@n-dx/core 0.1.0

package/packages/hench/dist/store/run-change-detector.js

@@ -0,0 +1,170 @@
+/**
+ * File change detection for hench run records.
+ *
+ * Tracks which `.hench/runs/*.json` files have been added, modified, or deleted
+ * since the last aggregation checkpoint. Enables efficient delta processing
+ * instead of full rebuilds on every aggregation pass.
+ *
+ * ## Design
+ *
+ * A checkpoint file (`.aggregation-checkpoint.json`) in the runs directory
+ * stores per-file metadata (mtime, size) from the last successful aggregation.
+ * On the next detection pass, the current filesystem state is compared against
+ * the checkpoint to produce a minimal set of changes.
+ *
+ * The checkpoint is intentionally stored alongside the run files rather than
+ * in a separate location — this keeps the aggregation state co-located with
+ * the data it describes and simplifies cleanup.
+ *
+ * @module hench/store/run-change-detector
+ */
+import { join } from "node:path";
+import { readFile, writeFile, readdir, stat } from "node:fs/promises";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CHECKPOINT_FILENAME = ".aggregation-checkpoint.json";
+// ---------------------------------------------------------------------------
+// RunChangeDetector
+// ---------------------------------------------------------------------------
+/**
+ * Detects changes to run files in a `.hench/runs/` directory by comparing
+ * the current filesystem state against a persisted checkpoint.
+ *
+ * Usage:
+ * ```ts
+ * const detector = new RunChangeDetector(runsDir);
+ * const { changes, checkpoint } = await detector.detectChanges();
+ *
+ * // Process only changed files...
+ * for (const change of changes) { ... }
+ *
+ * // Persist checkpoint after successful processing
+ * await detector.saveCheckpoint(checkpoint);
+ * ```
+ */
+export class RunChangeDetector {
+    runsDir;
+    checkpointPath;
+    constructor(runsDir) {
+        this.runsDir = runsDir;
+        this.checkpointPath = join(runsDir, CHECKPOINT_FILENAME);
+    }
+    // ---- Checkpoint I/O -----------------------------------------------------
+    /** Load the persisted checkpoint. Returns `null` if no checkpoint exists or it is invalid. */
+    async loadCheckpoint() {
+        try {
+            const raw = await readFile(this.checkpointPath, "utf-8");
+            const data = JSON.parse(raw);
+            if (!data || typeof data.timestamp !== "string" || typeof data.files !== "object") {
+                return null;
+            }
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Persist a checkpoint to disk. */
+    async saveCheckpoint(checkpoint) {
+        await writeFile(this.checkpointPath, JSON.stringify(checkpoint, null, 2), "utf-8");
+    }
+    // ---- Change detection ---------------------------------------------------
+    /**
+     * Compare current run files against the last checkpoint and return the
+     * set of changes (added / modified / deleted).
+     *
+     * The returned `checkpoint` reflects the **current** filesystem state and
+     * should be saved (via {@link saveCheckpoint}) only after the caller has
+     * successfully processed all changes.
+     */
+    async detectChanges() {
+        const previous = await this.loadCheckpoint();
+        const previousFiles = previous?.files ?? {};
+        // Scan current filesystem state
+        const currentFiles = await this.scanRunFiles();
+        const changes = [];
+        // Detect added and modified files
+        for (const [file, snapshot] of Object.entries(currentFiles)) {
+            const prev = previousFiles[file];
+            if (!prev) {
+                changes.push({ file, type: "added" });
+            }
+            else if (prev.mtimeMs !== snapshot.mtimeMs || prev.size !== snapshot.size) {
+                changes.push({ file, type: "modified" });
+            }
+        }
+        // Detect deleted files
+        for (const file of Object.keys(previousFiles)) {
+            if (!(file in currentFiles)) {
+                changes.push({ file, type: "deleted" });
+            }
+        }
+        // Sort for deterministic output
+        changes.sort((a, b) => a.file.localeCompare(b.file));
+        return {
+            changes,
+            checkpoint: {
+                timestamp: new Date().toISOString(),
+                files: currentFiles,
+            },
+        };
+    }
+    /**
+     * Convenience: returns `true` if there are any changes since the last checkpoint.
+     * Cheaper than building the full delta when you just need a boolean check.
+     */
+    async hasChanges() {
+        const { changes } = await this.detectChanges();
+        return changes.length > 0;
+    }
+    // ---- Static helpers -----------------------------------------------------
+    /** Extract only added and modified filenames from a delta result. */
+    static changedFiles(result) {
+        return result.changes
+            .filter((c) => c.type === "added" || c.type === "modified")
+            .map((c) => c.file);
+    }
+    /** Extract only deleted filenames from a delta result. */
+    static deletedFiles(result) {
+        return result.changes
+            .filter((c) => c.type === "deleted")
+            .map((c) => c.file);
+    }
+    // ---- Private ------------------------------------------------------------
+    /**
+     * Read the runs directory and build a snapshot map of all run files
+     * (`.json` and `.json.gz`), excluding the checkpoint file itself.
+     */
+    async scanRunFiles() {
+        const snapshots = {};
+        let files;
+        try {
+            files = await readdir(this.runsDir);
+        }
+        catch {
+            return snapshots;
+        }
+        const runFiles = files.filter((f) => (f.endsWith(".json") || f.endsWith(".json.gz")) &&
+            f !== CHECKPOINT_FILENAME &&
+            !f.startsWith("."));
+        // Stat files in parallel for performance
+        const entries = await Promise.all(runFiles.map(async (file) => {
+            try {
+                const st = await stat(join(this.runsDir, file));
+                return { file, snapshot: { mtimeMs: st.mtimeMs, size: st.size } };
+            }
+            catch {
+                // File disappeared between readdir and stat — skip
+                return null;
+            }
+        }));
+        for (const entry of entries) {
+            if (entry) {
+                snapshots[entry.file] = entry.snapshot;
+            }
+        }
+        return snapshots;
+    }
+}
+//# sourceMappingURL=run-change-detector.js.map

package/packages/hench/dist/store/run-change-detector.js.map

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

package/packages/hench/dist/store/run-retention-scheduler.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Periodic retention policy scheduler.
+ *
+ * Runs the retention policy on a configurable interval, automatically
+ * deleting very old run files while preserving usage statistics. Emits
+ * warnings for files approaching the retention cutoff so callers can
+ * notify users before data is removed.
+ *
+ * ## Design
+ *
+ * Follows the same scheduler pattern as `usage-cleanup-scheduler`
+ * in the web package: a `setInterval` timer that runs cleanup cycles,
+ * logs results, and optionally broadcasts events. The timer is unref'd
+ * so it won't prevent process exit.
+ *
+ * ## Configuration
+ *
+ * Reads from `.n-dx.json`:
+ * ```json
+ * {
+ *   "retention": {
+ *     "maxAgeDays": 180,
+ *     "enabled": true,
+ *     "warningDays": 30,
+ *     "preserveUsageStats": true,
+ *     "intervalMs": 86400000
+ *   }
+ * }
+ * ```
+ * Default interval: 86400000 ms (24 hours / daily).
+ *
+ * @module hench/store/run-retention-scheduler
+ */
+import { type RetentionResult } from "./run-retention.js";
+/** Default retention enforcement interval: 24 hours (daily). */
+export declare const DEFAULT_RETENTION_INTERVAL_MS: number;
+/** Callback invoked when files are approaching the retention cutoff. */
+export type WarningCallback = (warningFiles: string[], daysUntilDeletion: number) => void;
+/** Options for the retention scheduler. */
+export interface RetentionSchedulerOptions {
+    /** Path to the `.hench/runs/` directory. */
+    runsDir: string;
+    /** Project root directory (for config loading). */
+    projectDir: string;
+    /** Optional callback when files are approaching deletion. */
+    onWarning?: WarningCallback;
+    /** Optional callback for broadcast events (e.g., WebSocket). */
+    broadcast?: (data: unknown) => void;
+    /** Override interval for testing (takes precedence over config). */
+    overrideIntervalMs?: number;
+}
+/**
+ * Load the retention scheduler interval from `.n-dx.json`.
+ *
+ * Reads `retention.intervalMs`. Returns the default if missing or invalid.
+ */
+export declare function loadRetentionIntervalMs(projectDir: string): Promise<number>;
+/**
+ * Execute a single retention enforcement cycle.
+ *
+ * Loads configuration, enforces the policy, logs results, and invokes
+ * callbacks for warnings and broadcasts.
+ *
+ * @returns The retention result, or `null` if an error occurred.
+ */
+export declare function runRetentionCycle(options: RetentionSchedulerOptions): Promise<RetentionResult | null>;
+/**
+ * Start the periodic retention policy scheduler.
+ *
+ * Runs retention enforcement on a configurable interval (read from
+ * `.n-dx.json`, default daily). Each cycle identifies old run files,
+ * preserves their usage statistics, and deletes them. Files approaching
+ * the retention cutoff trigger warnings via the `onWarning` callback.
+ *
+ * The timer is unref'd so it won't prevent process exit.
+ *
+ * @param options Scheduler configuration.
+ * @returns The setInterval handle for cleanup during shutdown.
+ */
+export declare function startRetentionScheduler(options: RetentionSchedulerOptions): Promise<ReturnType<typeof setInterval>>;

package/packages/hench/dist/store/run-retention-scheduler.js

@@ -0,0 +1,143 @@
+/**
+ * Periodic retention policy scheduler.
+ *
+ * Runs the retention policy on a configurable interval, automatically
+ * deleting very old run files while preserving usage statistics. Emits
+ * warnings for files approaching the retention cutoff so callers can
+ * notify users before data is removed.
+ *
+ * ## Design
+ *
+ * Follows the same scheduler pattern as `usage-cleanup-scheduler`
+ * in the web package: a `setInterval` timer that runs cleanup cycles,
+ * logs results, and optionally broadcasts events. The timer is unref'd
+ * so it won't prevent process exit.
+ *
+ * ## Configuration
+ *
+ * Reads from `.n-dx.json`:
+ * ```json
+ * {
+ *   "retention": {
+ *     "maxAgeDays": 180,
+ *     "enabled": true,
+ *     "warningDays": 30,
+ *     "preserveUsageStats": true,
+ *     "intervalMs": 86400000
+ *   }
+ * }
+ * ```
+ * Default interval: 86400000 ms (24 hours / daily).
+ *
+ * @module hench/store/run-retention-scheduler
+ */
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { enforceRetentionPolicy, loadRetentionConfig, } from "./run-retention.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default retention enforcement interval: 24 hours (daily). */
+export const DEFAULT_RETENTION_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Scheduler interval configuration
+// ---------------------------------------------------------------------------
+/**
+ * Load the retention scheduler interval from `.n-dx.json`.
+ *
+ * Reads `retention.intervalMs`. Returns the default if missing or invalid.
+ */
+export async function loadRetentionIntervalMs(projectDir) {
+    try {
+        const raw = await readFile(join(projectDir, ".n-dx.json"), "utf-8");
+        const data = JSON.parse(raw);
+        const section = data.retention;
+        if (section &&
+            typeof section === "object" &&
+            typeof section.intervalMs === "number" &&
+            section.intervalMs > 0) {
+            return section.intervalMs;
+        }
+    }
+    catch {
+        // Fall through to default
+    }
+    return DEFAULT_RETENTION_INTERVAL_MS;
+}
+// ---------------------------------------------------------------------------
+// Single cycle execution
+// ---------------------------------------------------------------------------
+/**
+ * Execute a single retention enforcement cycle.
+ *
+ * Loads configuration, enforces the policy, logs results, and invokes
+ * callbacks for warnings and broadcasts.
+ *
+ * @returns The retention result, or `null` if an error occurred.
+ */
+export async function runRetentionCycle(options) {
+    const { runsDir, projectDir, onWarning, broadcast } = options;
+    try {
+        const config = await loadRetentionConfig(projectDir);
+        const logPath = join(projectDir, ".hench", "retention-stats.jsonl");
+        const result = await enforceRetentionPolicy(runsDir, config, undefined, logPath);
+        // Emit warnings for files approaching deletion
+        if (onWarning && result.warningFiles.length > 0) {
+            onWarning(result.warningFiles, config.warningDays);
+        }
+        // Broadcast so dashboard/consumers know retention ran
+        if (broadcast) {
+            broadcast({
+                type: "hench:retention-cleanup",
+                filesDeleted: result.filesDeleted,
+                filesSkipped: result.filesSkipped,
+                warningFiles: result.warningFiles,
+                preservedStats: result.preservedStats,
+            });
+        }
+        return result;
+    }
+    catch (err) {
+        // Non-fatal: retention errors must not crash the host process
+        console.error("[retention] Error during retention cycle:", err);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Scheduler
+// ---------------------------------------------------------------------------
+/**
+ * Start the periodic retention policy scheduler.
+ *
+ * Runs retention enforcement on a configurable interval (read from
+ * `.n-dx.json`, default daily). Each cycle identifies old run files,
+ * preserves their usage statistics, and deletes them. Files approaching
+ * the retention cutoff trigger warnings via the `onWarning` callback.
+ *
+ * The timer is unref'd so it won't prevent process exit.
+ *
+ * @param options Scheduler configuration.
+ * @returns The setInterval handle for cleanup during shutdown.
+ */
+export async function startRetentionScheduler(options) {
+    const intervalMs = options.overrideIntervalMs ??
+        (await loadRetentionIntervalMs(options.projectDir));
+    const timer = setInterval(async () => {
+        const result = await runRetentionCycle(options);
+        if (result && result.filesDeleted > 0) {
+            console.log(`[retention] Deleted ${result.filesDeleted} run file(s) older than retention threshold.` +
+                (result.preservedStats
+                    ? ` Preserved ${result.preservedStats.totalRuns} run(s) usage stats ` +
+                        `(${result.preservedStats.totalInputTokens + result.preservedStats.totalOutputTokens} total tokens).`
+                    : ""));
+        }
+        if (result && result.warningFiles.length > 0) {
+            console.log(`[retention] Warning: ${result.warningFiles.length} run file(s) approaching retention cutoff.`);
+        }
+    }, intervalMs);
+    if (timer.unref) {
+        timer.unref();
+    }
+    return timer;
+}
+//# sourceMappingURL=run-retention-scheduler.js.map

package/packages/hench/dist/store/run-retention-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-retention-scheduler.js","sourceRoot":"","sources":["../../src/store/run-retention-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,GAGpB,MAAM,oBAAoB,CAAC;AAE5B,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA0BjE,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAAkB;IAElB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACxD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAgD,CAAC;QACtE,IACE,OAAO;YACP,OAAO,OAAO,KAAK,QAAQ;YAC3B,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACtC,OAAO,CAAC,UAAU,GAAG,CAAC,EACtB,CAAC;YACD,OAAO,OAAO,CAAC,UAAU,CAAC;QAC5B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IACD,OAAO,6BAA6B,CAAC;AACvC,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAkC;IAElC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,uBAAuB,CAAC,CAAC;QAEpE,MAAM,MAAM,GAAG,MAAM,sBAAsB,CACzC,OAAO,EACP,MAAM,EACN,SAAS,EACT,OAAO,CACR,CAAC;QAEF,+CAA+C;QAC/C,IAAI,SAAS,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,SAAS,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QACrD,CAAC;QAED,sDAAsD;QACtD,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,CAAC;gBACR,IAAI,EAAE,yBAAyB;gBAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,cAAc,EAAE,MAAM,CAAC,cAAc;aACtC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8DAA8D;QAC9D,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,GAAG,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAkC;IAElC,MAAM,UAAU,GACd,OAAO,CAAC,kBAAkB;QAC1B,CAAC,MAAM,uBAAuB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACnC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEhD,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACtC,OAAO,CAAC,GAAG,CACT,uBAAuB,MAAM,CAAC,YAAY,8CAA8C;gBACtF,CAAC,MAAM,CAAC,cAAc;oBACpB,CAAC,CAAC,cAAc,MAAM,CAAC,cAAc,CAAC,SAAS,sBAAsB;wBACnE,IAAI,MAAM,CAAC,cAAc,CAAC,gBAAgB,GAAG,MAAM,CAAC,cAAc,CAAC,iBAAiB,iBAAiB;oBACvG,CAAC,CAAC,EAAE,CAAC,CACV,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,GAAG,CACT,wBAAwB,MAAM,CAAC,YAAY,CAAC,MAAM,4CAA4C,CAC/F,CAAC;QACJ,CAAC;IACH,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/hench/dist/store/run-retention.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Run history retention policies.
+ *
+ * Configurable retention policies that automatically remove very old run
+ * files (both `.json` and `.json.gz`) while preserving aggregated usage
+ * statistics. Operates at a longer time horizon than archival (default
+ * 6 months vs 30 days) — archival compresses, retention deletes.
+ *
+ * ## Design
+ *
+ * Before deleting any files, the module extracts and aggregates token
+ * usage statistics into a summary record written to a JSONL audit log.
+ * This ensures that historical usage data is never lost, even after
+ * individual run files are removed.
+ *
+ * A warning system identifies files approaching the retention cutoff
+ * so callers can notify users before data is deleted.
+ *
+ * Configuration lives in `.n-dx.json` under the `retention` key.
+ *
+ * @module hench/store/run-retention
+ */
+/** Configuration for run history retention policies. */
+export interface RetentionConfig {
+    /** Number of days after which run files are eligible for deletion. */
+    maxAgeDays: number;
+    /** Whether retention enforcement is enabled. */
+    enabled: boolean;
+    /** Number of days before `maxAgeDays` to start warning users. */
+    warningDays: number;
+    /** Whether to extract and preserve usage stats before deleting runs. */
+    preserveUsageStats: boolean;
+}
+/** Aggregated usage statistics preserved from deleted run files. */
+export interface PreservedUsageStats {
+    /** Total input tokens across all deleted runs. */
+    totalInputTokens: number;
+    /** Total output tokens across all deleted runs. */
+    totalOutputTokens: number;
+    /** Total cache creation tokens across all deleted runs. */
+    totalCacheCreationTokens: number;
+    /** Total cache read tokens across all deleted runs. */
+    totalCacheReadTokens: number;
+    /** Total number of deleted run files. */
+    totalRuns: number;
+    /** Total turns across all deleted runs. */
+    totalTurns: number;
+    /** Unique task IDs that had runs deleted. */
+    taskIds: string[];
+    /** Files that could not be read (filename → error message). */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/** Summary of a retention enforcement pass. */
+export interface RetentionResult {
+    /** Number of files deleted. */
+    filesDeleted: number;
+    /** Number of files kept (too recent for deletion). */
+    filesSkipped: number;
+    /** Files in the warning window (approaching deletion). */
+    warningFiles: string[];
+    /** Aggregated usage stats preserved before deletion (if enabled). */
+    preservedStats?: PreservedUsageStats;
+    /** Files that failed to delete (filename → error message). */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/** Persistent log entry written to the retention JSONL audit file. */
+export interface RetentionLogEntry {
+    event: "retention_cleanup";
+    timestamp: string;
+    filesDeleted: number;
+    filesSkipped: number;
+    warningFiles: string[];
+    preservedStats?: PreservedUsageStats;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+export declare const DEFAULT_RETENTION_CONFIG: RetentionConfig;
+/**
+ * Load retention configuration from `.n-dx.json`.
+ *
+ * Reads the `retention` section from the project config file. Missing
+ * or invalid fields fall back to {@link DEFAULT_RETENTION_CONFIG}.
+ *
+ * @param projectDir Project root directory containing `.n-dx.json`.
+ */
+export declare function loadRetentionConfig(projectDir: string): Promise<RetentionConfig>;
+/**
+ * Identify run files eligible for deletion (older than `maxAgeDays`).
+ *
+ * Checks both `.json` and `.json.gz` files. Hidden files are excluded.
+ *
+ * @param runsDir Path to the `.hench/runs/` directory.
+ * @param maxAgeDays Threshold in days.
+ * @param now Optional reference time (for testing). Defaults to `Date.now()`.
+ * @returns Array of filenames eligible for deletion, sorted.
+ */
+export declare function identifyRetainableRuns(runsDir: string, maxAgeDays: number, now?: number): Promise<string[]>;
+/**
+ * Identify run files in the warning window (approaching deletion but
+ * not yet eligible).
+ *
+ * A file is in the warning window if its age is between
+ * `(maxAgeDays - warningDays)` and `maxAgeDays`.
+ *
+ * @param runsDir Path to the `.hench/runs/` directory.
+ * @param maxAgeDays Deletion threshold in days.
+ * @param warningDays Warning lead time in days.
+ * @param now Optional reference time (for testing). Defaults to `Date.now()`.
+ * @returns Array of filenames in the warning window, sorted.
+ */
+export declare function identifyWarningRuns(runsDir: string, maxAgeDays: number, warningDays: number, now?: number): Promise<string[]>;
+/**
+ * Extract and aggregate token usage statistics from a set of run files.
+ *
+ * Reads each file, extracts `tokenUsage` and metadata, and aggregates
+ * into a summary. Files that cannot be read are recorded in the `errors`
+ * array but do not abort the operation.
+ *
+ * @param runsDir Path to the runs directory.
+ * @param files Array of filenames to extract stats from.
+ * @returns Aggregated usage statistics.
+ */
+export declare function extractUsageStats(runsDir: string, files: string[]): Promise<PreservedUsageStats>;
+/**
+ * Enforce the retention policy by deleting old run files.
+ *
+ * Scans the `runs/` directory, identifies files older than the configured
+ * threshold, optionally extracts and preserves aggregated usage statistics,
+ * then deletes the old files. Also identifies files in the warning window
+ * for user notification.
+ *
+ * All token usage metadata is aggregated and preserved in the retention
+ * audit log before any files are removed, ensuring usage statistics are
+ * never permanently lost.
+ *
+ * @param runsDir Path to the `.hench/runs/` directory.
+ * @param config Retention configuration.
+ * @param now Optional reference time (for testing).
+ * @param logPath Optional path for the JSONL retention audit log.
+ * @returns Summary of the retention operation.
+ */
+export declare function enforceRetentionPolicy(runsDir: string, config?: RetentionConfig, now?: number, logPath?: string): Promise<RetentionResult>;