@lostgradient/weft 0.2.0

package/dist/diagnostics/recommendations.js

@@ -0,0 +1,116 @@
+import { THRESHOLDS } from "./types.js";
+function integrityFailureRule({ database }) {
+  if (database.integrityOk)
+    return [];
+  return [
+    {
+      severity: "critical",
+      section: "database",
+      message: `Database integrity check failed: ${database.integrityError}`
+    }
+  ];
+}
+function databaseSizeRule({ database, thresholds }) {
+  if (database.sizeLimitBytes <= 0)
+    return [];
+  const fraction = database.sizeBytes / database.sizeLimitBytes, message = `Database is at ${(fraction * 100).toFixed(1)}% capacity (${formatBytes(database.sizeBytes)} / ${formatBytes(database.sizeLimitBytes)}).`;
+  if (fraction > thresholds.databaseSizeCriticalFraction)
+    return [{ severity: "critical", section: "database", message }];
+  if (fraction > thresholds.databaseSizeWarningFraction)
+    return [{ severity: "warning", section: "database", message }];
+  return [];
+}
+function walSizeRule({ database, thresholds }) {
+  if (database.walSizeBytes === null || database.walSizeBytes <= thresholds.walSizeWarningBytes)
+    return [];
+  return [
+    {
+      severity: "warning",
+      section: "database",
+      message: `WAL file is ${formatBytes(database.walSizeBytes)}, which may indicate stalled checkpointing.`
+    }
+  ];
+}
+function fragmentationRule({ database, thresholds }) {
+  if (database.fragmentationPercent <= thresholds.fragmentationVacuumPercent)
+    return [];
+  return [
+    {
+      severity: "warning",
+      section: "database",
+      message: `Database fragmentation is ${database.fragmentationPercent.toFixed(1)}%. Running VACUUM is recommended.`
+    }
+  ];
+}
+function longRunningWorkflowRule({ workflows, thresholds }) {
+  const longest = workflows.longestRunning;
+  if (!longest || longest.elapsedMilliseconds <= thresholds.longRunningWorkflowMilliseconds)
+    return [];
+  return [
+    {
+      severity: "warning",
+      section: "workflows",
+      message: `Workflow "${longest.id}" has been running for ${formatDuration(longest.elapsedMilliseconds)}. Consider setting an executionTimeout to prevent runaway workflows.`
+    }
+  ];
+}
+function largeCheckpointRule({ workflows, thresholds }) {
+  const largest = workflows.largestCheckpoint;
+  if (!largest || largest.sizeBytes <= thresholds.largeCheckpointBytes)
+    return [];
+  return [
+    {
+      severity: "warning",
+      section: "workflows",
+      message: `Workflow "${largest.workflowId}" has a ${formatBytes(largest.sizeBytes)} checkpoint. Consider reducing state size to improve serialization performance.`
+    }
+  ];
+}
+function idleQueueRule({ queues }) {
+  const out = [];
+  for (const queue of queues)
+    if (queue.pendingCount > 0 && queue.inflightCount === 0)
+      out.push({
+        severity: "warning",
+        section: "activities",
+        message: `Queue "${queue.name}" has ${queue.pendingCount} pending operation(s) but nothing in-flight. Workers may be stopped or disconnected.`
+      });
+  return out;
+}
+const RECOMMENDATION_RULES = [
+  integrityFailureRule,
+  databaseSizeRule,
+  walSizeRule,
+  fragmentationRule,
+  longRunningWorkflowRule,
+  largeCheckpointRule,
+  idleQueueRule
+];
+export function generateRecommendations(report, thresholds) {
+  const context = {
+    database: report.database,
+    workflows: report.workflows,
+    queues: report.queues,
+    thresholds: { ...THRESHOLDS, ...thresholds }
+  };
+  return RECOMMENDATION_RULES.flatMap((rule) => rule(context));
+}
+function formatBytes(bytes) {
+  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`;
+}
+function formatDuration(milliseconds) {
+  const seconds = Math.floor(milliseconds / 1000), minutes = Math.floor(seconds / 60), hours = Math.floor(minutes / 60), days = Math.floor(hours / 24);
+  if (days > 0)
+    return `${days}d ${hours % 24}h`;
+  if (hours > 0)
+    return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0)
+    return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared types and threshold constants for Weft diagnostic commands.
+ *
+ * Used by `weft doctor` (database health, workflow stats, queue depths,
+ * recommendations) and `weft version:check` (version compatibility analysis).
+ *
+ * @module diagnostics/types
+ */
+import type { VersionCompatibility } from '../core/versioning.ts';
+/**
+ * Tri-level health indicator used throughout the diagnostic system.
+ *
+ * `'healthy'` means all metrics are within normal bounds; `'warning'`
+ * indicates a threshold breach that warrants attention; `'critical'` signals a
+ * condition that may affect availability and should be addressed immediately.
+ */
+export type HealthStatus = 'healthy' | 'warning' | 'critical';
+/**
+ * Low-level SQLite database health metrics collected by `weft doctor`.
+ *
+ * Includes file size, WAL size, integrity check result, fragmentation
+ * percentage, and PRAGMA-level metadata.  Consumers typically read this off a
+ * {@link DiagnosticReport} rather than constructing it directly.
+ */
+export interface DatabaseHealth {
+    sizeBytes: number;
+    sizeLimitBytes: number;
+    walSizeBytes: number | null;
+    integrityOk: boolean;
+    integrityError: string | null;
+    fragmentationPercent: number;
+    journalMode: string;
+    pageCount: number;
+    pageSize: number;
+    freelistCount: number;
+}
+/**
+ * Count of workflows in each lifecycle state at the time of the diagnostic
+ * snapshot.
+ *
+ * Populated inside {@link WorkflowStatistics} and returned as part of a
+ * {@link DiagnosticReport}.
+ */
+export interface WorkflowStatusCounts {
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    timedOut: number;
+}
+/**
+ * Identity and elapsed wall-clock time of the longest-running workflow in
+ * storage.
+ *
+ * Useful for spotting stuck or runaway workflows.  Included in
+ * {@link WorkflowStatistics} when at least one active workflow exists.
+ */
+export interface LongestRunningWorkflow {
+    id: string;
+    type: string;
+    startedAt: number;
+    elapsedMilliseconds: number;
+    currentStep: number;
+}
+/**
+ * Workflow ID and byte size of the largest serialised checkpoint in storage.
+ *
+ * Large checkpoints can indicate excessive state accumulation or unbounded
+ * context windows in agent workflows.  Included in {@link WorkflowStatistics}
+ * when at least one workflow has a checkpoint.
+ */
+export interface LargestCheckpoint {
+    workflowId: string;
+    sizeBytes: number;
+}
+/**
+ * Aggregate workflow statistics collected by `weft doctor`.
+ *
+ * Combines total workflow count, per-status counts, the longest-running
+ * workflow, and the largest checkpoint into a single snapshot.  Populated
+ * inside a {@link DiagnosticReport}.
+ */
+export interface WorkflowStatistics {
+    total: number;
+    statusCounts: WorkflowStatusCounts;
+    longestRunning: LongestRunningWorkflow | null;
+    largestCheckpoint: LargestCheckpoint | null;
+}
+/**
+ * Pending and in-flight task counts for a single named activity queue.
+ *
+ * High `pendingCount` values relative to worker capacity indicate backpressure;
+ * high `inflightCount` may suggest workers are slow or stuck.  Included in the
+ * `queues` array of a {@link DiagnosticReport}.
+ */
+export interface QueueStatistics {
+    name: string;
+    pendingCount: number;
+    inflightCount: number;
+}
+/**
+ * Importance level of a diagnostic {@link Recommendation}.
+ *
+ * `'info'` is advisory; `'warning'` means the condition should be addressed
+ * soon; `'critical'` means it needs immediate attention.
+ */
+export type RecommendationSeverity = 'info' | 'warning' | 'critical';
+/**
+ * A single actionable recommendation produced by `weft doctor`.
+ *
+ * Each recommendation has a human-readable `message`, a `severity` level, and
+ * a `section` tag (`'database'`, `'workflows'`, or `'activities'`) so consumers
+ * can group or filter the output.
+ */
+export interface Recommendation {
+    severity: RecommendationSeverity;
+    message: string;
+    section: 'database' | 'workflows' | 'activities';
+}
+/**
+ * Full report produced by `weft doctor`, covering database health, workflow
+ * statistics, per-queue depths, and prioritised recommendations.
+ *
+ * Consumers typically render or log this report rather than constructing it
+ * directly — it is returned by the `doctor` command implementation.
+ */
+export interface DiagnosticReport {
+    timestamp: number;
+    databasePath: string;
+    database: DatabaseHealth;
+    workflows: WorkflowStatistics;
+    queues: QueueStatistics[];
+    recommendations: Recommendation[];
+}
+/**
+ * Per-workflow-type version compatibility analysis for active (running or
+ * pending) workflows.
+ *
+ * Contains the most prevalent stored version, the currently registered version,
+ * a running-workflow count, a {@link VersionCompatibility} verdict, and whether
+ * a migration exists.  Included in a {@link VersionCheckReport}.
+ */
+export interface WorkflowTypeReport {
+    type: string;
+    storedVersion: string;
+    registeredVersion: string;
+    runningCount: number;
+    compatibility: VersionCompatibility;
+    hasMigration: boolean;
+}
+/**
+ * Deployment-safety report produced by `weft version:check`.
+ *
+ * Summarises per-type version compatibility across all active workflows and
+ * gives an `overallVerdict` of `'safe'`, `'unsafe'`, or `'needs-migration'`.
+ * Returned by {@link runVersionCheck} — consumers do not construct it directly.
+ */
+export interface VersionCheckReport {
+    workflowTypes: WorkflowTypeReport[];
+    overallVerdict: 'safe' | 'unsafe' | 'needs-migration';
+}
+export declare const THRESHOLDS: {
+    /** Fragmentation percent above which VACUUM is recommended. */
+    readonly fragmentationVacuumPercent: 20;
+    /** WAL size in bytes above which a warning is emitted. */
+    readonly walSizeWarningBytes: number;
+    /** Database size as fraction of limit that triggers a warning. */
+    readonly databaseSizeWarningFraction: 0.8;
+    /** Database size as fraction of limit that triggers critical. */
+    readonly databaseSizeCriticalFraction: 0.95;
+    /** Workflow running duration (ms) above which a warning is emitted. */
+    readonly longRunningWorkflowMilliseconds: number;
+    /** Checkpoint size in bytes above which a warning is emitted. */
+    readonly largeCheckpointBytes: number;
+    /** Default assumed database size limit (10 GB). */
+    readonly defaultDatabaseSizeLimitBytes: number;
+};

package/dist/diagnostics/types.js

@@ -0,0 +1,9 @@
+export const THRESHOLDS = {
+  fragmentationVacuumPercent: 20,
+  walSizeWarningBytes: 104857600,
+  databaseSizeWarningFraction: 0.8,
+  databaseSizeCriticalFraction: 0.95,
+  longRunningWorkflowMilliseconds: 604800000,
+  largeCheckpointBytes: 524288,
+  defaultDatabaseSizeLimitBytes: 10737418240
+};

package/dist/diagnostics/validate.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Design-time workflow validation for `weft validate`.
+ *
+ * Analyses workflow registrations for common anti-patterns:
+ *
+ * 1. **Unbounded retry policy** — an activity whose `retry.maxAttempts` is
+ *    `Infinity` (or the workflow registration specifies `retry.maxAttempts`
+ *    equal to `Infinity`).  Unbounded retries can loop indefinitely on
+ *    persistent failures, consuming resources without ever propagating the
+ *    error.
+ *
+ * 2. **Stateful activity without compensator** — an activity definition that
+ *    is not marked `idempotent: true` and has no `compensate` function.
+ *    Without a compensator, the activity cannot participate in saga-style
+ *    rollback, leaving partial writes stranded on failure.
+ *
+ * 3. **Non-serializable activity input/output** — detected by passing a
+ *    sentinel object through `JSON.stringify`; non-serializable values
+ *    (functions, Symbols, circular references) cannot survive checkpoint
+ *    persistence.
+ *
+ * @module diagnostics/validate
+ */
+import type { ConstraintDefinition } from '../core/constraint.ts';
+import type { ActivityDefinition, DefinitionSchema, RetentionPolicy, SearchAttributeSchema, WorkflowFunction } from '../core/types.ts';
+/**
+ * Loosely-typed workflow registration shape used only by the `weft validate`
+ * and `weft schedule` CLIs when loading workflow modules from disk. This is
+ * intentionally separate from the public `WorkflowDefinition` type because
+ * loaded modules historically export bare `{ handler, ... }` objects that
+ * do not carry a `name` field — the registration key comes from the export
+ * key, not the object itself.
+ */
+export interface WorkflowRegistration<TInput = unknown, TOutput = unknown> {
+    version?: string;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+    inputSchema?: DefinitionSchema<unknown, TInput>;
+    outputSchema?: DefinitionSchema<unknown, TOutput>;
+    handler: WorkflowFunction<TInput, TOutput>;
+    migrate?: (checkpoint: unknown, fromVersion: string) => unknown;
+    searchAttributes?: SearchAttributeSchema;
+    retention?: RetentionPolicy;
+    constraints?: ConstraintDefinition[];
+}
+export type ValidationIssueSeverity = 'error' | 'warning';
+export type ValidationIssueCode = 'unbounded-retry' | 'stateful-without-compensator' | 'non-serializable-input';
+export interface ValidationIssue {
+    severity: ValidationIssueSeverity;
+    code: ValidationIssueCode;
+    workflowType: string;
+    activityName?: string;
+    message: string;
+}
+export interface ValidationReport {
+    /** Total number of workflow registrations scanned. */
+    workflowCount: number;
+    /** All detected issues across all registrations. */
+    issues: ValidationIssue[];
+    /** `true` when there are no `error`-severity issues. */
+    valid: boolean;
+}
+/**
+ * Validate a collection of workflow registrations for common anti-patterns.
+ *
+ * @param registrations A record of workflow type name → WorkflowRegistration.
+ * @param activities    Optional list of ActivityDefinition objects to check.
+ *                      Activities are not reachable from WorkflowRegistration
+ *                      alone, so pass them explicitly when available.
+ */
+export declare function validateRegistrations(registrations: Record<string, WorkflowRegistration>, activities?: ActivityDefinition[]): ValidationReport;
+export declare function loadRegistrationsFromModule(modulePath: string): Promise<{
+    registrations: Record<string, WorkflowRegistration>;
+    activities: ActivityDefinition[];
+}>;
+/**
+ * Format a validation report as human-readable text for console output.
+ */
+export declare function formatValidationReport(report: ValidationReport, entryPath: string): string;

package/dist/diagnostics/validate.js

@@ -0,0 +1,88 @@
+import { resolve } from "node:path";
+function checkUnboundedRetry(workflowType, activity) {
+  const maxAttempts = activity.retry?.maxAttempts;
+  if (maxAttempts !== void 0 && !isFinite(maxAttempts))
+    return {
+      severity: "error",
+      code: "unbounded-retry",
+      workflowType,
+      activityName: activity.name,
+      message: `Activity "${activity.name}" has retry.maxAttempts = ${maxAttempts}. Unbounded retries loop indefinitely on persistent failures. Set a finite maxAttempts (e.g. 3) or handle the error explicitly.`
+    };
+  return null;
+}
+function checkStatefulWithoutCompensator(workflowType, activity) {
+  if (!activity.idempotent && !activity.compensate)
+    return {
+      severity: "error",
+      code: "stateful-without-compensator",
+      workflowType,
+      activityName: activity.name,
+      message: `Activity "${activity.name}" is not marked idempotent and has no compensate function. If this activity has side effects (writes, charges, emails) it cannot participate in ctx.saga() rollback. Either add a compensate function or set idempotent: true.`
+    };
+  return null;
+}
+export function validateRegistrations(registrations, activities = []) {
+  const issues = [], workflowTypes = Object.keys(registrations);
+  for (const activity of activities) {
+    const retryIssue = checkUnboundedRetry("(standalone)", activity);
+    if (retryIssue)
+      issues.push(retryIssue);
+    const compensatorIssue = checkStatefulWithoutCompensator("(standalone)", activity);
+    if (compensatorIssue)
+      issues.push(compensatorIssue);
+  }
+  const hasErrors = issues.some((i) => i.severity === "error");
+  return {
+    workflowCount: workflowTypes.length,
+    issues,
+    valid: !hasErrors
+  };
+}
+function collectFromExports(entries, registrations, activities, options) {
+  for (const [key, value] of entries)
+    if (isWorkflowRegistration(value)) {
+      if (options.allowOverwrite || !(key in registrations))
+        registrations[key] = value;
+    } else if (isActivityDefinition(value)) {
+      if (options.allowOverwrite || !activities.includes(value))
+        activities.push(value);
+    }
+}
+export async function loadRegistrationsFromModule(modulePath) {
+  const mod = await import(resolve(process.cwd(), modulePath)), registrations = {}, activities = [], defaultExport = mod.default;
+  if (defaultExport !== null && typeof defaultExport === "object")
+    collectFromExports(Object.entries(defaultExport), registrations, activities, { allowOverwrite: !0 });
+  const namedEntries = Object.entries(mod).filter(([key]) => key !== "default");
+  collectFromExports(namedEntries, registrations, activities, { allowOverwrite: !1 });
+  return { registrations, activities };
+}
+function isWorkflowRegistration(value) {
+  return typeof value === "object" && value !== null && "handler" in value && typeof value.handler === "function";
+}
+function isActivityDefinition(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function")
+    return !1;
+  const v = value;
+  return typeof v.name === "string" && typeof v.execute === "function";
+}
+export function formatValidationReport(report, entryPath) {
+  const lines = [];
+  lines.push(`Validating: ${entryPath}`);
+  lines.push(`Workflows scanned: ${report.workflowCount}`);
+  if (report.issues.length === 0) {
+    lines.push("No issues found.");
+    return lines.join(`
+`);
+  }
+  lines.push(`Issues found: ${report.issues.length}`);
+  lines.push("");
+  for (const issue of report.issues) {
+    const location = issue.activityName ? `${issue.workflowType} / ${issue.activityName}` : issue.workflowType, severityLabel = issue.severity === "error" ? "error" : "warning";
+    lines.push(`  [${severityLabel}] ${location}`);
+    lines.push(`    ${issue.code}: ${issue.message}`);
+    lines.push("");
+  }
+  return lines.join(`
+`).trimEnd();
+}

package/dist/diagnostics/version-check.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Version compatibility check for running workflows against registered versions.
+ *
+ * Scans storage for active (running/pending) workflows, groups by type,
+ * and compares stored versions with currently registered versions to
+ * determine deployment safety.
+ *
+ * @module diagnostics/version-check
+ */
+import type { Storage } from '../storage/interface.ts';
+import type { VersionCheckReport } from './types.ts';
+import type { WorkflowRegistration } from './validate.ts';
+/**
+ * Scans active (running and pending) workflows in `storage`, groups them by
+ * type, and compares stored workflow versions against currently registered
+ * versions to determine deployment safety.
+ *
+ * Returns a {@link VersionCheckReport} with a per-type breakdown and an
+ * `overallVerdict` of `'safe'`, `'unsafe'`, or `'needs-migration'`.  Typically
+ * called by the `weft version:check` CLI command.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage, runVersionCheck, workflow } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ *
+ * const ping = workflow({ name: 'ping', version: '1.0.0' })
+ *   .execute(async function* () { return 'pong'; });
+ * const report = await runVersionCheck(storage, { ping });
+ * console.log(report.overallVerdict); // 'safe'
+ * ```
+ */
+export declare function runVersionCheck(storage: Storage, registrations: Record<string, WorkflowRegistration>): Promise<VersionCheckReport>;

package/dist/diagnostics/version-check.js

@@ -0,0 +1,61 @@
+import { decode } from "../core/codec.js";
+import { DEFAULT_WORKFLOW_VERSION, checkVersionCompatibility } from "../core/versioning.js";
+async function groupActiveWorkflowsByType(storage) {
+  const groups = new Map;
+  for await (const [key, bytes] of storage.scan("wf:")) {
+    if (key.includes(":ckpt"))
+      continue;
+    const state = decode(bytes);
+    if (state.status !== "running" && state.status !== "pending")
+      continue;
+    let group = groups.get(state.type);
+    if (!group) {
+      group = { count: 0, versionCounts: new Map };
+      groups.set(state.type, group);
+    }
+    group.count++;
+    group.versionCounts.set(state.version, (group.versionCounts.get(state.version) ?? 0) + 1);
+  }
+  return groups;
+}
+function findMostCommonVersion(versionCounts) {
+  let storedVersion = "", maxCount = 0;
+  for (const [version, count] of versionCounts)
+    if (count > maxCount) {
+      maxCount = count;
+      storedVersion = version;
+    }
+  return storedVersion;
+}
+function buildWorkflowTypeReports(groups, registrations) {
+  const reports = [];
+  for (const [type, group] of groups) {
+    const registration = registrations[type];
+    if (!registration)
+      continue;
+    const storedVersion = findMostCommonVersion(group.versionCounts), registeredVersion = registration.version ?? DEFAULT_WORKFLOW_VERSION, hasMigration = !!registration.migrate, compatibility = checkVersionCompatibility(storedVersion, registeredVersion, hasMigration);
+    reports.push({
+      type,
+      storedVersion,
+      registeredVersion,
+      runningCount: group.count,
+      compatibility,
+      hasMigration
+    });
+  }
+  return reports;
+}
+function computeOverallVerdict(reports) {
+  let verdict = "safe";
+  for (const report of reports) {
+    if (report.compatibility === "incompatible")
+      return "unsafe";
+    if (report.compatibility === "needs-migration")
+      verdict = "needs-migration";
+  }
+  return verdict;
+}
+export async function runVersionCheck(storage, registrations) {
+  const groups = await groupActiveWorkflowsByType(storage), workflowTypes = buildWorkflowTypeReports(groups, registrations), overallVerdict = computeOverallVerdict(workflowTypes);
+  return { workflowTypes, overallVerdict };
+}