@lostgradient/weft 0.2.0

package/dist/diagnostics/doctor.js

@@ -0,0 +1,173 @@
+import { decode } from "../core/codec.js";
+import { fileSize } from "../runtime/portable.js";
+import { KEYS } from "../storage/interface.js";
+import { generateRecommendations } from "./recommendations.js";
+import { THRESHOLDS } from "./types.js";
+export async function collectDiagnostics(storage, databasePath, options) {
+  const now = options?.now ?? Date.now(), sizeLimitBytes = options?.sizeLimitBytes ?? THRESHOLDS.defaultDatabaseSizeLimitBytes, [database, workflows, queues] = await Promise.all([
+    collectDatabaseHealth(storage, databasePath, sizeLimitBytes),
+    collectWorkflowStatistics(storage, now),
+    collectQueueStatistics(storage)
+  ]), recommendations = generateRecommendations({ database, workflows, queues });
+  return {
+    timestamp: now,
+    databasePath,
+    database,
+    workflows,
+    queues,
+    recommendations
+  };
+}
+function firstNumber(rows, column) {
+  const value = rows[0]?.[column];
+  return typeof value === "number" ? value : 0;
+}
+function firstString(rows, column, fallback) {
+  const value = rows[0]?.[column];
+  return typeof value === "string" ? value : fallback;
+}
+async function readDatabasePragmas(query) {
+  const [pageCountRows, pageSizeRows, freelistRows, integrityRows, journalRows] = await Promise.all([
+    query("PRAGMA page_count"),
+    query("PRAGMA page_size"),
+    query("PRAGMA freelist_count"),
+    query("PRAGMA integrity_check"),
+    query("PRAGMA journal_mode")
+  ]);
+  return {
+    pageCount: firstNumber(pageCountRows, "page_count"),
+    pageSize: firstNumber(pageSizeRows, "page_size"),
+    freelistCount: firstNumber(freelistRows, "freelist_count"),
+    integrityResult: firstString(integrityRows, "integrity_check", "ok"),
+    journalMode: firstString(journalRows, "journal_mode", "unknown")
+  };
+}
+function measureDatabaseFiles(databasePath) {
+  if (databasePath === ":memory:")
+    return { sizeBytes: 0, walSizeBytes: null };
+  const walSize = fileSize(databasePath + "-wal");
+  return {
+    sizeBytes: fileSize(databasePath),
+    walSizeBytes: walSize > 0 ? walSize : null
+  };
+}
+async function collectDatabaseHealth(storage, databasePath, sizeLimitBytes) {
+  if (typeof storage.query !== "function")
+    return {
+      sizeBytes: 0,
+      sizeLimitBytes,
+      walSizeBytes: null,
+      integrityOk: !0,
+      integrityError: null,
+      fragmentationPercent: 0,
+      journalMode: "unknown",
+      pageCount: 0,
+      pageSize: 0,
+      freelistCount: 0
+    };
+  const pragmas = await readDatabasePragmas(storage.query.bind(storage)), { sizeBytes, walSizeBytes } = measureDatabaseFiles(databasePath), integrityOk = pragmas.integrityResult === "ok", fragmentationPercent = pragmas.pageCount > 0 ? pragmas.freelistCount / pragmas.pageCount * 100 : 0;
+  return {
+    sizeBytes,
+    sizeLimitBytes,
+    walSizeBytes,
+    integrityOk,
+    integrityError: integrityOk ? null : pragmas.integrityResult,
+    fragmentationPercent,
+    journalMode: pragmas.journalMode,
+    pageCount: pragmas.pageCount,
+    pageSize: pragmas.pageSize,
+    freelistCount: pragmas.freelistCount
+  };
+}
+function mapStatusKey(status) {
+  return status === "timed-out" ? "timedOut" : status;
+}
+async function aggregateWorkflowScan(storage, now) {
+  const statusCounts = {
+    pending: 0,
+    running: 0,
+    completed: 0,
+    failed: 0,
+    cancelled: 0,
+    timedOut: 0
+  };
+  let total = 0, longestRunning = null, earliestCreatedAt = 1 / 0;
+  for await (const [key, value] of storage.scan("wf:")) {
+    if (key.includes(":ckpt"))
+      continue;
+    const state = decode(value);
+    total++;
+    statusCounts[mapStatusKey(state.status)]++;
+    if (state.status === "running" && state.createdAt < earliestCreatedAt) {
+      earliestCreatedAt = state.createdAt;
+      longestRunning = {
+        id: state.id,
+        type: state.type,
+        startedAt: state.createdAt,
+        elapsedMilliseconds: now - state.createdAt,
+        currentStep: 0
+      };
+    }
+  }
+  return { total, statusCounts, longestRunning };
+}
+async function hydrateLongestRunningStep(storage, longestRunning) {
+  const checkpointValue = await storage.get(KEYS.checkpoint(longestRunning.id));
+  if (!checkpointValue)
+    return;
+  const checkpoint = decode(checkpointValue);
+  longestRunning.currentStep = checkpoint.step;
+}
+async function findLargestCheckpoint(storage) {
+  let largestCheckpoint = null, largestSize = 0;
+  for await (const [key, value] of storage.scan("wf:")) {
+    const checkpointIndex = key.indexOf(":ckpt");
+    if (checkpointIndex === -1)
+      continue;
+    if (key.length > checkpointIndex + 5)
+      continue;
+    if (value.byteLength > largestSize) {
+      largestSize = value.byteLength;
+      largestCheckpoint = {
+        workflowId: key.slice(3, checkpointIndex),
+        sizeBytes: value.byteLength
+      };
+    }
+  }
+  return largestCheckpoint;
+}
+async function collectWorkflowStatistics(storage, now) {
+  const { total, statusCounts, longestRunning } = await aggregateWorkflowScan(storage, now);
+  if (longestRunning)
+    await hydrateLongestRunningStep(storage, longestRunning);
+  const largestCheckpoint = await findLargestCheckpoint(storage);
+  return { total, statusCounts, longestRunning, largestCheckpoint };
+}
+async function collectQueueStatistics(storage) {
+  const queueMap = new Map;
+  for await (const [key] of storage.scan("op:")) {
+    if (key.startsWith("op:inflight:"))
+      continue;
+    if (key.startsWith("op:queued:"))
+      continue;
+    if (key.startsWith("op:resolved:"))
+      continue;
+    if (key.startsWith(KEYS.operationResolvedByTimePrefix()))
+      continue;
+    const queueName = key.split(":")[1] ?? "";
+    if (!queueMap.has(queueName))
+      queueMap.set(queueName, { pending: 0, inflight: 0 });
+    queueMap.get(queueName).pending++;
+  }
+  for await (const [, value] of storage.scan("op:inflight:")) {
+    const queueName = decode(value).queue;
+    if (!queueMap.has(queueName))
+      queueMap.set(queueName, { pending: 0, inflight: 0 });
+    queueMap.get(queueName).inflight++;
+  }
+  return [...queueMap.entries()].map(([name, counts]) => ({
+    name,
+    pendingCount: counts.pending,
+    inflightCount: counts.inflight
+  }));
+}

