@n-dx/core 0.1.0

package/packages/hench/dist/process/process-memory-tracker.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Per-process memory tracking with history and high-RSS warnings.
+ *
+ * Collects time-series RSS samples for individual hench task processes
+ * and stores them in bounded ring buffers. Flags processes whose RSS
+ * exceeds a configurable threshold.
+ *
+ * Key differences from sibling modules:
+ * - **SystemMemoryMonitor** — system-wide memory readings + pre-spawn gating
+ * - **MemoryThrottle** — entry-gate decision engine (delay/reject)
+ * - **ProcessMemoryTracker** — per-process historical tracking + RSS warnings
+ *
+ * @module hench/process/process-memory-tracker
+ */
+/**
+ * Configuration for the process memory tracker.
+ */
+export interface ProcessMemoryTrackerConfig {
+    /** Maximum samples per process ring buffer. */
+    maxSamples: number;
+    /** Maximum completed histories retained after process ends. */
+    maxCompletedHistories: number;
+    /** RSS threshold in bytes — processes exceeding this are flagged. */
+    rssWarningBytes: number;
+}
+/** Default process memory tracker configuration. */
+export declare const DEFAULT_PROCESS_MEMORY_TRACKER_CONFIG: ProcessMemoryTrackerConfig;
+/**
+ * A single memory sample for a tracked process.
+ */
+export interface ProcessMemorySample {
+    /** Process RSS in bytes. */
+    rssBytes: number;
+    /** ISO timestamp of the sample. */
+    timestamp: string;
+    /** Epoch milliseconds (for efficient time-delta calculations). */
+    epochMs: number;
+}
+/**
+ * Memory trend summary for a tracked process.
+ */
+export interface MemoryTrend {
+    /** Whether RSS exceeds the warning threshold. */
+    isLeaking: boolean;
+    /** Human-readable description. */
+    description: string;
+}
+/**
+ * Full memory history for a single tracked process.
+ */
+export interface ProcessMemoryHistory {
+    /** Task ID this process is executing. */
+    taskId: string;
+    /** Human-readable task title. */
+    taskTitle: string;
+    /** Process ID. */
+    pid: number;
+    /** Ordered time-series samples (oldest first). */
+    samples: ProcessMemorySample[];
+    /** When tracking started for this process. */
+    startedAt: string;
+    /** When the process ended (undefined if still running). */
+    endedAt?: string;
+    /** Memory trend (undefined if no samples yet). */
+    trend?: MemoryTrend;
+    /** Peak RSS observed across all samples (bytes). */
+    peakRssBytes: number;
+    /** Most recent RSS (bytes). */
+    currentRssBytes: number;
+}
+/**
+ * Warning report for a process exceeding the RSS threshold.
+ */
+export interface LeakReport {
+    /** Task ID. */
+    taskId: string;
+    /** Task title. */
+    taskTitle: string;
+    /** Process ID. */
+    pid: number;
+    /** Memory trend. */
+    trend: MemoryTrend;
+    /** Current RSS in bytes. */
+    currentRssBytes: number;
+    /** Peak RSS in bytes. */
+    peakRssBytes: number;
+    /** Duration the process has been tracked (seconds). */
+    trackingDurationSec: number;
+    /** ISO timestamp of this report. */
+    timestamp: string;
+}
+/**
+ * Summary of all tracked processes and any warnings.
+ */
+export interface LeakDetectionSummary {
+    /** Total processes currently being tracked. */
+    activeProcesses: number;
+    /** Total completed histories retained. */
+    completedProcesses: number;
+    /** Processes flagged for high RSS. */
+    leaks: LeakReport[];
+    /** Overall health assessment. */
+    health: "healthy" | "warning";
+    /** ISO timestamp. */
+    timestamp: string;
+}
+/**
+ * Tracks per-process memory usage over time for hench task processes.
+ *
+ * Each tracked process gets a bounded ring buffer of RSS samples.
+ * Processes whose RSS exceeds a configurable threshold are flagged.
+ *
+ * Completed processes are retained (up to `maxCompletedHistories`) so
+ * post-mortem analysis is available for recently finished tasks.
+ *
+ * @example
+ * ```ts
+ * const tracker = new ProcessMemoryTracker();
+ *
+ * // Record samples during periodic monitoring
+ * tracker.recordSample("task-123", "Fix bug", 45678, 52_428_800);
+ *
+ * // Check for high-RSS processes
+ * const summary = tracker.detectLeaks();
+ * if (summary.leaks.length > 0) {
+ *   console.warn("High RSS detected:", summary.leaks);
+ * }
+ * ```
+ */
+export declare class ProcessMemoryTracker {
+    private readonly _config;
+    private readonly _active;
+    private readonly _completed;
+    private readonly _now;
+    constructor(config?: Partial<ProcessMemoryTrackerConfig>, overrides?: {
+        now?: () => number;
+    });
+    get config(): Readonly<ProcessMemoryTrackerConfig>;
+    get activeCount(): number;
+    get completedCount(): number;
+    /**
+     * Record a memory sample for a process.
+     *
+     * Creates a new tracking entry if this is the first sample for the
+     * given taskId. Appends to the ring buffer, evicting the oldest
+     * sample when full.
+     */
+    recordSample(taskId: string, taskTitle: string, pid: number, rssBytes: number): void;
+    markCompleted(taskId: string): void;
+    remove(taskId: string): void;
+    getHistory(taskId: string): ProcessMemoryHistory | undefined;
+    getAllHistories(): ProcessMemoryHistory[];
+    getActiveHistories(): ProcessMemoryHistory[];
+    /**
+     * Check all active processes for high RSS.
+     *
+     * A process is flagged when its current RSS exceeds `rssWarningBytes`.
+     */
+    detectLeaks(): LeakDetectionSummary;
+    getLeakAlerts(): LeakReport[];
+    reset(): void;
+    private _computeTrend;
+    private _buildHistory;
+}

