@lostgradient/weft 0.2.0

package/dist/core/worker-protocol.js

@@ -0,0 +1,346 @@
+import { encode, validateCloneable } from "./codec.js";
+import {
+  WORKER_REPLAY_SIGNATURE_FORMAT
+} from "./types/checkpoint.js";
+export {
+  WORKER_REPLAY_SIGNATURE_FORMAT
+} from "./types/checkpoint.js";
+export const WORKER_PROTOCOL_VERSION = 1, DEFAULT_WORKER_TURN_TIMEOUT_MS = 1000, DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES = 1048576, MIN_WORKER_PROTOCOL_MESSAGE_BYTES = 4096;
+const BINARY_MARKER = "__weftBinaryBytes", DATE_MARKER = "__weftDate", ERROR_MARKER = "__weftError", MAP_MARKER = "__weftMap", SET_MARKER = "__weftSet", MAX_BOUNDED_ERROR_LENGTH = 512, WORKER_SIGNATURE_EXCLUDED_FIELDS = new Set([
+  "attempt",
+  "callerStack",
+  "execute",
+  "fn",
+  "id",
+  "operationId",
+  "resumedCacheEntry",
+  "scheduledFireAt",
+  "scheduledAt",
+  "workflowId"
+]), WORKER_SIGNATURE_OPERATION_TYPES = new Set([
+  "activity",
+  "archive",
+  "child-workflow",
+  "load",
+  "memo",
+  "offload",
+  "parallel",
+  "race",
+  "run-all",
+  "signal-wait",
+  "sleep",
+  "speculate",
+  "state-commit",
+  "state-read",
+  "stream",
+  "timer",
+  "wait-review",
+  "wait-signal",
+  "wait-update"
+]);
+
+export class WorkerProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkerProtocolError";
+  }
+}
+
+export class WorkerProtocolMessageSizeError extends WorkerProtocolError {
+  actualBytes;
+  maxBytes;
+  constructor(actualBytes, maxBytes) {
+    super(`Worker protocol message is ${actualBytes} bytes, exceeding limit ${maxBytes}`);
+    this.actualBytes = actualBytes;
+    this.maxBytes = maxBytes;
+  }
+}
+export function createBoundedWorkerFailureMessage(parameters) {
+  return {
+    type: "failed",
+    protocolVersion: WORKER_PROTOCOL_VERSION,
+    ...parameters.turnId === void 0 ? {} : { turnId: parameters.turnId },
+    workflowId: parameters.workflowId,
+    error: truncateForProtocol(parameters.error),
+    failureCategory: parameters.failureCategory
+  };
+}
+export function estimateWorkerProtocolMessageBytes(message) {
+  let binaryBytes = 0;
+  return encode(toEncodedEnvelope(message, [], (bytes) => {
+    binaryBytes += bytes;
+  })).byteLength + binaryBytes;
+}
+export function assertWorkerProtocolMessageWithinLimit(message, maxBytes) {
+  const actualBytes = estimateWorkerProtocolMessageBytes(message);
+  if (maxBytes !== void 0 && actualBytes > maxBytes)
+    throw new WorkerProtocolMessageSizeError(actualBytes, maxBytes);
+  return actualBytes;
+}
+export function assertWorkerOutboundMessageShape(message) {
+  const record = assertWorkerOutboundRecord(message);
+  assertWorkerOutboundCommonFields(record);
+  assertWorkerOutboundVariant(record);
+}
+function assertWorkerOutboundRecord(message) {
+  if (typeof message !== "object" || message === null)
+    throw new WorkerProtocolError("Worker outbound message must be an object");
+  return message;
+}
+function assertWorkerOutboundCommonFields(record) {
+  if (typeof record.workflowId !== "string")
+    throw new WorkerProtocolError("Worker outbound message must include workflowId");
+  assertOptionalIntegerField(record, "protocolVersion");
+  assertOptionalIntegerField(record, "turnId");
+}
+function assertOptionalIntegerField(record, field) {
+  if (record[field] !== void 0 && !Number.isSafeInteger(record[field]))
+    throw new WorkerProtocolError(`Worker outbound message ${field} must be an integer`);
+}
+function assertWorkerOutboundVariant(record) {
+  switch (record.type) {
+    case "checkpoint":
+      assertWorkerCheckpointOutbound(record);
+      return;
+    case "completed":
+      return;
+    case "failed":
+      assertWorkerFailedOutbound(record);
+      return;
+    default:
+      throw new WorkerProtocolError("Worker outbound message has an unsupported type");
+  }
+}
+function assertWorkerCheckpointOutbound(record) {
+  if (!(record.checkpoint instanceof ArrayBuffer))
+    throw new WorkerProtocolError("Worker checkpoint message must include checkpoint bytes");
+  if (typeof record.operationRequest !== "object" || record.operationRequest === null)
+    throw new WorkerProtocolError("Worker checkpoint message must include operationRequest");
+}
+function assertWorkerFailedOutbound(record) {
+  if (typeof record.error !== "string")
+    throw new WorkerProtocolError("Worker failed message must include an error string");
+}
+export async function createWorkerReplayOperationSignature(operation, maxStableFieldsBytes) {
+  const operationType = workerOperationType(operation), stableFields = stableWorkerOperationFields(operation, operationType), encodedStableFields = encode(stableFields);
+  if (encodedStableFields.byteLength > maxStableFieldsBytes)
+    throw new WorkerProtocolError(`Worker replay signature input is ${encodedStableFields.byteLength} bytes, exceeding limit ${maxStableFieldsBytes}`);
+  const digestBytes = await crypto.subtle.digest("SHA-256", encodedStableFields);
+  return {
+    format: WORKER_REPLAY_SIGNATURE_FORMAT,
+    operationType,
+    stableFieldsDigest: bytesToHex(new Uint8Array(digestBytes)),
+    stableFieldsByteLength: encodedStableFields.byteLength
+  };
+}
+export function workerReplayOperationSignaturesEqual(left, right) {
+  return left.format === right.format && left.operationType === right.operationType && left.stableFieldsDigest === right.stableFieldsDigest && left.stableFieldsByteLength === right.stableFieldsByteLength;
+}
+function truncateForProtocol(value) {
+  if (value.length <= MAX_BOUNDED_ERROR_LENGTH)
+    return value;
+  return `${value.slice(0, MAX_BOUNDED_ERROR_LENGTH)}...`;
+}
+function workerOperationType(operation) {
+  const record = operation, type = record.type;
+  if (typeof type === "string")
+    return type;
+  const kind = record.kind;
+  if (typeof kind === "string")
+    return kind;
+  throw new WorkerProtocolError("Worker operation has no type or kind");
+}
+function stableWorkerOperationFields(operation, operationType) {
+  if (!isSupportedWorkerOperationType(operationType))
+    throw new WorkerProtocolError(`Unsupported Worker replay operation type: ${operationType}`);
+  return toSortedStableRecord(operation);
+}
+function isSupportedWorkerOperationType(operationType) {
+  return WORKER_SIGNATURE_OPERATION_TYPES.has(operationType);
+}
+function toSortedStableRecord(record) {
+  const stable = {};
+  for (const key of Object.keys(record).toSorted()) {
+    if (WORKER_SIGNATURE_EXCLUDED_FIELDS.has(key))
+      continue;
+    if (record.type === "run-all" && key === "branches") {
+      stable[key] = toStableRunAllBranches(record[key], []);
+      continue;
+    }
+    stable[key] = toSignatureValue(record[key], []);
+  }
+  return stable;
+}
+function toStableRunAllBranches(value, stack) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return toSignatureValue(value, stack);
+  if (stack.includes(value))
+    throw new WorkerProtocolError("Worker replay signature cannot include cyclic values");
+  stack.push(value);
+  try {
+    const stableBranches = {}, branches = value;
+    for (const branchName of Object.keys(branches).toSorted())
+      stableBranches[branchName] = toStableRunAllBranch(branches[branchName], stack);
+    return stableBranches;
+  } finally {
+    stack.pop();
+  }
+}
+function toStableRunAllBranch(branch, stack) {
+  if (!Array.isArray(branch))
+    return toSignatureValue(branch, stack);
+  const stableBranch = {
+    arity: branch.length
+  };
+  if (branch.length > 1)
+    stableBranch.input = toSignatureValue(branch[1], stack);
+  return stableBranch;
+}
+function toSignatureValue(value, stack) {
+  const specialValue = toSignatureSpecialValue(value, stack);
+  if (specialValue.handled)
+    return specialValue.value;
+  if (stack.includes(value))
+    throw new WorkerProtocolError("Worker replay signature cannot include cyclic values");
+  stack.push(value);
+  try {
+    return toSortedStableRecord(value);
+  } finally {
+    stack.pop();
+  }
+}
+function toSignatureSpecialValue(value, stack) {
+  if (typeof value === "function" || typeof value === "symbol")
+    throw new WorkerProtocolError("Worker replay signature cannot include functions or symbols");
+  const binaryValue = toSignatureBinaryValue(value);
+  if (binaryValue.handled)
+    return binaryValue;
+  const objectValue = toSignatureKnownObjectValue(value, stack);
+  if (objectValue.handled)
+    return objectValue;
+  if (Array.isArray(value))
+    return { handled: !0, value: value.map((entry) => toSignatureValue(entry, stack)) };
+  if (typeof value !== "object" || value === null)
+    return { handled: !0, value };
+  return { handled: !1 };
+}
+function toSignatureBinaryValue(value) {
+  if (value instanceof ArrayBuffer)
+    return { handled: !0, value: { [BINARY_MARKER]: bytesToHex(new Uint8Array(value)) } };
+  if (ArrayBuffer.isView(value))
+    return {
+      handled: !0,
+      value: {
+        [BINARY_MARKER]: bytesToHex(new Uint8Array(value.buffer, value.byteOffset, value.byteLength))
+      }
+    };
+  return { handled: !1 };
+}
+function toSignatureKnownObjectValue(value, stack) {
+  if (value instanceof Date)
+    return { handled: !0, value: { [DATE_MARKER]: value.toISOString() } };
+  if (value instanceof Error)
+    return {
+      handled: !0,
+      value: { [ERROR_MARKER]: { name: value.name, message: value.message } }
+    };
+  if (value instanceof Map)
+    return {
+      handled: !0,
+      value: {
+        [MAP_MARKER]: [...value.entries()].map(([key, entryValue]) => [
+          toSignatureValue(key, stack),
+          toSignatureValue(entryValue, stack)
+        ])
+      }
+    };
+  if (value instanceof Set)
+    return {
+      handled: !0,
+      value: { [SET_MARKER]: [...value.values()].map((entry) => toSignatureValue(entry, stack)) }
+    };
+  return { handled: !1 };
+}
+function toEncodedEnvelope(value, stack, recordBinaryBytes) {
+  const specialValue = toEncodedSpecialValue(value, stack, recordBinaryBytes);
+  if (specialValue.handled)
+    return specialValue.value;
+  if (stack.includes(value))
+    throw new WorkerProtocolError("Worker protocol message cannot include cyclic values");
+  if (!validateCloneable(value).valid)
+    throw new WorkerProtocolError("Worker protocol message contains non-cloneable values");
+  return toEncodedObjectEnvelope(value, stack, recordBinaryBytes);
+}
+function toEncodedSpecialValue(value, stack, recordBinaryBytes) {
+  if (typeof value === "function" || typeof value === "symbol")
+    throw new WorkerProtocolError("Worker protocol message cannot include functions or symbols");
+  const binaryValue = toEncodedBinaryValue(value, recordBinaryBytes);
+  if (binaryValue.handled)
+    return binaryValue;
+  const objectValue = toEncodedKnownObjectValue(value, stack, recordBinaryBytes);
+  if (objectValue.handled)
+    return objectValue;
+  if (Array.isArray(value))
+    return {
+      handled: !0,
+      value: value.map((entry) => toEncodedEnvelope(entry, stack, recordBinaryBytes))
+    };
+  if (typeof value !== "object" || value === null)
+    return { handled: !0, value };
+  return { handled: !1 };
+}
+function toEncodedBinaryValue(value, recordBinaryBytes) {
+  if (value instanceof ArrayBuffer) {
+    recordBinaryBytes(value.byteLength);
+    return { handled: !0, value: { [BINARY_MARKER]: value.byteLength } };
+  }
+  if (ArrayBuffer.isView(value)) {
+    recordBinaryBytes(value.byteLength);
+    return { handled: !0, value: { [BINARY_MARKER]: value.byteLength } };
+  }
+  return { handled: !1 };
+}
+function toEncodedKnownObjectValue(value, stack, recordBinaryBytes) {
+  if (value instanceof Date)
+    return { handled: !0, value: { [DATE_MARKER]: value.toISOString() } };
+  if (value instanceof Error)
+    return {
+      handled: !0,
+      value: { [ERROR_MARKER]: { name: value.name, message: value.message } }
+    };
+  if (value instanceof Map)
+    return {
+      handled: !0,
+      value: {
+        [MAP_MARKER]: [...value.entries()].map(([key, entryValue]) => [
+          toEncodedEnvelope(key, stack, recordBinaryBytes),
+          toEncodedEnvelope(entryValue, stack, recordBinaryBytes)
+        ])
+      }
+    };
+  if (value instanceof Set)
+    return {
+      handled: !0,
+      value: {
+        [SET_MARKER]: [...value.values()].map((entry) => toEncodedEnvelope(entry, stack, recordBinaryBytes))
+      }
+    };
+  return { handled: !1 };
+}
+function toEncodedObjectEnvelope(value, stack, recordBinaryBytes) {
+  stack.push(value);
+  try {
+    const envelope = {};
+    for (const key of Object.keys(value).toSorted())
+      envelope[key] = toEncodedEnvelope(value[key], stack, recordBinaryBytes);
+    return envelope;
+  } finally {
+    stack.pop();
+  }
+}
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}