package/dist/diagnostics/format.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Output formatters for diagnostic commands.
+ *
+ * Provides human-readable formatting for `weft doctor` and `weft version:check`
+ * reports, plus utility functions for byte sizes and durations.
+ *
+ * @module diagnostics/format
+ */
+import type { DiagnosticReport, VersionCheckReport } from './types.ts';
+/**
+ * Format a byte count into a human-readable string.
+ *
+ * - 0 returns '0 B'
+ * - Values under 1024 return '{n} B'
+ * - Values under 1024^2 return '{n} KB' (1 decimal place)
+ * - Values under 1024^3 return '{n} MB' (1 decimal place)
+ * - Otherwise returns '{n} GB' (1 decimal place)
+ *
+ * @example
+ * ```ts
+ * import { formatBytes } from '@lostgradient/weft';
+ *
+ * console.log(formatBytes(0));         // '0 B'
+ * console.log(formatBytes(1024));      // '1.0 KB'
+ * console.log(formatBytes(1048576));   // '1.0 MB'
+ * ```
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format a duration in milliseconds into a human-readable string.
+ *
+ * - Under 1000ms: '{n}ms'
+ * - Under 60000ms: '{n} seconds' (rounded)
+ * - Under 3600000ms: '{n} minutes' (rounded)
+ * - Under 86400000ms: '{n} hours' optionally with minutes
+ * - Otherwise: '{n} days' optionally with hours
+ *
+ * @example
+ * ```ts
+ * import { formatDuration } from '@lostgradient/weft';
+ *
+ * console.log(formatDuration(500));      // '500ms'
+ * console.log(formatDuration(90000));    // '2 minutes'
+ * console.log(formatDuration(7200000));  // '2 hours'
+ * ```
+ */
+export declare function formatDuration(milliseconds: number): string;
+/**
+ * Format a DiagnosticReport into a human-readable multi-section string.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage, collectDiagnostics, formatDiagnosticReport } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * const report = await collectDiagnostics(storage, ':memory:');
+ * console.log(formatDiagnosticReport(report));
+ * ```
+ */
+export declare function formatDiagnosticReport(report: DiagnosticReport): string;
+/**
+ * Format a VersionCheckReport into a human-readable string.
+ *
+ * @example
+ * ```ts
+ * import type { VersionCheckReport } from '@lostgradient/weft';
+ * import { formatVersionCheckReport } from '@lostgradient/weft';
+ *
+ * const report: VersionCheckReport = {
+ *   workflowTypes: [],
+ *   overallVerdict: 'safe',
+ * };
+ * console.log(formatVersionCheckReport(report));
+ * // Result: safe to deploy.
+ * ```
+ */
+export declare function formatVersionCheckReport(report: VersionCheckReport): string;

