@weavelogic/knowledge-graph-agent 0.2.0 → 0.3.0

package/dist/sops/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../src/sops/types.ts"],"sourcesContent":["/**\n * AI-SDLC SOP Types and Schemas\n *\n * Type definitions for AI-SDLC Standard Operating Procedures integration.\n * Based on https://github.com/AISDLC/AI-SDLC-SOPs\n *\n * @module sops/types\n */\n\n/**\n * SOP Categories aligned with AI-SDLC framework\n */\nexport enum SOPCategory {\n  /** Program and Project Management (1000-1010) */\n  PROGRAM_MANAGEMENT = 'program-management',\n\n  /** Operational and Maintenance (1011-1060) */\n  OPERATIONS = 'operations',\n\n  /** Training and Development (1100-1220) */\n  DEVELOPMENT = 'development',\n\n  /** Governance and Specialized Controls (1300-2000) */\n  GOVERNANCE = 'governance',\n\n  /** Quality Records (2000+) */\n  QUALITY = 'quality',\n}\n\n/**\n * SOP Compliance Status\n */\nexport enum ComplianceStatus {\n  /** Fully compliant with SOP requirements */\n  COMPLIANT = 'compliant',\n\n  /** Partially compliant - some requirements met */\n  PARTIAL = 'partial',\n\n  /** Not compliant - requirements not met */\n  NON_COMPLIANT = 'non-compliant',\n\n  /** Not applicable to this project */\n  NOT_APPLICABLE = 'not-applicable',\n\n  /** Not yet assessed */\n  PENDING = 'pending',\n}\n\n/**\n * SOP Priority/Risk Level\n */\nexport enum SOPPriority {\n  /** Critical - Must be addressed immediately */\n  CRITICAL = 'critical',\n\n  /** High - Should be addressed soon */\n  HIGH = 'high',\n\n  /** Medium - Address in normal course */\n  MEDIUM = 'medium',\n\n  /** Low - Nice to have */\n  LOW = 'low',\n}\n\n/**\n * AI-IRB Review Status\n */\nexport enum IRBStatus {\n  /** Requires IRB review */\n  REQUIRED = 'required',\n\n  /** IRB review in progress */\n  IN_REVIEW = 'in-review',\n\n  /** IRB approved */\n  APPROVED = 'approved',\n\n  /** IRB approval not required */\n  NOT_REQUIRED = 'not-required',\n\n  /** IRB review pending */\n  PENDING = 'pending',\n}\n\n/**\n * Knowledge Graph Layer Types\n */\nexport enum GraphLayer {\n  /** Foundation layer - AI-SDLC SOPs reference */\n  STANDARDS = 'standards',\n\n  /** Project implementation layer */\n  PROJECT = 'project',\n\n  /** Compliance overlay showing gaps */\n  COMPLIANCE = 'compliance',\n\n  /** Custom overlay */\n  CUSTOM = 'custom',\n}\n\n/**\n * SOP Requirement definition\n */\nexport interface SOPRequirement {\n  /** Requirement ID */\n  id: string;\n\n  /** Requirement description */\n  description: string;\n\n  /** Whether this requirement is mandatory */\n  mandatory: boolean;\n\n  /** Verification method */\n  verification: 'document' | 'test' | 'review' | 'audit' | 'automated';\n\n  /** Evidence required for compliance */\n  evidence: string[];\n\n  /** Related artifacts */\n  artifacts?: string[];\n}\n\n/**\n * SOP Checkpoint definition\n */\nexport interface SOPCheckpoint {\n  /** Checkpoint ID */\n  id: string;\n\n  /** Checkpoint name */\n  name: string;\n\n  /** When this checkpoint should be triggered */\n  trigger: 'phase-start' | 'phase-end' | 'milestone' | 'continuous' | 'scheduled';\n\n  /** Phase this checkpoint applies to */\n  phase?: string;\n\n  /** Requirements to verify at this checkpoint */\n  requirements: string[];\n\n  /** AI-IRB involvement */\n  irbRequired: boolean;\n\n  /** Approval authorities */\n  approvers: string[];\n}\n\n/**\n * SOP Definition\n */\nexport interface SOPDefinition {\n  /** SOP ID (e.g., \"SOP-1200-01-AI\") */\n  id: string;\n\n  /** SOP number (e.g., 1200) */\n  number: number;\n\n  /** SOP title */\n  title: string;\n\n  /** SOP description */\n  description: string;\n\n  /** SOP category */\n  category: SOPCategory;\n\n  /** Priority/risk level */\n  priority: SOPPriority;\n\n  /** Version */\n  version: string;\n\n  /** Source URL */\n  sourceUrl: string;\n\n  /** Scope description */\n  scope: string;\n\n  /** Requirements */\n  requirements: SOPRequirement[];\n\n  /** Checkpoints */\n  checkpoints: SOPCheckpoint[];\n\n  /** Related SOPs */\n  relatedSOPs: string[];\n\n  /** Tags for searching */\n  tags: string[];\n\n  /** Whether AI-IRB review is typically required */\n  irbTypicallyRequired: boolean;\n\n  /** Applicable project types */\n  applicableTo: string[];\n}\n\n/**\n * Project SOP Assessment\n */\nexport interface SOPAssessment {\n  /** SOP ID being assessed */\n  sopId: string;\n\n  /** Current compliance status */\n  status: ComplianceStatus;\n\n  /** Compliance score (0-100) */\n  score: number;\n\n  /** Requirements met */\n  requirementsMet: string[];\n\n  /** Requirements not met (gaps) */\n  requirementsGaps: string[];\n\n  /** Evidence provided */\n  evidence: Record<string, string>;\n\n  /** AI-IRB status */\n  irbStatus: IRBStatus;\n\n  /** Assessment date */\n  assessedAt: Date;\n\n  /** Assessor */\n  assessedBy: string;\n\n  /** Notes */\n  notes: string;\n\n  /** Remediation plan if non-compliant */\n  remediationPlan?: string;\n\n  /** Target compliance date */\n  targetDate?: Date;\n}\n\n/**\n * Compliance Gap\n */\nexport interface ComplianceGap {\n  /** Gap ID */\n  id: string;\n\n  /** SOP ID */\n  sopId: string;\n\n  /** Requirement ID */\n  requirementId: string;\n\n  /** Gap description */\n  description: string;\n\n  /** Priority */\n  priority: SOPPriority;\n\n  /** Impact description */\n  impact: string;\n\n  /** Recommended remediation */\n  remediation: string;\n\n  /** Effort estimate */\n  effort: 'low' | 'medium' | 'high';\n\n  /** Status */\n  status: 'open' | 'in-progress' | 'resolved' | 'accepted-risk';\n\n  /** Created date */\n  createdAt: Date;\n\n  /** Resolved date */\n  resolvedAt?: Date;\n}\n\n/**\n * Graph Layer Definition\n */\nexport interface LayerDefinition {\n  /** Layer ID */\n  id: string;\n\n  /** Layer name */\n  name: string;\n\n  /** Layer type */\n  type: GraphLayer;\n\n  /** Layer description */\n  description: string;\n\n  /** Whether layer is visible */\n  visible: boolean;\n\n  /** Layer order (for rendering) */\n  order: number;\n\n  /** Node filter for this layer */\n  nodeFilter?: (node: LayerNode) => boolean;\n\n  /** Edge filter for this layer */\n  edgeFilter?: (edge: LayerEdge) => boolean;\n\n  /** Metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Layer Node - extends base node with layer info\n */\nexport interface LayerNode {\n  /** Node ID */\n  id: string;\n\n  /** Node title */\n  title: string;\n\n  /** Node type */\n  type: string;\n\n  /** Layer this node belongs to */\n  layer: GraphLayer;\n\n  /** SOP reference (for standards layer) */\n  sopRef?: string;\n\n  /** Compliance status (for compliance layer) */\n  complianceStatus?: ComplianceStatus;\n\n  /** Tags */\n  tags: string[];\n\n  /** Metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Layer Edge - extends base edge with layer info\n */\nexport interface LayerEdge {\n  /** Source node ID */\n  source: string;\n\n  /** Target node ID */\n  target: string;\n\n  /** Edge type */\n  type: 'implements' | 'references' | 'depends-on' | 'compliance-gap' | 'wikilink';\n\n  /** Layer this edge belongs to */\n  layer: GraphLayer;\n\n  /** Weight */\n  weight: number;\n\n  /** Metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Multi-Layer Graph\n */\nexport interface MultiLayerGraph {\n  /** Graph ID */\n  id: string;\n\n  /** Graph name */\n  name: string;\n\n  /** Layers */\n  layers: LayerDefinition[];\n\n  /** All nodes across layers */\n  nodes: LayerNode[];\n\n  /** All edges across layers */\n  edges: LayerEdge[];\n\n  /** Cross-layer edges (connecting nodes in different layers) */\n  crossLayerEdges: LayerEdge[];\n\n  /** Metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Compliance Report\n */\nexport interface ComplianceReport {\n  /** Report ID */\n  id: string;\n\n  /** Project name */\n  projectName: string;\n\n  /** Report generation date */\n  generatedAt: Date;\n\n  /** Overall compliance score (0-100) */\n  overallScore: number;\n\n  /** SOP assessments */\n  assessments: SOPAssessment[];\n\n  /** Open gaps */\n  gaps: ComplianceGap[];\n\n  /** Summary by category */\n  categoryScores: Record<SOPCategory, number>;\n\n  /** Summary by priority */\n  priorityBreakdown: Record<SOPPriority, { total: number; compliant: number }>;\n\n  /** AI-IRB summary */\n  irbSummary: {\n    required: number;\n    approved: number;\n    pending: number;\n    inReview: number;\n  };\n\n  /** Recommendations */\n  recommendations: string[];\n}\n\n/**\n * SOP Node Frontmatter - extends standard frontmatter with SOP fields\n */\nexport interface SOPFrontmatter {\n  /** Standard frontmatter fields */\n  title?: string;\n  type?: string;\n  status?: string;\n  created?: string;\n  updated?: string;\n  tags?: string[];\n\n  /** SOP-specific fields */\n  sop?: {\n    /** SOP ID reference */\n    id?: string;\n\n    /** Compliance status */\n    status?: ComplianceStatus;\n\n    /** AI-IRB status */\n    irbStatus?: IRBStatus;\n\n    /** Requirements addressed */\n    requirements?: string[];\n\n    /** Evidence links */\n    evidence?: string[];\n\n    /** Last assessment date */\n    assessedAt?: string;\n\n    /** Assessor */\n    assessedBy?: string;\n\n    /** Notes */\n    notes?: string;\n  };\n\n  /** Layer assignment */\n  layer?: GraphLayer;\n}\n\n/**\n * SOP Configuration\n */\nexport interface SOPConfig {\n  /** Whether SOP compliance is enabled */\n  enabled: boolean;\n\n  /** Source repository for SOPs */\n  sourceRepo: string;\n\n  /** SOP version/tag to use */\n  version: string;\n\n  /** Categories to include */\n  categories: SOPCategory[];\n\n  /** Custom SOP definitions */\n  customSOPs?: SOPDefinition[];\n\n  /** Default IRB requirement */\n  defaultIRBRequired: boolean;\n\n  /** Auto-assessment configuration */\n  autoAssess?: {\n    /** Enable auto-assessment */\n    enabled: boolean;\n\n    /** Patterns to match for compliance */\n    patterns: Record<string, string[]>;\n  };\n}\n"],"names":["SOPCategory","ComplianceStatus","SOPPriority","IRBStatus","GraphLayer"],"mappings":"AAYO,IAAK,gCAAAA,iBAAL;AAELA,eAAA,oBAAA,IAAqB;AAGrBA,eAAA,YAAA,IAAa;AAGbA,eAAA,aAAA,IAAc;AAGdA,eAAA,YAAA,IAAa;AAGbA,eAAA,SAAA,IAAU;AAdA,SAAAA;AAAA,GAAA,eAAA,CAAA,CAAA;AAoBL,IAAK,qCAAAC,sBAAL;AAELA,oBAAA,WAAA,IAAY;AAGZA,oBAAA,SAAA,IAAU;AAGVA,oBAAA,eAAA,IAAgB;AAGhBA,oBAAA,gBAAA,IAAiB;AAGjBA,oBAAA,SAAA,IAAU;AAdA,SAAAA;AAAA,GAAA,oBAAA,CAAA,CAAA;AAoBL,IAAK,gCAAAC,iBAAL;AAELA,eAAA,UAAA,IAAW;AAGXA,eAAA,MAAA,IAAO;AAGPA,eAAA,QAAA,IAAS;AAGTA,eAAA,KAAA,IAAM;AAXI,SAAAA;AAAA,GAAA,eAAA,CAAA,CAAA;AAiBL,IAAK,8BAAAC,eAAL;AAELA,aAAA,UAAA,IAAW;AAGXA,aAAA,WAAA,IAAY;AAGZA,aAAA,UAAA,IAAW;AAGXA,aAAA,cAAA,IAAe;AAGfA,aAAA,SAAA,IAAU;AAdA,SAAAA;AAAA,GAAA,aAAA,CAAA,CAAA;AAoBL,IAAK,+BAAAC,gBAAL;AAELA,cAAA,WAAA,IAAY;AAGZA,cAAA,SAAA,IAAU;AAGVA,cAAA,YAAA,IAAa;AAGbA,cAAA,QAAA,IAAS;AAXC,SAAAA;AAAA,GAAA,cAAA,CAAA,CAAA;"}

package/dist/utils/error-recovery.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Error Recovery System
+ *
+ * Provides intelligent retry strategies with exponential backoff,
+ * jitter, and circuit breaker patterns. Based on weaver recovery patterns.
+ *
+ * @module utils/error-recovery
+ */
+import { type ClassifiedError } from './error-taxonomy.js';
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Backoff factor for exponential backoff (default: 2) */
+    backoffFactor?: number;
+    /** Whether to add random jitter (default: true) */
+    jitter?: boolean;
+    /** Jitter factor (0-1, default: 0.1) */
+    jitterFactor?: number;
+    /** Custom function to determine if error is retryable */
+    isRetryable?: (error: unknown) => boolean;
+    /** Called before each retry attempt */
+    onRetry?: (error: ClassifiedError, attempt: number, delay: number) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a retry operation
+ */
+export interface RetryResult<T> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The result value (if successful) */
+    value?: T;
+    /** The final error (if failed) */
+    error?: ClassifiedError;
+    /** Number of attempts made */
+    attempts: number;
+    /** Total time spent in milliseconds */
+    totalTime: number;
+}
+/**
+ * Circuit breaker state
+ */
+export declare enum CircuitState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "half_open"
+}
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before testing circuit again (default: 30000) */
+    resetTimeout?: number;
+    /** Number of successful tests before fully closing (default: 2) */
+    successThreshold?: number;
+    /** Whether to track errors by type (default: false) */
+    trackByErrorType?: boolean;
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successCount;
+    private lastFailureTime;
+    private readonly options;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Check if circuit allows execution
+     */
+    canExecute(): boolean;
+    /**
+     * Record a successful execution
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed execution
+     */
+    recordFailure(): void;
+    /**
+     * Reset the circuit breaker
+     */
+    reset(): void;
+}
+/**
+ * Calculate delay with exponential backoff
+ *
+ * @param attempt - The current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoff(attempt: number, options?: Pick<RetryOptions, 'initialDelay' | 'maxDelay' | 'backoffFactor' | 'jitter' | 'jitterFactor'>): number;
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Duration in milliseconds
+ * @param signal - Optional abort signal
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Execute operation with automatic retry
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry configuration
+ * @returns Result containing value or error
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxRetries: 5, onRetry: (err, attempt) => console.log(`Retry ${attempt}`) }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Data:', result.value);
+ * } else {
+ *   console.error('Failed after', result.attempts, 'attempts');
+ * }
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Execute operation with automatic retry (throws on failure)
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry configuration
+ * @returns The operation result
+ * @throws The last error if all retries fail
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = await retry(() => fetchData(), { maxRetries: 3 });
+ *   console.log('Data:', data);
+ * } catch (error) {
+ *   console.error('All retries failed:', error);
+ * }
+ * ```
+ */
+export declare function retry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Fallback chain options
+ */
+export interface FallbackOptions<T> {
+    /** Called when primary operation fails */
+    onFallback?: (error: ClassifiedError, index: number) => void;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Default value if all operations fail */
+    defaultValue?: T;
+}
+/**
+ * Execute with fallback chain
+ *
+ * Tries each operation in sequence until one succeeds.
+ *
+ * @param operations - Array of fallback operations
+ * @param options - Fallback configuration
+ * @returns The first successful result or default value
+ *
+ * @example
+ * ```typescript
+ * const data = await withFallback(
+ *   [
+ *     () => fetchFromPrimary(),
+ *     () => fetchFromSecondary(),
+ *     () => fetchFromCache(),
+ *   ],
+ *   { defaultValue: { cached: true, data: [] } }
+ * );
+ * ```
+ */
+export declare function withFallback<T>(operations: Array<() => Promise<T>>, options?: FallbackOptions<T>): Promise<T>;
+/**
+ * Execute with circuit breaker
+ *
+ * @param operation - The operation to execute
+ * @param breaker - Circuit breaker instance
+ * @returns The operation result
+ * @throws If circuit is open or operation fails
+ */
+export declare function withCircuitBreaker<T>(operation: () => Promise<T>, breaker: CircuitBreaker): Promise<T>;
+/**
+ * Create a retryable version of an async function
+ *
+ * @param fn - The async function to wrap
+ * @param options - Default retry options
+ * @returns A new function that automatically retries on failure
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = retryable(
+ *   (url: string) => fetch(url),
+ *   { maxRetries: 3 }
+ * );
+ *
+ * const response = await fetchWithRetry('https://api.example.com/data');
+ * ```
+ */
+export declare function retryable<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, options?: RetryOptions): (...args: TArgs) => Promise<TResult>;
+/**
+ * Error class for retries exhausted
+ */
+export declare class RetriesExhaustedError extends Error {
+    readonly lastError: ClassifiedError;
+    readonly attempts: number;
+    constructor(lastError: ClassifiedError, attempts: number);
+}
+/**
+ * Error class for circuit breaker open
+ */
+export declare class CircuitOpenError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=error-recovery.d.ts.map