package/dist/core/worker-turn-watchdog.d.ts

@@ -0,0 +1,14 @@
+export interface WorkerTurnState {
+    worker: Worker;
+    workflowId: string;
+    turnId: number;
+    kind: 'run' | 'resume';
+}
+export declare class WorkerTurnWatchdog {
+    #private;
+    constructor(timeoutMs: number | undefined, onTimeout: (turn: WorkerTurnState) => void);
+    begin(worker: Worker, workflowId: string, turnId: number, kind: WorkerTurnState['kind']): void;
+    clear(worker: Worker): void;
+    clearAll(): void;
+    get(worker: Worker): WorkerTurnState | undefined;
+}

package/dist/core/worker-turn-watchdog.js

@@ -0,0 +1,40 @@
+export class WorkerTurnWatchdog {
+  #turnsByWorker = new Map;
+  #timeoutMs;
+  #onTimeout;
+  constructor(timeoutMs, onTimeout) {
+    this.#timeoutMs = timeoutMs;
+    this.#onTimeout = onTimeout;
+  }
+  begin(worker, workflowId, turnId, kind) {
+    this.clear(worker);
+    const turn = {
+      worker,
+      workflowId,
+      turnId,
+      kind,
+      timeout: null
+    };
+    if (this.#timeoutMs !== void 0)
+      turn.timeout = setTimeout(() => {
+        if (this.#turnsByWorker.get(worker) === turn)
+          this.#onTimeout(turn);
+      }, this.#timeoutMs);
+    this.#turnsByWorker.set(worker, turn);
+  }
+  clear(worker) {
+    const turn = this.#turnsByWorker.get(worker);
+    if (!turn)
+      return;
+    if (turn.timeout !== null)
+      clearTimeout(turn.timeout);
+    this.#turnsByWorker.delete(worker);
+  }
+  clearAll() {
+    for (const worker of this.#turnsByWorker.keys())
+      this.clear(worker);
+  }
+  get(worker) {
+    return this.#turnsByWorker.get(worker);
+  }
+}

package/dist/core/workflow-identifiers.d.ts

@@ -0,0 +1 @@
+export declare function assertValidWorkflowId(id: string, fieldName?: string): void;

package/dist/core/workflow-identifiers.js

@@ -0,0 +1,19 @@
+const MAX_WORKFLOW_ID_LENGTH = 128;
+function containsControlCharacter(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === void 0)
+      continue;
+    if (codePoint >= 0 && codePoint <= 31 || codePoint === 127)
+      return !0;
+  }
+  return !1;
+}
+export function assertValidWorkflowId(id, fieldName = "options.id") {
+  if (id.length === 0)
+    throw Error(`${fieldName} must not be an empty string`);
+  if (id.length > MAX_WORKFLOW_ID_LENGTH)
+    throw Error(`${fieldName} must be at most ${MAX_WORKFLOW_ID_LENGTH} characters`);
+  if (containsControlCharacter(id))
+    throw Error(`${fieldName} must not contain control characters`);
+}

package/dist/core/workflow-tags.d.ts

@@ -0,0 +1,9 @@
+import type { BatchOperation } from '../storage/interface.ts';
+/** Normalize workflow tags for stable storage, filtering, and rendering. */
+export declare function normalizeWorkflowTags(tags: readonly string[] | undefined): string[] | undefined;
+/** True when a decoded value is a string array suitable for workflow tags. */
+export declare function isWorkflowTagArray(value: unknown): value is string[];
+/** Build the storage index delta for workflow tag changes. */
+export declare function buildWorkflowTagIndexOperations(workflowId: string, previousTags: readonly string[] | undefined, nextTags: readonly string[] | undefined): BatchOperation[];
+/** Match a workflow's tags against an intersection-style filter. */
+export declare function matchesWorkflowTagFilter(workflowTags: readonly string[] | undefined, filterTags: readonly string[] | undefined): boolean;

package/dist/core/workflow-tags.js

@@ -0,0 +1,37 @@
+import { KEYS } from "../storage/interface.js";
+const EMPTY_VALUE = new Uint8Array(0);
+export function normalizeWorkflowTags(tags) {
+  if (!tags || tags.length === 0)
+    return;
+  const normalized = [...new Set(tags.map((tag) => tag.trim()).filter((tag) => tag.length > 0))];
+  normalized.sort((left, right) => left.localeCompare(right));
+  return normalized.length > 0 ? normalized : void 0;
+}
+export function isWorkflowTagArray(value) {
+  return Array.isArray(value) && value.every((tag) => typeof tag === "string");
+}
+export function buildWorkflowTagIndexOperations(workflowId, previousTags, nextTags) {
+  const operations = [], previous = new Set(previousTags ?? []), next = new Set(nextTags ?? []);
+  for (const tag of previous)
+    if (!next.has(tag))
+      operations.push({
+        type: "delete",
+        key: KEYS.tagIndex(tag, workflowId)
+      });
+  for (const tag of next)
+    if (!previous.has(tag))
+      operations.push({
+        type: "put",
+        key: KEYS.tagIndex(tag, workflowId),
+        value: EMPTY_VALUE
+      });
+  return operations;
+}
+export function matchesWorkflowTagFilter(workflowTags, filterTags) {
+  if (!filterTags || filterTags.length === 0)
+    return !0;
+  if (!workflowTags || workflowTags.length === 0)
+    return !1;
+  const workflowTagSet = new Set(workflowTags);
+  return filterTags.every((tag) => workflowTagSet.has(tag));
+}

package/dist/core/workflow-version-tuple.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Workflow, agent, and tool version tuple utilities.
+ *
+ * Captures a `(workflowVersion, agentVersion, toolVersions[])` tuple on every
+ * event-log entry and provides diff utilities to detect mismatches between
+ * stored tuples and currently-registered definitions when resuming workflows.
+ *
+ * @module core/workflow-version-tuple
+ */
+/** Version tuple captured at workflow start and on every event-log entry. */
+export type WorkflowVersionTuple = {
+    workflowVersion: string;
+    agentVersion?: string;
+    /** Sorted `"${name}@${version}"` strings, one per tool. */
+    toolVersions?: string[];
+};
+/** A single tool-level version change surfaced by {@link diffWorkflowVersionTuples}. */
+export type WorkflowToolVersionChange = {
+    tool: string;
+    change: 'added';
+    to: string;
+} | {
+    tool: string;
+    change: 'removed';
+    from: string;
+} | {
+    tool: string;
+    change: 'changed';
+    from: string;
+    to: string;
+};
+/** Structured field-level diff between two {@link WorkflowVersionTuple}s. */
+export type WorkflowVersionDiff = {
+    workflowVersion?: [string, string];
+    agentVersion?: [string, string];
+    toolVersions?: WorkflowToolVersionChange[];
+};
+/**
+ * Collect sorted `"${name}@${version}"` version strings from a tool array.
+ *
+ * Each element must expose a flat `name` or the old internal
+ * `definition.name` compatibility shape, plus an optional `version`. Missing
+ * versions default to `"0.0.0"`. The returned array is sorted alphabetically
+ * so comparisons are order-independent.
+ */
+export declare function collectToolVersions(tools: Array<{
+    name: string;
+    version?: string | undefined;
+} | {
+    definition: {
+        name: string;
+    };
+    version?: string | undefined;
+}>): string[];
+/**
+ * Compare two {@link WorkflowVersionTuple}s and return structured field-level diffs.
+ *
+ * Only fields that actually differ are included in the output. An empty
+ * object means the tuples are identical.
+ */
+export declare function diffWorkflowVersionTuples(stored: WorkflowVersionTuple, registered: WorkflowVersionTuple): WorkflowVersionDiff;
+/**
+ * Format a human-readable summary of a {@link WorkflowVersionDiff} for error messages.
+ *
+ * Returns an empty string when the diff has no changes.
+ */
+export declare function formatWorkflowVersionDiff(diff: WorkflowVersionDiff): string;

package/dist/core/workflow-version-tuple.js

@@ -0,0 +1,77 @@
+export function collectToolVersions(tools) {
+  return tools.map((tool) => {
+    const name = "name" in tool ? tool.name : tool.definition.name;
+    if (!name)
+      throw Error("collectToolVersions: tool is missing a required name field");
+    return `${name}@${tool.version ?? "0.0.0"}`;
+  }).toSorted();
+}
+export function diffWorkflowVersionTuples(stored, registered) {
+  const diff = {};
+  if (stored.workflowVersion !== registered.workflowVersion)
+    diff.workflowVersion = [stored.workflowVersion, registered.workflowVersion];
+  const storedAgent = stored.agentVersion ?? "0.0.0", registeredAgent = registered.agentVersion ?? "0.0.0";
+  if (storedAgent !== registeredAgent)
+    diff.agentVersion = [storedAgent, registeredAgent];
+  const toolChanges = diffToolVersions(stored.toolVersions ?? [], registered.toolVersions ?? []);
+  if (toolChanges.length > 0)
+    diff.toolVersions = toolChanges;
+  return diff;
+}
+export function formatWorkflowVersionDiff(diff) {
+  const lines = [];
+  if (diff.workflowVersion) {
+    const [from, to] = diff.workflowVersion;
+    lines.push(`  - workflow version: ${from} \u2192 ${to}`);
+  }
+  if (diff.agentVersion) {
+    const [from, to] = diff.agentVersion;
+    lines.push(`  - agent version: ${from} \u2192 ${to}`);
+  }
+  if (diff.toolVersions)
+    for (const change of diff.toolVersions)
+      switch (change.change) {
+        case "added":
+          lines.push(`  - tool \`${change.tool}\` added (version: ${change.to})`);
+          break;
+        case "removed":
+          lines.push(`  - tool \`${change.tool}\` removed (was: ${change.from})`);
+          break;
+        case "changed":
+          lines.push(`  - tool \`${change.tool}\` version: ${change.from} \u2192 ${change.to}`);
+          break;
+      }
+  if (lines.length === 0)
+    return "";
+  return `
+Version tuple changes:
+${lines.join(`
+`)}`;
+}
+function parseToolVersionMap(versions) {
+  const map = new Map;
+  for (const entry of versions) {
+    const atIndex = entry.lastIndexOf("@");
+    if (atIndex > 0)
+      map.set(entry.slice(0, atIndex), entry.slice(atIndex + 1));
+  }
+  return map;
+}
+function diffToolVersions(storedVersions, registeredVersions) {
+  const storedTools = parseToolVersionMap(storedVersions), registeredTools = parseToolVersionMap(registeredVersions), allToolNames = new Set([...storedTools.keys(), ...registeredTools.keys()]), toolChanges = [];
+  for (const name of allToolNames) {
+    const change = diffToolVersion(name, storedTools.get(name), registeredTools.get(name));
+    if (change !== void 0)
+      toolChanges.push(change);
+  }
+  return toolChanges;
+}
+function diffToolVersion(tool, from, to) {
+  if (from === void 0 && to !== void 0)
+    return { tool, change: "added", to };
+  if (from !== void 0 && to === void 0)
+    return { tool, change: "removed", from };
+  if (from !== void 0 && to !== void 0 && from !== to)
+    return { tool, change: "changed", from, to };
+  return;
+}

package/dist/diagnostics/doctor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Diagnostic data collection for `weft doctor`.
+ *
+ * Inspects storage to gather database health, workflow statistics,
+ * and queue statistics, then generates actionable recommendations.
+ *
+ * @module diagnostics/doctor
+ */
+import type { Storage } from '../storage/interface.ts';
+import type { DiagnosticReport } from './types.ts';
+/**
+ * Collect diagnostics from a Weft storage instance.
+ *
+ * Gathers database health, workflow statistics, and queue statistics,
+ * then generates recommendations based on configurable thresholds.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage, collectDiagnostics } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * const report = await collectDiagnostics(storage, ':memory:');
+ * console.log(report.workflows.total);
+ * console.log(report.recommendations.length);
+ * ```
+ */
+export declare function collectDiagnostics(storage: Storage, databasePath: string, options?: {
+    now?: number;
+    sizeLimitBytes?: number;
+}): Promise<DiagnosticReport>;