package/dist/diagnostics/format.js

@@ -0,0 +1,115 @@
+const supportsColor = typeof process < "u" && process.stdout?.isTTY && !process.env.NO_COLOR, color = {
+  green: (text) => supportsColor ? `\x1B[32m${text}\x1B[0m` : text,
+  yellow: (text) => supportsColor ? `\x1B[33m${text}\x1B[0m` : text,
+  red: (text) => supportsColor ? `\x1B[31m${text}\x1B[0m` : text,
+  bold: (text) => supportsColor ? `\x1B[1m${text}\x1B[0m` : text
+};
+export function formatBytes(bytes) {
+  if (bytes === 0)
+    return "0 B";
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1048576)
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1073741824)
+    return `${(bytes / 1048576).toFixed(1)} MB`;
+  return `${(bytes / 1073741824).toFixed(1)} GB`;
+}
+export function formatDuration(milliseconds) {
+  if (milliseconds < 1000)
+    return `${milliseconds}ms`;
+  if (milliseconds < 60000)
+    return `${Math.round(milliseconds / 1000)} seconds`;
+  if (milliseconds < 3600000)
+    return `${Math.round(milliseconds / 60000)} minutes`;
+  if (milliseconds < 86400000) {
+    const hours = Math.floor(milliseconds / 3600000), minutes = Math.round(milliseconds % 3600000 / 60000);
+    if (minutes > 0)
+      return `${hours} hours ${minutes} minutes`;
+    return `${hours} hours`;
+  }
+  const days = Math.floor(milliseconds / 86400000), hours = Math.round(milliseconds % 86400000 / 3600000);
+  if (hours > 0)
+    return `${days} days ${hours} hours`;
+  return `${days} days`;
+}
+function appendDatabaseSection(lines, database) {
+  lines.push(color.bold("Database:"));
+  lines.push(`  Size: ${formatBytes(database.sizeBytes)} (of ${formatBytes(database.sizeLimitBytes)})`);
+  lines.push(`  WAL size: ${database.walSizeBytes !== null ? formatBytes(database.walSizeBytes) : "N/A"}`);
+  lines.push(`  Integrity: ${database.integrityOk ? "OK" : `FAILED: ${database.integrityError}`}`);
+  lines.push(`  Fragmentation: ${database.fragmentationPercent}%`);
+}
+function appendWorkflowsSection(lines, workflows) {
+  lines.push("");
+  lines.push(color.bold("Workflows:"));
+  if (workflows.total === 0) {
+    lines.push("  Total: 0 (no workflows)");
+    return;
+  }
+  const counts = workflows.statusCounts;
+  lines.push(`  Total: ${workflows.total} (${counts.running} running, ${counts.completed} completed, ${counts.failed} failed)`);
+  if (workflows.longestRunning) {
+    const longest = workflows.longestRunning;
+    lines.push(`  Longest running: ${longest.id} (started ${formatDuration(longest.elapsedMilliseconds)} ago, step ${longest.currentStep})`);
+  }
+  if (workflows.largestCheckpoint) {
+    const largest = workflows.largestCheckpoint;
+    lines.push(`  Largest checkpoint: ${largest.workflowId} (${formatBytes(largest.sizeBytes)})`);
+  }
+}
+function appendActivitiesSection(lines, queues) {
+  lines.push("");
+  lines.push(color.bold("Activities:"));
+  if (queues.length === 0) {
+    lines.push("  No activity queues");
+    return;
+  }
+  for (const queue of queues)
+    lines.push(`  Queue "${queue.name}": ${queue.pendingCount} pending, ${queue.inflightCount} in-flight`);
+}
+function recommendationIcon(severity) {
+  return severity === "critical" ? "!!" : "!";
+}
+function appendRecommendationsSection(lines, recommendations) {
+  lines.push("");
+  lines.push(color.bold("Recommendations:"));
+  if (recommendations.length === 0) {
+    lines.push("  No issues found.");
+    return;
+  }
+  for (const recommendation of recommendations)
+    lines.push(`  ${recommendationIcon(recommendation.severity)} ${recommendation.message}`);
+}
+export function formatDiagnosticReport(report) {
+  const lines = [];
+  appendDatabaseSection(lines, report.database);
+  appendWorkflowsSection(lines, report.workflows);
+  appendActivitiesSection(lines, report.queues);
+  appendRecommendationsSection(lines, report.recommendations);
+  return lines.join(`
+`);
+}
+export function formatVersionCheckReport(report) {
+  const lines = [];
+  for (const typeReport of report.workflowTypes) {
+    lines.push(`${typeReport.type} (${typeReport.storedVersion} \u2192 ${typeReport.registeredVersion}):`);
+    lines.push(`  ${typeReport.runningCount} running workflows`);
+    lines.push(`  Compatibility: ${typeReport.compatibility}`);
+    lines.push(`  Migration: ${typeReport.hasMigration ? "provided" : "not provided"}`);
+    lines.push("");
+  }
+  switch (report.overallVerdict) {
+    case "safe":
+      lines.push(`Result: ${color.green("Safe to deploy.")}`);
+      break;
+    case "needs-migration":
+      lines.push(`Result: ${color.yellow("Needs migration. Migration functions provided.")}`);
+      break;
+    case "unsafe":
+      lines.push(`Result: ${color.red("UNSAFE: missing migration functions.")}`);
+      break;
+  }
+  return lines.join(`
+`);
+}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Diagnostics public surface — doctor checks, memory profiling, formatting,
+ * recommendations, and version checks. Re-exported from the package root
+ * (`weft`) so the diagnostics API is importable without reaching into the
+ * `diagnostics/` directory directly.
+ *
+ * @module diagnostics
+ */
+export { collectDiagnostics } from './doctor.ts';
+export { formatBytes, formatDiagnosticReport, formatDuration, formatVersionCheckReport, } from './format.ts';
+export { MemoryProfiler, analyzeStability, linearRegression } from './memory-profiler.ts';
+export type { MemoryProfile, MemorySample, StabilityOptions, StabilityResult, } from './memory-profiler.ts';
+export { generateRecommendations } from './recommendations.ts';
+export type { DatabaseHealth, DiagnosticReport, HealthStatus, LargestCheckpoint, LongestRunningWorkflow, QueueStatistics, Recommendation, RecommendationSeverity, VersionCheckReport, WorkflowStatistics, WorkflowStatusCounts, WorkflowTypeReport, } from './types.ts';
+export { runVersionCheck } from './version-check.ts';