package/packages/hench/dist/process/process-memory-tracker.js

@@ -0,0 +1,249 @@
+/**
+ * Per-process memory tracking with history and high-RSS warnings.
+ *
+ * Collects time-series RSS samples for individual hench task processes
+ * and stores them in bounded ring buffers. Flags processes whose RSS
+ * exceeds a configurable threshold.
+ *
+ * Key differences from sibling modules:
+ * - **SystemMemoryMonitor** — system-wide memory readings + pre-spawn gating
+ * - **MemoryThrottle** — entry-gate decision engine (delay/reject)
+ * - **ProcessMemoryTracker** — per-process historical tracking + RSS warnings
+ *
+ * @module hench/process/process-memory-tracker
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum samples retained per process (ring buffer size). */
+const DEFAULT_MAX_SAMPLES = 360;
+/** Maximum number of completed process histories to retain. */
+const DEFAULT_MAX_COMPLETED_HISTORIES = 20;
+/** Default RSS warning threshold: 512 MB. */
+const DEFAULT_RSS_WARNING_BYTES = 512 * 1024 * 1024;
+/** Default process memory tracker configuration. */
+export const DEFAULT_PROCESS_MEMORY_TRACKER_CONFIG = {
+    maxSamples: DEFAULT_MAX_SAMPLES,
+    maxCompletedHistories: DEFAULT_MAX_COMPLETED_HISTORIES,
+    rssWarningBytes: DEFAULT_RSS_WARNING_BYTES,
+};
+// ---------------------------------------------------------------------------
+// ProcessMemoryTracker
+// ---------------------------------------------------------------------------
+/**
+ * Tracks per-process memory usage over time for hench task processes.
+ *
+ * Each tracked process gets a bounded ring buffer of RSS samples.
+ * Processes whose RSS exceeds a configurable threshold are flagged.
+ *
+ * Completed processes are retained (up to `maxCompletedHistories`) so
+ * post-mortem analysis is available for recently finished tasks.
+ *
+ * @example
+ * ```ts
+ * const tracker = new ProcessMemoryTracker();
+ *
+ * // Record samples during periodic monitoring
+ * tracker.recordSample("task-123", "Fix bug", 45678, 52_428_800);
+ *
+ * // Check for high-RSS processes
+ * const summary = tracker.detectLeaks();
+ * if (summary.leaks.length > 0) {
+ *   console.warn("High RSS detected:", summary.leaks);
+ * }
+ * ```
+ */
+export class ProcessMemoryTracker {
+    _config;
+    _active = new Map();
+    _completed = [];
+    _now;
+    constructor(config, overrides) {
+        this._config = { ...DEFAULT_PROCESS_MEMORY_TRACKER_CONFIG, ...config };
+        this._now = overrides?.now ?? Date.now;
+    }
+    get config() {
+        return { ...this._config };
+    }
+    get activeCount() {
+        return this._active.size;
+    }
+    get completedCount() {
+        return this._completed.length;
+    }
+    // -----------------------------------------------------------------------
+    // Sample recording
+    // -----------------------------------------------------------------------
+    /**
+     * Record a memory sample for a process.
+     *
+     * Creates a new tracking entry if this is the first sample for the
+     * given taskId. Appends to the ring buffer, evicting the oldest
+     * sample when full.
+     */
+    recordSample(taskId, taskTitle, pid, rssBytes) {
+        const now = this._now();
+        const sample = {
+            rssBytes,
+            timestamp: new Date(now).toISOString(),
+            epochMs: now,
+        };
+        let tracked = this._active.get(taskId);
+        if (!tracked) {
+            tracked = {
+                taskId,
+                taskTitle,
+                pid,
+                samples: [],
+                startedAt: sample.timestamp,
+                peakRssBytes: rssBytes,
+                active: true,
+            };
+            this._active.set(taskId, tracked);
+        }
+        tracked.pid = pid;
+        if (tracked.samples.length >= this._config.maxSamples) {
+            tracked.samples.shift();
+        }
+        tracked.samples.push(sample);
+        if (rssBytes > tracked.peakRssBytes) {
+            tracked.peakRssBytes = rssBytes;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Process lifecycle
+    // -----------------------------------------------------------------------
+    markCompleted(taskId) {
+        const tracked = this._active.get(taskId);
+        if (!tracked)
+            return;
+        tracked.active = false;
+        tracked.endedAt = new Date(this._now()).toISOString();
+        this._active.delete(taskId);
+        this._completed.push(tracked);
+        while (this._completed.length > this._config.maxCompletedHistories) {
+            this._completed.shift();
+        }
+    }
+    remove(taskId) {
+        this._active.delete(taskId);
+    }
+    // -----------------------------------------------------------------------
+    // History queries
+    // -----------------------------------------------------------------------
+    getHistory(taskId) {
+        const tracked = this._active.get(taskId) ??
+            this._completed.find((p) => p.taskId === taskId);
+        if (!tracked)
+            return undefined;
+        return this._buildHistory(tracked);
+    }
+    getAllHistories() {
+        const all = [];
+        for (const tracked of this._active.values()) {
+            all.push(this._buildHistory(tracked));
+        }
+        for (const tracked of this._completed) {
+            all.push(this._buildHistory(tracked));
+        }
+        return all;
+    }
+    getActiveHistories() {
+        const result = [];
+        for (const tracked of this._active.values()) {
+            result.push(this._buildHistory(tracked));
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Leak detection (simplified: RSS threshold check)
+    // -----------------------------------------------------------------------
+    /**
+     * Check all active processes for high RSS.
+     *
+     * A process is flagged when its current RSS exceeds `rssWarningBytes`.
+     */
+    detectLeaks() {
+        const leaks = [];
+        for (const tracked of this._active.values()) {
+            const samples = tracked.samples;
+            const currentRss = samples[samples.length - 1]?.rssBytes ?? 0;
+            if (currentRss < this._config.rssWarningBytes)
+                continue;
+            const firstSample = samples[0];
+            const lastSample = samples[samples.length - 1];
+            const durationSec = firstSample && lastSample
+                ? (lastSample.epochMs - firstSample.epochMs) / 1000
+                : 0;
+            const currentMB = Math.round(currentRss / 1024 / 1024);
+            const thresholdMB = Math.round(this._config.rssWarningBytes / 1024 / 1024);
+            leaks.push({
+                taskId: tracked.taskId,
+                taskTitle: tracked.taskTitle,
+                pid: tracked.pid,
+                trend: {
+                    isLeaking: true,
+                    description: `RSS ${currentMB}MB exceeds ${thresholdMB}MB threshold`,
+                },
+                currentRssBytes: currentRss,
+                peakRssBytes: tracked.peakRssBytes,
+                trackingDurationSec: Math.round(durationSec),
+                timestamp: new Date().toISOString(),
+            });
+        }
+        return {
+            activeProcesses: this._active.size,
+            completedProcesses: this._completed.length,
+            leaks,
+            health: leaks.length > 0 ? "warning" : "healthy",
+            timestamp: new Date().toISOString(),
+        };
+    }
+    getLeakAlerts() {
+        return this.detectLeaks().leaks;
+    }
+    // -----------------------------------------------------------------------
+    // Reset
+    // -----------------------------------------------------------------------
+    reset() {
+        this._active.clear();
+        this._completed.length = 0;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    _computeTrend(tracked) {
+        const samples = tracked.samples;
+        if (samples.length === 0)
+            return undefined;
+        const currentRss = samples[samples.length - 1].rssBytes;
+        const currentMB = Math.round(currentRss / 1024 / 1024);
+        if (currentRss >= this._config.rssWarningBytes) {
+            const thresholdMB = Math.round(this._config.rssWarningBytes / 1024 / 1024);
+            return {
+                isLeaking: true,
+                description: `RSS ${currentMB}MB exceeds ${thresholdMB}MB threshold`,
+            };
+        }
+        return {
+            isLeaking: false,
+            description: `RSS ${currentMB}MB — within normal range`,
+        };
+    }
+    _buildHistory(tracked) {
+        const samples = tracked.samples;
+        const lastSample = samples[samples.length - 1];
+        return {
+            taskId: tracked.taskId,
+            taskTitle: tracked.taskTitle,
+            pid: tracked.pid,
+            samples: [...samples],
+            startedAt: tracked.startedAt,
+            endedAt: tracked.endedAt,
+            trend: this._computeTrend(tracked),
+            peakRssBytes: tracked.peakRssBytes,
+            currentRssBytes: lastSample?.rssBytes ?? 0,
+        };
+    }
+}
+//# sourceMappingURL=process-memory-tracker.js.map

package/packages/hench/dist/process/process-memory-tracker.js.map

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

package/packages/hench/dist/public.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Public API for the hench package.
+ *
+ * ## API philosophy: types + schema constants + config factory
+ *
+ * Hench is a **CLI tool**, not a library. Other packages interact with it
+ * exclusively through:
+ *
+ * 1. **Subprocess spawning** — `cli.js` and `web.js` invoke `hench run`
+ * 2. **Filesystem reads** — the web dashboard and rex's token-usage module
+ *    read `.hench/config.json` and `.hench/runs/*.json` directly from disk
+ *
+ * This public API exports types, schema constants, and the default config
+ * factory — enough for consumers to validate JSON file shapes at compile
+ * time and generate default configurations without creating unnecessary
+ * runtime coupling to the agent engine.
+ *
+ * Each package's public surface reflects its actual consumption pattern —
+ * see PACKAGE_GUIDELINES.md for the full decision tree.
+ *
+ * Runtime functions (agent loops, tool dispatch, guard rails) are
+ * intentionally kept internal. Consumers should use the CLI binary
+ * rather than calling hench as a library.
+ *
+ * @module hench/public
+ */
+export { HENCH_SCHEMA_VERSION, DEFAULT_HENCH_CONFIG } from "./schema/v1.js";
+export type { HenchConfig, GuardConfig, PolicyLimitsConfig, MemoryThrottleConfig, MemoryMonitorConfig, RuntimePoolConfig, RetryConfig, Provider, RunRecord, RunStatus, ToolCallRecord, TokenUsage, TurnTokenUsage, CommandRecord, TestRecord, SummaryCounts, PostRunTestRecord, RunSummaryData, } from "./schema/v1.js";
+export type { TaskBrief, TaskBriefTask, TaskBriefParent, TaskBriefSibling, TaskBriefProject, TaskBriefLogEntry, } from "./schema/v1.js";
+export { BUILT_IN_TEMPLATES } from "./schema/templates.js";
+export type { WorkflowTemplate, TemplateConfigOverlay, } from "./schema/templates.js";
+export { DEFAULT_ADAPTIVE_SETTINGS } from "./agent/analysis/adaptive.js";
+export type { AdaptiveSettings, AdjustmentCategory, AdjustmentPriority, ProjectMetrics, WorkflowAdjustment, AdjustmentNotification, AdaptiveAnalysis, } from "./agent/analysis/adaptive.js";
+export { ExecutionQueue, normalizePriority } from "./queue/index.js";
+export type { TaskPriority, QueueEntry, QueueStatus, } from "./queue/index.js";
+export { resolveSchedulingPriority, extractPriorityFromTags } from "./queue/index.js";
+export type { TaskPriorityMetadata, } from "./queue/index.js";
+export { ProcessLimiter, ProcessLimitReachedError } from "./process/limiter.js";
+export { ProcessLifecycleValidator, LifecycleAuditTrail } from "./process/lifecycle.js";
+export type { LifecycleEvent, TerminationReport, OrphanReport, ResourceSnapshot, ResourceThresholds, ProcessLifecycleValidatorOptions, } from "./process/lifecycle.js";
+export { MemoryThrottle, MemoryThrottleRejectError, DEFAULT_MEMORY_THROTTLE_CONFIG, } from "./process/memory-throttle.js";
+export type { MemoryThrottleStatus, ThrottleDecision, } from "./process/memory-throttle.js";
+export { SystemMemoryMonitor, DEFAULT_MEMORY_MONITOR_CONFIG, } from "./process/memory-monitor.js";
+export type { SystemMemorySnapshot, SpawnMemoryCheck, } from "./process/memory-monitor.js";
+export { RuntimePool, PoolExhaustedError, DEFAULT_RUNTIME_POOL_CONFIG, } from "./process/pool.js";
+export type { WorkerHandle, WorkerFactory, WorkerState, PooledRuntime, PooledRuntimeInfo, RuntimePoolStatus, } from "./process/pool.js";
+export { ProcessMemoryTracker, DEFAULT_PROCESS_MEMORY_TRACKER_CONFIG, } from "./process/process-memory-tracker.js";
+export type { ProcessMemoryTrackerConfig, ProcessMemorySample, MemoryTrend, ProcessMemoryHistory, LeakReport, LeakDetectionSummary, } from "./process/process-memory-tracker.js";
+export { ConcurrentExecutionMetrics, DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG, } from "./process/concurrent-execution-metrics.js";
+export type { ConcurrentExecutionMetricsConfig, ExecutionMetricsSnapshot, TaskResourceMetrics, UtilizationPatterns, ExecutionMetricsSummary, } from "./process/concurrent-execution-metrics.js";
+export { RunChangeDetector } from "./store/run-change-detector.js";
+export type { FileSnapshot, AggregationCheckpoint, RunFileChange, DeltaResult, } from "./store/run-change-detector.js";
+export { archiveOldRuns, identifyArchivableRuns, compressRunFile, readCompressedJSON, loadArchivalConfig, DEFAULT_ARCHIVAL_CONFIG, } from "./store/run-archiver.js";
+export type { ArchivalConfig, ArchivalResult, CompressedFileResult, } from "./store/run-archiver.js";
+export { enforceRetentionPolicy, identifyRetainableRuns, identifyWarningRuns, extractUsageStats, loadRetentionConfig, DEFAULT_RETENTION_CONFIG, } from "./store/run-retention.js";
+export type { RetentionConfig, RetentionResult, PreservedUsageStats, RetentionLogEntry, } from "./store/run-retention.js";
+export { startRetentionScheduler, runRetentionCycle, loadRetentionIntervalMs, DEFAULT_RETENTION_INTERVAL_MS, } from "./store/run-retention-scheduler.js";
+export type { WarningCallback, RetentionSchedulerOptions, } from "./store/run-retention-scheduler.js";
+export type { AgentLoopOptions, AgentLoopResult } from "./agent/lifecycle/loop.js";
+export type { CliLoopOptions, CliLoopResult } from "./agent/lifecycle/cli-loop.js";
+export type { TokenBudgetResult } from "./agent/lifecycle/token-budget.js";
+export type { CompletionValidationResult, CompletionValidationOptions } from "./validation/completion.js";

package/packages/hench/dist/public.js

@@ -0,0 +1,58 @@
+/**
+ * Public API for the hench package.
+ *
+ * ## API philosophy: types + schema constants + config factory
+ *
+ * Hench is a **CLI tool**, not a library. Other packages interact with it
+ * exclusively through:
+ *
+ * 1. **Subprocess spawning** — `cli.js` and `web.js` invoke `hench run`
+ * 2. **Filesystem reads** — the web dashboard and rex's token-usage module
+ *    read `.hench/config.json` and `.hench/runs/*.json` directly from disk
+ *
+ * This public API exports types, schema constants, and the default config
+ * factory — enough for consumers to validate JSON file shapes at compile
+ * time and generate default configurations without creating unnecessary
+ * runtime coupling to the agent engine.
+ *
+ * Each package's public surface reflects its actual consumption pattern —
+ * see PACKAGE_GUIDELINES.md for the full decision tree.
+ *
+ * Runtime functions (agent loops, tool dispatch, guard rails) are
+ * intentionally kept internal. Consumers should use the CLI binary
+ * rather than calling hench as a library.
+ *
+ * @module hench/public
+ */
+// ---- Schema constants & config factory ------------------------------------
+export { HENCH_SCHEMA_VERSION, DEFAULT_HENCH_CONFIG } from "./schema/v1.js";
+// ---- Workflow template types -----------------------------------------------
+export { BUILT_IN_TEMPLATES } from "./schema/templates.js";
+// ---- Adaptive workflow adjustment types ------------------------------------
+export { DEFAULT_ADAPTIVE_SETTINGS } from "./agent/analysis/adaptive.js";
+// ---- Execution queue -------------------------------------------------------
+export { ExecutionQueue, normalizePriority } from "./queue/index.js";
+// ---- Priority scheduling ---------------------------------------------------
+export { resolveSchedulingPriority, extractPriorityFromTags } from "./queue/index.js";
+// ---- Process concurrency limiter -------------------------------------------
+export { ProcessLimiter, ProcessLimitReachedError } from "./process/limiter.js";
+// ---- Process lifecycle validation ------------------------------------------
+export { ProcessLifecycleValidator, LifecycleAuditTrail } from "./process/lifecycle.js";
+// ---- Memory throttle --------------------------------------------------------
+export { MemoryThrottle, MemoryThrottleRejectError, DEFAULT_MEMORY_THROTTLE_CONFIG, } from "./process/memory-throttle.js";
+// ---- System memory monitor --------------------------------------------------
+export { SystemMemoryMonitor, DEFAULT_MEMORY_MONITOR_CONFIG, } from "./process/memory-monitor.js";
+// ---- Runtime process pool ---------------------------------------------------
+export { RuntimePool, PoolExhaustedError, DEFAULT_RUNTIME_POOL_CONFIG, } from "./process/pool.js";
+// ---- Process memory tracking -------------------------------------------------
+export { ProcessMemoryTracker, DEFAULT_PROCESS_MEMORY_TRACKER_CONFIG, } from "./process/process-memory-tracker.js";
+// ---- Concurrent execution metrics -------------------------------------------
+export { ConcurrentExecutionMetrics, DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG, } from "./process/concurrent-execution-metrics.js";
+// ---- Run file change detection ----------------------------------------------
+export { RunChangeDetector } from "./store/run-change-detector.js";
+// ---- Run file archival ------------------------------------------------------
+export { archiveOldRuns, identifyArchivableRuns, compressRunFile, readCompressedJSON, loadArchivalConfig, DEFAULT_ARCHIVAL_CONFIG, } from "./store/run-archiver.js";
+// ---- Run history retention ---------------------------------------------------
+export { enforceRetentionPolicy, identifyRetainableRuns, identifyWarningRuns, extractUsageStats, loadRetentionConfig, DEFAULT_RETENTION_CONFIG, } from "./store/run-retention.js";
+export { startRetentionScheduler, runRetentionCycle, loadRetentionIntervalMs, DEFAULT_RETENTION_INTERVAL_MS, } from "./store/run-retention-scheduler.js";
+//# sourceMappingURL=public.js.map

package/packages/hench/dist/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../src/public.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,8EAA8E;AAE9E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAoC5E,+EAA+E;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAO3D,+EAA+E;AAE/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAYzE,+EAA+E;AAE/E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAQrE,+EAA+E;AAE/E,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAMtF,+EAA+E;AAE/E,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,+EAA+E;AAE/E,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAWxF,gFAAgF;AAEhF,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC;AAOtC,gFAAgF;AAEhF,OAAO,EACL,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,6BAA6B,CAAC;AAOrC,gFAAgF;AAEhF,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAW3B,iFAAiF;AAEjF,OAAO,EACL,oBAAoB,EACpB,qCAAqC,GACtC,MAAM,qCAAqC,CAAC;AAW7C,gFAAgF;AAEhF,OAAO,EACL,0BAA0B,EAC1B,2CAA2C,GAC5C,MAAM,2CAA2C,CAAC;AAUnD,gFAAgF;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AASnE,gFAAgF;AAEhF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAQjC,iFAAiF;AAEjF,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AASlC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,oCAAoC,CAAC"}