package/dist/utils/error-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.d.ts","sourceRoot":"","sources":["../../src/utils/error-recovery.ts"],"names":[],"mappings":"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"}

package/dist/utils/error-recovery.js

@@ -0,0 +1,228 @@
+import { isRetryableError, classifyError, isRateLimitError } from "./error-taxonomy.js";
+var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
+  CircuitState2["CLOSED"] = "closed";
+  CircuitState2["OPEN"] = "open";
+  CircuitState2["HALF_OPEN"] = "half_open";
+  return CircuitState2;
+})(CircuitState || {});
+class CircuitBreaker {
+  state = "closed";
+  failures = 0;
+  successCount = 0;
+  lastFailureTime = 0;
+  options;
+  constructor(options = {}) {
+    this.options = {
+      failureThreshold: options.failureThreshold ?? 5,
+      resetTimeout: options.resetTimeout ?? 3e4,
+      successThreshold: options.successThreshold ?? 2,
+      trackByErrorType: options.trackByErrorType ?? false
+    };
+  }
+  /**
+   * Get current circuit state
+   */
+  getState() {
+    if (this.state === "open" && Date.now() - this.lastFailureTime >= this.options.resetTimeout) {
+      this.state = "half_open";
+      this.successCount = 0;
+    }
+    return this.state;
+  }
+  /**
+   * Check if circuit allows execution
+   */
+  canExecute() {
+    const state = this.getState();
+    return state === "closed" || state === "half_open";
+  }
+  /**
+   * Record a successful execution
+   */
+  recordSuccess() {
+    if (this.state === "half_open") {
+      this.successCount++;
+      if (this.successCount >= this.options.successThreshold) {
+        this.state = "closed";
+        this.failures = 0;
+        this.successCount = 0;
+      }
+    } else if (this.state === "closed") {
+      this.failures = 0;
+    }
+  }
+  /**
+   * Record a failed execution
+   */
+  recordFailure() {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+    if (this.state === "half_open") {
+      this.state = "open";
+      this.successCount = 0;
+    } else if (this.failures >= this.options.failureThreshold) {
+      this.state = "open";
+    }
+  }
+  /**
+   * Reset the circuit breaker
+   */
+  reset() {
+    this.state = "closed";
+    this.failures = 0;
+    this.successCount = 0;
+    this.lastFailureTime = 0;
+  }
+}
+function calculateBackoff(attempt, options = {}) {
+  const initialDelay = options.initialDelay ?? 1e3;
+  const maxDelay = options.maxDelay ?? 3e4;
+  const backoffFactor = options.backoffFactor ?? 2;
+  const jitter = options.jitter ?? true;
+  const jitterFactor = options.jitterFactor ?? 0.1;
+  let delay = initialDelay * Math.pow(backoffFactor, attempt - 1);
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    const jitterAmount = delay * jitterFactor;
+    delay = delay + (Math.random() * 2 - 1) * jitterAmount;
+  }
+  return Math.round(delay);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Aborted"));
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(new Error("Aborted"));
+    });
+  });
+}
+async function withRetry(operation, options = {}) {
+  const maxRetries = options.maxRetries ?? 3;
+  const isRetryable = options.isRetryable ?? isRetryableError;
+  const startTime = Date.now();
+  let attempt = 0;
+  let lastError;
+  while (attempt <= maxRetries) {
+    try {
+      if (options.signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+      const value = await operation();
+      return {
+        success: true,
+        value,
+        attempts: attempt + 1,
+        totalTime: Date.now() - startTime
+      };
+    } catch (error) {
+      const classified = classifyError(error);
+      lastError = classified;
+      attempt++;
+      if (attempt > maxRetries) {
+        break;
+      }
+      if (!isRetryable(error)) {
+        break;
+      }
+      let delay = calculateBackoff(attempt, options);
+      if (isRateLimitError(error) && classified.suggestedDelay > delay) {
+        delay = classified.suggestedDelay;
+      }
+      options.onRetry?.(classified, attempt, delay);
+      try {
+        await sleep(delay, options.signal);
+      } catch {
+        break;
+      }
+    }
+  }
+  return {
+    success: false,
+    error: lastError,
+    attempts: attempt,
+    totalTime: Date.now() - startTime
+  };
+}
+async function retry(operation, options = {}) {
+  const result = await withRetry(operation, options);
+  if (result.success) {
+    return result.value;
+  }
+  throw result.error?.original ?? new Error("Operation failed");
+}
+async function withFallback(operations, options = {}) {
+  if (operations.length === 0) {
+    if (options.defaultValue !== void 0) {
+      return options.defaultValue;
+    }
+    throw new Error("No fallback operations provided");
+  }
+  let lastError;
+  for (let i = 0; i < operations.length; i++) {
+    try {
+      if (options.signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+      return await operations[i]();
+    } catch (error) {
+      const classified = classifyError(error);
+      lastError = classified;
+      options.onFallback?.(classified, i);
+    }
+  }
+  if (options.defaultValue !== void 0) {
+    return options.defaultValue;
+  }
+  throw lastError?.original ?? new Error("All fallback operations failed");
+}
+async function withCircuitBreaker(operation, breaker) {
+  if (!breaker.canExecute()) {
+    throw new Error("Circuit breaker is open");
+  }
+  try {
+    const result = await operation();
+    breaker.recordSuccess();
+    return result;
+  } catch (error) {
+    breaker.recordFailure();
+    throw error;
+  }
+}
+function retryable(fn, options = {}) {
+  return (...args) => retry(() => fn(...args), options);
+}
+class RetriesExhaustedError extends Error {
+  lastError;
+  attempts;
+  constructor(lastError, attempts) {
+    super(`All ${attempts} retry attempts exhausted: ${lastError.message}`);
+    this.name = "RetriesExhaustedError";
+    this.lastError = lastError;
+    this.attempts = attempts;
+  }
+}
+class CircuitOpenError extends Error {
+  constructor(message = "Circuit breaker is open") {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+}
+export {
+  CircuitBreaker,
+  CircuitOpenError,
+  CircuitState,
+  RetriesExhaustedError,
+  calculateBackoff,
+  retry,
+  retryable,
+  sleep,
+  withCircuitBreaker,
+  withFallback,
+  withRetry
+};
+//# sourceMappingURL=error-recovery.js.map

package/dist/utils/error-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.js","sources":["../../src/utils/error-recovery.ts"],"sourcesContent":["/**\n * Error Recovery System\n *\n * Provides intelligent retry strategies with exponential backoff,\n * jitter, and circuit breaker patterns. Based on weaver recovery patterns.\n *\n * @module utils/error-recovery\n */\n\nimport {\n  classifyError,\n  ErrorCategory,\n  type ClassifiedError,\n  isRetryableError,\n  isRateLimitError,\n} from './error-taxonomy.js';\n\n/**\n * Retry configuration options\n */\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxRetries?: number;\n\n  /** Initial delay in milliseconds (default: 1000) */\n  initialDelay?: number;\n\n  /** Maximum delay in milliseconds (default: 30000) */\n  maxDelay?: number;\n\n  /** Backoff factor for exponential backoff (default: 2) */\n  backoffFactor?: number;\n\n  /** Whether to add random jitter (default: true) */\n  jitter?: boolean;\n\n  /** Jitter factor (0-1, default: 0.1) */\n  jitterFactor?: number;\n\n  /** Custom function to determine if error is retryable */\n  isRetryable?: (error: unknown) => boolean;\n\n  /** Called before each retry attempt */\n  onRetry?: (error: ClassifiedError, attempt: number, delay: number) => void;\n\n  /** Abort signal for cancellation */\n  signal?: AbortSignal;\n}\n\n/**\n * Result of a retry operation\n */\nexport interface RetryResult<T> {\n  /** Whether the operation succeeded */\n  success: boolean;\n\n  /** The result value (if successful) */\n  value?: T;\n\n  /** The final error (if failed) */\n  error?: ClassifiedError;\n\n  /** Number of attempts made */\n  attempts: number;\n\n  /** Total time spent in milliseconds */\n  totalTime: number;\n}\n\n/**\n * Circuit breaker state\n */\nexport enum CircuitState {\n  CLOSED = 'closed',\n  OPEN = 'open',\n  HALF_OPEN = 'half_open',\n}\n\n/**\n * Circuit breaker configuration\n */\nexport interface CircuitBreakerOptions {\n  /** Number of failures before opening circuit (default: 5) */\n  failureThreshold?: number;\n\n  /** Time in ms before testing circuit again (default: 30000) */\n  resetTimeout?: number;\n\n  /** Number of successful tests before fully closing (default: 2) */\n  successThreshold?: number;\n\n  /** Whether to track errors by type (default: false) */\n  trackByErrorType?: boolean;\n}\n\n/**\n * Circuit breaker for protecting against cascading failures\n */\nexport class CircuitBreaker {\n  private state = CircuitState.CLOSED;\n  private failures = 0;\n  private successCount = 0;\n  private lastFailureTime = 0;\n  private readonly options: Required<CircuitBreakerOptions>;\n\n  constructor(options: CircuitBreakerOptions = {}) {\n    this.options = {\n      failureThreshold: options.failureThreshold ?? 5,\n      resetTimeout: options.resetTimeout ?? 30000,\n      successThreshold: options.successThreshold ?? 2,\n      trackByErrorType: options.trackByErrorType ?? false,\n    };\n  }\n\n  /**\n   * Get current circuit state\n   */\n  getState(): CircuitState {\n    // Check if we should transition from OPEN to HALF_OPEN\n    if (\n      this.state === CircuitState.OPEN &&\n      Date.now() - this.lastFailureTime >= this.options.resetTimeout\n    ) {\n      this.state = CircuitState.HALF_OPEN;\n      this.successCount = 0;\n    }\n    return this.state;\n  }\n\n  /**\n   * Check if circuit allows execution\n   */\n  canExecute(): boolean {\n    const state = this.getState();\n    return state === CircuitState.CLOSED || state === CircuitState.HALF_OPEN;\n  }\n\n  /**\n   * Record a successful execution\n   */\n  recordSuccess(): void {\n    if (this.state === CircuitState.HALF_OPEN) {\n      this.successCount++;\n      if (this.successCount >= this.options.successThreshold) {\n        this.state = CircuitState.CLOSED;\n        this.failures = 0;\n        this.successCount = 0;\n      }\n    } else if (this.state === CircuitState.CLOSED) {\n      // Reset failures on success\n      this.failures = 0;\n    }\n  }\n\n  /**\n   * Record a failed execution\n   */\n  recordFailure(): void {\n    this.failures++;\n    this.lastFailureTime = Date.now();\n\n    if (this.state === CircuitState.HALF_OPEN) {\n      // Any failure in half-open returns to open\n      this.state = CircuitState.OPEN;\n      this.successCount = 0;\n    } else if (this.failures >= this.options.failureThreshold) {\n      this.state = CircuitState.OPEN;\n    }\n  }\n\n  /**\n   * Reset the circuit breaker\n   */\n  reset(): void {\n    this.state = CircuitState.CLOSED;\n    this.failures = 0;\n    this.successCount = 0;\n    this.lastFailureTime = 0;\n  }\n}\n\n/**\n * Calculate delay with exponential backoff\n *\n * @param attempt - The current attempt number (1-based)\n * @param options - Retry options\n * @returns Delay in milliseconds\n */\nexport function calculateBackoff(\n  attempt: number,\n  options: Pick<RetryOptions, 'initialDelay' | 'maxDelay' | 'backoffFactor' | 'jitter' | 'jitterFactor'> = {}\n): number {\n  const initialDelay = options.initialDelay ?? 1000;\n  const maxDelay = options.maxDelay ?? 30000;\n  const backoffFactor = options.backoffFactor ?? 2;\n  const jitter = options.jitter ?? true;\n  const jitterFactor = options.jitterFactor ?? 0.1;\n\n  // Calculate exponential delay\n  let delay = initialDelay * Math.pow(backoffFactor, attempt - 1);\n\n  // Cap at maximum\n  delay = Math.min(delay, maxDelay);\n\n  // Add jitter if enabled\n  if (jitter) {\n    const jitterAmount = delay * jitterFactor;\n    delay = delay + (Math.random() * 2 - 1) * jitterAmount;\n  }\n\n  return Math.round(delay);\n}\n\n/**\n * Sleep for specified duration\n *\n * @param ms - Duration in milliseconds\n * @param signal - Optional abort signal\n */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new Error('Aborted'));\n      return;\n    }\n\n    const timeout = setTimeout(resolve, ms);\n\n    signal?.addEventListener('abort', () => {\n      clearTimeout(timeout);\n      reject(new Error('Aborted'));\n    });\n  });\n}\n\n/**\n * Execute operation with automatic retry\n *\n * @param operation - The async operation to execute\n * @param options - Retry configuration\n * @returns Result containing value or error\n *\n * @example\n * ```typescript\n * const result = await withRetry(\n *   () => fetchData(),\n *   { maxRetries: 5, onRetry: (err, attempt) => console.log(`Retry ${attempt}`) }\n * );\n *\n * if (result.success) {\n *   console.log('Data:', result.value);\n * } else {\n *   console.error('Failed after', result.attempts, 'attempts');\n * }\n * ```\n */\nexport async function withRetry<T>(\n  operation: () => Promise<T>,\n  options: RetryOptions = {}\n): Promise<RetryResult<T>> {\n  const maxRetries = options.maxRetries ?? 3;\n  const isRetryable = options.isRetryable ?? isRetryableError;\n\n  const startTime = Date.now();\n  let attempt = 0;\n  let lastError: ClassifiedError | undefined;\n\n  while (attempt <= maxRetries) {\n    try {\n      // Check for abort\n      if (options.signal?.aborted) {\n        throw new Error('Operation aborted');\n      }\n\n      const value = await operation();\n      return {\n        success: true,\n        value,\n        attempts: attempt + 1,\n        totalTime: Date.now() - startTime,\n      };\n    } catch (error) {\n      const classified = classifyError(error);\n      lastError = classified;\n      attempt++;\n\n      // Don't retry if we've exhausted attempts\n      if (attempt > maxRetries) {\n        break;\n      }\n\n      // Don't retry non-retryable errors\n      if (!isRetryable(error)) {\n        break;\n      }\n\n      // Calculate delay\n      let delay = calculateBackoff(attempt, options);\n\n      // Use suggested delay for rate limits (often includes Retry-After header)\n      if (isRateLimitError(error) && classified.suggestedDelay > delay) {\n        delay = classified.suggestedDelay;\n      }\n\n      // Notify about retry\n      options.onRetry?.(classified, attempt, delay);\n\n      // Wait before retry\n      try {\n        await sleep(delay, options.signal);\n      } catch {\n        // Aborted during sleep\n        break;\n      }\n    }\n  }\n\n  return {\n    success: false,\n    error: lastError,\n    attempts: attempt,\n    totalTime: Date.now() - startTime,\n  };\n}\n\n/**\n * Execute operation with automatic retry (throws on failure)\n *\n * @param operation - The async operation to execute\n * @param options - Retry configuration\n * @returns The operation result\n * @throws The last error if all retries fail\n *\n * @example\n * ```typescript\n * try {\n *   const data = await retry(() => fetchData(), { maxRetries: 3 });\n *   console.log('Data:', data);\n * } catch (error) {\n *   console.error('All retries failed:', error);\n * }\n * ```\n */\nexport async function retry<T>(\n  operation: () => Promise<T>,\n  options: RetryOptions = {}\n): Promise<T> {\n  const result = await withRetry(operation, options);\n\n  if (result.success) {\n    return result.value as T;\n  }\n\n  // Throw the original error\n  throw result.error?.original ?? new Error('Operation failed');\n}\n\n/**\n * Fallback chain options\n */\nexport interface FallbackOptions<T> {\n  /** Called when primary operation fails */\n  onFallback?: (error: ClassifiedError, index: number) => void;\n\n  /** Abort signal */\n  signal?: AbortSignal;\n\n  /** Default value if all operations fail */\n  defaultValue?: T;\n}\n\n/**\n * Execute with fallback chain\n *\n * Tries each operation in sequence until one succeeds.\n *\n * @param operations - Array of fallback operations\n * @param options - Fallback configuration\n * @returns The first successful result or default value\n *\n * @example\n * ```typescript\n * const data = await withFallback(\n *   [\n *     () => fetchFromPrimary(),\n *     () => fetchFromSecondary(),\n *     () => fetchFromCache(),\n *   ],\n *   { defaultValue: { cached: true, data: [] } }\n * );\n * ```\n */\nexport async function withFallback<T>(\n  operations: Array<() => Promise<T>>,\n  options: FallbackOptions<T> = {}\n): Promise<T> {\n  if (operations.length === 0) {\n    if (options.defaultValue !== undefined) {\n      return options.defaultValue;\n    }\n    throw new Error('No fallback operations provided');\n  }\n\n  let lastError: ClassifiedError | undefined;\n\n  for (let i = 0; i < operations.length; i++) {\n    try {\n      if (options.signal?.aborted) {\n        throw new Error('Operation aborted');\n      }\n\n      return await operations[i]();\n    } catch (error) {\n      const classified = classifyError(error);\n      lastError = classified;\n      options.onFallback?.(classified, i);\n    }\n  }\n\n  if (options.defaultValue !== undefined) {\n    return options.defaultValue;\n  }\n\n  throw lastError?.original ?? new Error('All fallback operations failed');\n}\n\n/**\n * Execute with circuit breaker\n *\n * @param operation - The operation to execute\n * @param breaker - Circuit breaker instance\n * @returns The operation result\n * @throws If circuit is open or operation fails\n */\nexport async function withCircuitBreaker<T>(\n  operation: () => Promise<T>,\n  breaker: CircuitBreaker\n): Promise<T> {\n  if (!breaker.canExecute()) {\n    throw new Error('Circuit breaker is open');\n  }\n\n  try {\n    const result = await operation();\n    breaker.recordSuccess();\n    return result;\n  } catch (error) {\n    breaker.recordFailure();\n    throw error;\n  }\n}\n\n/**\n * Create a retryable version of an async function\n *\n * @param fn - The async function to wrap\n * @param options - Default retry options\n * @returns A new function that automatically retries on failure\n *\n * @example\n * ```typescript\n * const fetchWithRetry = retryable(\n *   (url: string) => fetch(url),\n *   { maxRetries: 3 }\n * );\n *\n * const response = await fetchWithRetry('https://api.example.com/data');\n * ```\n */\nexport function retryable<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  options: RetryOptions = {}\n): (...args: TArgs) => Promise<TResult> {\n  return (...args: TArgs) => retry(() => fn(...args), options);\n}\n\n/**\n * Error class for retries exhausted\n */\nexport class RetriesExhaustedError extends Error {\n  public readonly lastError: ClassifiedError;\n  public readonly attempts: number;\n\n  constructor(lastError: ClassifiedError, attempts: number) {\n    super(`All ${attempts} retry attempts exhausted: ${lastError.message}`);\n    this.name = 'RetriesExhaustedError';\n    this.lastError = lastError;\n    this.attempts = attempts;\n  }\n}\n\n/**\n * Error class for circuit breaker open\n */\nexport class CircuitOpenError extends Error {\n  constructor(message = 'Circuit breaker is open') {\n    super(message);\n    this.name = 'CircuitOpenError';\n  }\n}\n"],"names":["CircuitState"],"mappings":"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"}

package/dist/utils/error-taxonomy.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Error Taxonomy System
+ *
+ * Provides structured error classification for intelligent retry strategies
+ * and graceful degradation. Based on weaver error handling patterns.
+ *
+ * @module utils/error-taxonomy
+ */
+/**
+ * Error categories for classification and recovery strategy selection
+ */
+export declare enum ErrorCategory {
+    /** Transient errors that may succeed on retry (network hiccups, temporary failures) */
+    TRANSIENT = "transient",
+    /** Permanent errors that won't succeed on retry (invalid input, missing resources) */
+    PERMANENT = "permanent",
+    /** Rate limit errors requiring backoff (429 responses) */
+    RATE_LIMIT = "rate_limit",
+    /** Network connectivity errors (DNS, connection refused) */
+    NETWORK = "network",
+    /** Input validation errors (schema violations, type mismatches) */
+    VALIDATION = "validation",
+    /** Resource errors (file not found, permissions) */
+    RESOURCE = "resource",
+    /** Configuration errors (missing config, invalid settings) */
+    CONFIGURATION = "configuration",
+    /** Timeout errors (operation exceeded time limit) */
+    TIMEOUT = "timeout",
+    /** Unknown errors that couldn't be classified */
+    UNKNOWN = "unknown"
+}
+/**
+ * Error severity levels
+ */
+export declare enum ErrorSeverity {
+    /** Informational - operation can continue */
+    INFO = "info",
+    /** Warning - operation continues with degraded functionality */
+    WARNING = "warning",
+    /** Error - operation failed but system stable */
+    ERROR = "error",
+    /** Critical - operation failed, may affect system stability */
+    CRITICAL = "critical",
+    /** Fatal - system cannot continue */
+    FATAL = "fatal"
+}
+/**
+ * Classified error with metadata
+ */
+export interface ClassifiedError {
+    /** Original error */
+    original: Error | unknown;
+    /** Classified category */
+    category: ErrorCategory;
+    /** Error severity */
+    severity: ErrorSeverity;
+    /** Whether retry is recommended */
+    retryable: boolean;
+    /** Suggested delay before retry (milliseconds) */
+    suggestedDelay: number;
+    /** Error message */
+    message: string;
+    /** Error code if available */
+    code?: string;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Classify an error into a category with recovery metadata
+ *
+ * @param error - The error to classify
+ * @returns Classified error with recovery recommendations
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetchData();
+ * } catch (error) {
+ *   const classified = classifyError(error);
+ *   if (classified.retryable) {
+ *     await delay(classified.suggestedDelay);
+ *     return retry();
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function classifyError(error: unknown): ClassifiedError;
+/**
+ * Check if an error is retryable
+ *
+ * @param error - The error to check
+ * @returns Whether the error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Check if an error is transient (temporary failure)
+ *
+ * @param error - The error to check
+ * @returns Whether the error is transient
+ */
+export declare function isTransientError(error: unknown): boolean;
+/**
+ * Check if an error is a rate limit error
+ *
+ * @param error - The error to check
+ * @returns Whether the error is a rate limit error
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Check if an error is permanent (won't succeed on retry)
+ *
+ * @param error - The error to check
+ * @returns Whether the error is permanent
+ */
+export declare function isPermanentError(error: unknown): boolean;
+/**
+ * Custom error class for knowledge graph operations
+ */
+export declare class KnowledgeGraphError extends Error {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly retryable: boolean;
+    readonly code?: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        retryable?: boolean;
+        code?: string;
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+}
+/**
+ * Create a validation error
+ */
+export declare function createValidationError(message: string, context?: Record<string, unknown>): KnowledgeGraphError;
+/**
+ * Create a configuration error
+ */
+export declare function createConfigurationError(message: string, context?: Record<string, unknown>): KnowledgeGraphError;
+/**
+ * Create a resource error
+ */
+export declare function createResourceError(message: string, context?: Record<string, unknown>): KnowledgeGraphError;
+//# sourceMappingURL=error-taxonomy.d.ts.map