package/dist/diagnostics/index.js

@@ -0,0 +1,10 @@
+export { collectDiagnostics } from "./doctor.js";
+export {
+  formatBytes,
+  formatDiagnosticReport,
+  formatDuration,
+  formatVersionCheckReport
+} from "./format.js";
+export { MemoryProfiler, analyzeStability, linearRegression } from "./memory-profiler.js";
+export { generateRecommendations } from "./recommendations.js";
+export { runVersionCheck } from "./version-check.js";

package/dist/diagnostics/memory-profiler.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Memory profiler for detecting unbounded growth under sustained load.
+ *
+ * Samples process memory (RSS, heap) at configurable intervals and applies
+ * linear regression to determine whether RSS is growing over time. A stable
+ * system shows a near-zero slope after the initial warmup period.
+ *
+ * @module diagnostics/memory-profiler
+ */
+/** A single point-in-time memory measurement. */
+export interface MemorySample {
+    timestamp: number;
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    arrayBuffers: number;
+}
+/** Summary of a profiling session. */
+export interface MemoryProfile {
+    samples: MemorySample[];
+    durationMilliseconds: number;
+    peakRss: number;
+    averageRss: number;
+}
+/** Result of a stability analysis. */
+export interface StabilityResult {
+    /** Whether RSS growth rate is within the acceptable threshold. */
+    stable: boolean;
+    /** Estimated RSS growth in bytes per second (from linear regression). */
+    rssGrowthRatePerSecond: number;
+    /** The threshold used for comparison (bytes/sec). */
+    thresholdPerSecond: number;
+    /** Number of samples analyzed (after warmup skip). */
+    samplesAnalyzed: number;
+}
+/**
+ * Options for stability analysis.
+ *
+ * @example
+ * ```ts
+ * import { analyzeStability, type StabilityOptions } from '@lostgradient/weft';
+ *
+ * const options: StabilityOptions = {
+ *   maxGrowthRatePerSecond: 5 * 1024, // 5 KB/s threshold
+ *   warmupSamples: 3,
+ * };
+ * const result = analyzeStability([], options);
+ * console.log(result.stable); // true (no samples)
+ * ```
+ */
+export interface StabilityOptions {
+    /**
+     * Maximum acceptable RSS growth rate in bytes per second.
+     * Default: 10 KB/sec — accounts for minor GC jitter and allocator noise.
+     */
+    maxGrowthRatePerSecond?: number;
+    /**
+     * Number of initial samples to skip (warmup period where the runtime
+     * JIT-compiles, allocates caches, etc.). Default: 5.
+     */
+    warmupSamples?: number;
+}
+/**
+ * Simple least-squares linear regression over (x, y) points.
+ * Returns the slope and intercept of the best-fit line y = slope * x + intercept.
+ *
+ * @example
+ * ```ts
+ * import { linearRegression } from '@lostgradient/weft';
+ *
+ * const points: [number, number][] = [
+ *   [0, 100], [1, 105], [2, 110], [3, 115],
+ * ];
+ * const { slope, intercept } = linearRegression(points);
+ * console.log(slope);     // ~5
+ * console.log(intercept); // ~100
+ * ```
+ */
+export declare function linearRegression(points: [number, number][]): {
+    slope: number;
+    intercept: number;
+};
+/**
+ * Analyze a series of memory samples to determine if RSS is stable.
+ *
+ * Applies linear regression to RSS values over time (in seconds) after
+ * skipping a configurable warmup period. The system is considered stable
+ * if the growth rate is below the configured threshold.
+ *
+ * @example
+ * ```ts
+ * import { MemoryProfiler, analyzeStability } from '@lostgradient/weft';
+ *
+ * const profiler = new MemoryProfiler();
+ * profiler.start(100);
+ * await new Promise((r) => setTimeout(r, 600));
+ * profiler.stop();
+ * const { samples } = profiler.profile();
+ * const stability = analyzeStability(samples, { warmupSamples: 2 });
+ * console.log(stability.stable);
+ * ```
+ */
+export declare function analyzeStability(samples: MemorySample[], options?: StabilityOptions): StabilityResult;
+/**
+ * Interval-based memory profiler. Call {@link start} to begin sampling and
+ * {@link stop} when the workload is done. Use {@link profile} to retrieve
+ * the collected samples and summary statistics.
+ *
+ * @example
+ * ```ts
+ * import { MemoryProfiler } from '@lostgradient/weft';
+ *
+ * const profiler = new MemoryProfiler();
+ * profiler.start(200); // sample every 200ms
+ * await new Promise((r) => setTimeout(r, 1000));
+ * profiler.stop();
+ * const { peakRss, averageRss, samples } = profiler.profile();
+ * console.log('Peak RSS:', peakRss);
+ * console.log('Samples:', samples.length);
+ * ```
+ */
+export declare class MemoryProfiler {
+    #private;
+    constructor();
+    /** Take a single snapshot of current process memory. */
+    snapshot(): MemorySample;
+    /** Begin sampling memory at the given interval (milliseconds). */
+    start(intervalMilliseconds: number): void;
+    /** Stop interval sampling. Idempotent. */
+    stop(): void;
+    /** Clear all collected samples. */
+    reset(): void;
+    /** Return the collected profile with summary statistics. */
+    profile(): MemoryProfile;
+}

package/dist/diagnostics/memory-profiler.js

@@ -0,0 +1,93 @@
+export function linearRegression(points) {
+  const n = points.length;
+  if (n <= 1)
+    return { slope: 0, intercept: n === 1 ? points[0][1] : 0 };
+  let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0;
+  for (const [x, y] of points) {
+    sumX += x;
+    sumY += y;
+    sumXY += x * y;
+    sumX2 += x * x;
+  }
+  const denominator = n * sumX2 - sumX * sumX;
+  if (denominator === 0)
+    return { slope: 0, intercept: sumY / n };
+  const slope = (n * sumXY - sumX * sumY) / denominator, intercept = (sumY - slope * sumX) / n;
+  return { slope, intercept };
+}
+export function analyzeStability(samples, options = {}) {
+  const { maxGrowthRatePerSecond = 10240, warmupSamples = 5 } = options, analyzed = samples.slice(warmupSamples);
+  if (analyzed.length <= 1)
+    return {
+      stable: !0,
+      rssGrowthRatePerSecond: 0,
+      thresholdPerSecond: maxGrowthRatePerSecond,
+      samplesAnalyzed: analyzed.length
+    };
+  const baseTime = analyzed[0].timestamp, points = [];
+  for (const sample of analyzed)
+    points.push([(sample.timestamp - baseTime) / 1000, sample.rss]);
+  const { slope } = linearRegression(points);
+  return {
+    stable: Math.abs(slope) <= maxGrowthRatePerSecond,
+    rssGrowthRatePerSecond: slope,
+    thresholdPerSecond: maxGrowthRatePerSecond,
+    samplesAnalyzed: analyzed.length
+  };
+}
+
+export class MemoryProfiler {
+  #samples;
+  #timer;
+  constructor() {
+    this.#samples = [];
+    this.#timer = null;
+  }
+  #recordSnapshot() {
+    this.#samples.push(this.snapshot());
+  }
+  snapshot() {
+    const usage = process.memoryUsage();
+    return {
+      timestamp: Date.now(),
+      rss: usage.rss,
+      heapUsed: usage.heapUsed,
+      heapTotal: usage.heapTotal,
+      external: usage.external,
+      arrayBuffers: usage.arrayBuffers
+    };
+  }
+  start(intervalMilliseconds) {
+    this.stop();
+    this.#recordSnapshot();
+    this.#timer = setInterval(this.#recordSnapshot.bind(this), intervalMilliseconds);
+  }
+  stop() {
+    if (this.#timer !== null) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+  }
+  reset() {
+    this.stop();
+    this.#samples = [];
+  }
+  profile() {
+    const samples = this.#samples;
+    if (samples.length === 0)
+      return { samples: [], durationMilliseconds: 0, peakRss: 0, averageRss: 0 };
+    const first = samples[0], last = samples[samples.length - 1];
+    let peakRss = 0, totalRss = 0;
+    for (const sample of samples) {
+      if (sample.rss > peakRss)
+        peakRss = sample.rss;
+      totalRss += sample.rss;
+    }
+    return {
+      samples,
+      durationMilliseconds: last.timestamp - first.timestamp,
+      peakRss,
+      averageRss: totalRss / samples.length
+    };
+  }
+}

package/dist/diagnostics/recommendations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Recommendation engine for Weft diagnostics.
+ *
+ * Analyzes database health, workflow statistics, and queue statistics
+ * to produce actionable recommendations ordered by severity.
+ *
+ * @module diagnostics/recommendations
+ */
+import type { DatabaseHealth, QueueStatistics, Recommendation, WorkflowStatistics } from './types.ts';
+import { THRESHOLDS } from './types.ts';
+/**
+ * Generate recommendations based on diagnostic data.
+ *
+ * Rules are checked in a fixed order so that the most critical issues
+ * appear first in the returned array.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage, collectDiagnostics, generateRecommendations } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * const report = await collectDiagnostics(storage, ':memory:');
+ * const recs = generateRecommendations({
+ *   database: report.database,
+ *   workflows: report.workflows,
+ *   queues: report.queues,
+ * });
+ * console.log(recs.length); // 0 for a healthy instance
+ * ```
+ */
+export declare function generateRecommendations(report: {
+    database: DatabaseHealth;
+    workflows: WorkflowStatistics;
+    queues: QueueStatistics[];
+}, thresholds?: Partial<{
+    [K in keyof typeof THRESHOLDS]: number;
+}>): Recommendation[];