@nomos-arc/arc 0.1.0

package/src/core/graph/drift/classifier.ts

@@ -0,0 +1,165 @@
+import type {
+  DriftReport,
+  ClassifiedDrift,
+  ClassifiedChange,
+  DriftSeverity,
+} from '../../../types/index.js';
+
+/**
+ * classify — takes a DriftReport and classifies each change by severity.
+ * Returns a ClassifiedDrift with all changes annotated, has_breaking flag, and summary.
+ */
+export function classify(report: DriftReport): ClassifiedDrift {
+  const changes: ClassifiedChange[] = [];
+
+  // ── Symbol classification ─────────────────────────────────────────────────
+  for (const sym of report.symbols) {
+    if (sym.status === 'added') {
+      changes.push({
+        severity: 'info',
+        category: 'symbol',
+        message: `Symbol '${sym.name}' (${sym.kind}) added in ${sym.file}`,
+        file: sym.file,
+        detail: `Exported: ${sym.exported}`,
+        suggestion: "New symbol — no breaking impact.",
+      });
+      continue;
+    }
+
+    // removed or signature_changed
+    if (sym.exported && sym.dependents_affected.length > 0) {
+      const action = sym.status === 'removed' ? 'removed' : 'signature changed';
+      changes.push({
+        severity: 'breaking',
+        category: 'symbol',
+        message: `Exported symbol '${sym.name}' (${sym.kind}) ${action} in ${sym.file}`,
+        file: sym.file,
+        detail:
+          sym.status === 'signature_changed'
+            ? `Before: ${sym.signature_before ?? 'none'} | After: ${sym.signature_after ?? 'none'}`
+            : `Affects ${sym.dependents_affected.length} dependent(s): ${sym.dependents_affected.join(', ')}`,
+        suggestion: `Update all ${sym.dependents_affected.length} dependent(s) that reference '${sym.name}'.`,
+      });
+    } else if (sym.exported && sym.dependents_affected.length === 0) {
+      const action = sym.status === 'removed' ? 'removed' : 'signature changed';
+      changes.push({
+        severity: 'warning',
+        category: 'symbol',
+        message: `Exported symbol '${sym.name}' (${sym.kind}) ${action} in ${sym.file}`,
+        file: sym.file,
+        detail:
+          sym.status === 'signature_changed'
+            ? `Before: ${sym.signature_before ?? 'none'} | After: ${sym.signature_after ?? 'none'}`
+            : 'No tracked dependents, but public API has changed.',
+        suggestion: `Check for external consumers of '${sym.name}' not tracked in the project map.`,
+      });
+    } else {
+      // Not exported
+      const action = sym.status === 'removed' ? 'removed' : 'signature changed';
+      changes.push({
+        severity: 'info',
+        category: 'symbol',
+        message: `Internal symbol '${sym.name}' (${sym.kind}) ${action} in ${sym.file}`,
+        file: sym.file,
+        detail:
+          sym.status === 'signature_changed'
+            ? `Before: ${sym.signature_before ?? 'none'} | After: ${sym.signature_after ?? 'none'}`
+            : 'Non-exported symbol removed — no public API impact.',
+        suggestion: 'No action required — internal change only.',
+      });
+    }
+  }
+
+  // ── File classification ───────────────────────────────────────────────────
+  for (const f of report.files) {
+    if (f.status === 'removed') {
+      changes.push({
+        severity: 'warning',
+        category: 'file',
+        message: `File removed: ${f.file}`,
+        file: f.file,
+        detail: `Hash before: ${f.hash_before}`,
+        suggestion: `Check dependent files that imported from '${f.file}'.`,
+      });
+    } else if (f.status === 'added') {
+      changes.push({
+        severity: 'info',
+        category: 'file',
+        message: `File added: ${f.file}`,
+        file: f.file,
+        detail: `Hash after: ${f.hash_after}`,
+        suggestion: 'New file — no breaking impact.',
+      });
+    }
+    // modified → covered by symbol and import diffs — no standalone change entry
+  }
+
+  // ── Import classification ─────────────────────────────────────────────────
+  for (const imp of report.imports) {
+    changes.push({
+      severity: 'info',
+      category: 'import',
+      message: `Import '${imp.source}' ${imp.status} in ${imp.file}`,
+      file: imp.file,
+      detail: `Status: ${imp.status}`,
+      suggestion: 'Verify import graph integrity after this change.',
+    });
+  }
+
+  // ── Graph classification ──────────────────────────────────────────────────
+  for (const mod of report.graph.core_modules_added) {
+    changes.push({
+      severity: 'info',
+      category: 'graph',
+      message: `Module promoted to core: ${mod}`,
+      file: mod,
+      detail: 'Module is now in the core_modules list.',
+      suggestion: 'No action required — module importance increased.',
+    });
+  }
+
+  for (const mod of report.graph.core_modules_removed) {
+    changes.push({
+      severity: 'warning',
+      category: 'graph',
+      message: `Module demoted from core: ${mod}`,
+      file: mod,
+      detail: 'Module was removed from the core_modules list.',
+      suggestion: 'Verify this module is still in use or intentionally demoted.',
+    });
+  }
+
+  for (const dc of report.graph.depth_changes) {
+    const delta = dc.after - dc.before;
+    if (Math.abs(delta) >= 2) {
+      changes.push({
+        severity: 'warning',
+        category: 'graph',
+        message: `Significant depth change in ${dc.file}: ${dc.before} → ${dc.after}`,
+        file: dc.file,
+        detail: `Depth delta: ${delta > 0 ? '+' : ''}${delta}`,
+        suggestion: 'Review the dependency chain — significant structural shift detected.',
+      });
+    }
+  }
+
+  // ── Enrichment staleness classification ───────────────────────────────────
+  for (const stale of report.stale_enrichments) {
+    if (stale.hash_changed) {
+      changes.push({
+        severity: 'stale',
+        category: 'enrichment',
+        message: `Stale enrichment detected in ${stale.file}`,
+        file: stale.file,
+        detail: stale.was_semantic_now_structural
+          ? 'File was semantically enriched but is now structural — enrichment regression.'
+          : 'File hash changed but semantic data was not updated.',
+        suggestion: `Run 'arc map' with AI enrichment to refresh semantic data for ${stale.file}.`,
+      });
+    }
+  }
+
+  const has_breaking = changes.some((c) => c.severity === 'breaking');
+
+  return { changes, has_breaking, summary: report.summary };
+}

package/src/core/graph/drift/comparator.ts

@@ -0,0 +1,205 @@
+import type {
+  ProjectMap,
+  DriftReport,
+  FileDiff,
+  SymbolDiff,
+  ImportDiff,
+  GraphDiff,
+  EnrichmentStaleness,
+} from '../../../types/index.js';
+
+/**
+ * compare — pure function that diffs two ProjectMap objects and returns a DriftReport.
+ * No I/O, no side effects.
+ */
+export function compare(baseline: ProjectMap, current: ProjectMap): DriftReport {
+  const files: FileDiff[] = [];
+  const symbols: SymbolDiff[] = [];
+  const imports: ImportDiff[] = [];
+  const stale_enrichments: EnrichmentStaleness[] = [];
+
+  // ── 6.1 File-Level Diff ────────────────────────────────────────────────────
+  const allFileKeys = new Set([
+    ...Object.keys(baseline.files),
+    ...Object.keys(current.files),
+  ]);
+
+  for (const fileKey of allFileKeys) {
+    const baseFile = baseline.files[fileKey];
+    const currFile = current.files[fileKey];
+
+    if (!baseFile && currFile) {
+      // Added
+      files.push({
+        file: fileKey,
+        status: 'added',
+        hash_before: null,
+        hash_after: currFile.hash,
+      });
+    } else if (baseFile && !currFile) {
+      // Removed
+      files.push({
+        file: fileKey,
+        status: 'removed',
+        hash_before: baseFile.hash,
+        hash_after: null,
+      });
+
+      // ── 6.2 All symbols in removed file are 'removed' ─────────────────────
+      for (const sym of baseFile.symbols) {
+        symbols.push({
+          file: fileKey,
+          name: sym.name,
+          kind: sym.kind,
+          status: 'removed',
+          exported: sym.exported,
+          signature_before: sym.signature,
+          signature_after: null,
+          dependents_affected: [...baseFile.dependents],
+        });
+      }
+    } else if (baseFile && currFile) {
+      if (baseFile.hash === currFile.hash) {
+        // Unchanged — skip
+        continue;
+      }
+
+      // Modified
+      files.push({
+        file: fileKey,
+        status: 'modified',
+        hash_before: baseFile.hash,
+        hash_after: currFile.hash,
+      });
+
+      // ── 6.2 Symbol-Level Diff for modified files ───────────────────────────
+      // Use `name:kind` composite key to handle same-named symbols of different kinds (F-003)
+      const baseSymMap = new Map<string, (typeof baseFile.symbols)[0]>();
+      for (const sym of baseFile.symbols) {
+        baseSymMap.set(`${sym.name}:${sym.kind}`, sym);
+      }
+
+      const currSymMap = new Map<string, (typeof currFile.symbols)[0]>();
+      for (const sym of currFile.symbols) {
+        currSymMap.set(`${sym.name}:${sym.kind}`, sym);
+      }
+
+      // Detect removed and signature_changed
+      for (const [key, baseSym] of baseSymMap) {
+        const currSym = currSymMap.get(key);
+        if (!currSym) {
+          symbols.push({
+            file: fileKey,
+            name: baseSym.name,
+            kind: baseSym.kind,
+            status: 'removed',
+            exported: baseSym.exported,
+            signature_before: baseSym.signature,
+            signature_after: null,
+            dependents_affected: [...baseFile.dependents],
+          });
+        } else if (baseSym.signature !== currSym.signature) {
+          symbols.push({
+            file: fileKey,
+            name: baseSym.name,
+            kind: baseSym.kind,
+            status: 'signature_changed',
+            exported: baseSym.exported,
+            signature_before: baseSym.signature,
+            signature_after: currSym.signature,
+            dependents_affected: [...baseFile.dependents],
+          });
+        }
+      }
+
+      // Detect added
+      for (const [key, currSym] of currSymMap) {
+        if (!baseSymMap.has(key)) {
+          symbols.push({
+            file: fileKey,
+            name: currSym.name,
+            kind: currSym.kind,
+            status: 'added',
+            exported: currSym.exported,
+            signature_before: null,
+            signature_after: currSym.signature,
+            dependents_affected: [],
+          });
+        }
+      }
+
+      // ── 6.3 Import-Level Diff for modified files (internal only) ──────────
+      const baseInternalImports = new Set(
+        baseFile.imports
+          .filter((i) => !i.is_external && i.resolved !== null)
+          .map((i) => i.resolved as string),
+      );
+      const currInternalImports = new Set(
+        currFile.imports
+          .filter((i) => !i.is_external && i.resolved !== null)
+          .map((i) => i.resolved as string),
+      );
+
+      for (const resolved of currInternalImports) {
+        if (!baseInternalImports.has(resolved)) {
+          imports.push({ file: fileKey, source: resolved, status: 'added' });
+        }
+      }
+      for (const resolved of baseInternalImports) {
+        if (!currInternalImports.has(resolved)) {
+          imports.push({ file: fileKey, source: resolved, status: 'removed' });
+        }
+      }
+    }
+  }
+
+  // ── 6.4 Graph-Level Diff ──────────────────────────────────────────────────
+  const depth_changes: GraphDiff['depth_changes'] = [];
+  for (const fileKey of Object.keys(baseline.files)) {
+    const baseFile = baseline.files[fileKey];
+    const currFile = current.files[fileKey];
+    if (baseFile && currFile && baseFile.depth !== currFile.depth) {
+      depth_changes.push({ file: fileKey, before: baseFile.depth, after: currFile.depth });
+    }
+  }
+
+  const baseCore = new Set(baseline.stats.core_modules);
+  const currCore = new Set(current.stats.core_modules);
+  const core_modules_added = current.stats.core_modules.filter((m) => !baseCore.has(m));
+  const core_modules_removed = baseline.stats.core_modules.filter((m) => !currCore.has(m));
+
+  const graph: GraphDiff = { depth_changes, core_modules_added, core_modules_removed };
+
+  // ── 6.5 Enrichment Staleness Detection ───────────────────────────────────
+  for (const [fileKey, currFile] of Object.entries(current.files)) {
+    const baseFile = baseline.files[fileKey];
+
+    const hash_changed =
+      currFile.semantic !== null && currFile.semantic.source_hash !== currFile.hash;
+
+    const was_semantic_now_structural =
+      baseFile !== undefined &&
+      baseFile.enrichment_status === 'semantic' &&
+      currFile.enrichment_status === 'structural';
+
+    if (hash_changed || was_semantic_now_structural) {
+      stale_enrichments.push({ file: fileKey, hash_changed, was_semantic_now_structural });
+    }
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  const summary: DriftReport['summary'] = {
+    files_added: files.filter((f) => f.status === 'added').length,
+    files_removed: files.filter((f) => f.status === 'removed').length,
+    files_modified: files.filter((f) => f.status === 'modified').length,
+    symbols_added: symbols.filter((s) => s.status === 'added').length,
+    symbols_removed: symbols.filter((s) => s.status === 'removed').length,
+    symbols_changed: symbols.filter((s) => s.status === 'signature_changed').length,
+    imports_added: imports.filter((i) => i.status === 'added').length,
+    imports_removed: imports.filter((i) => i.status === 'removed').length,
+    depth_changes: depth_changes.length,
+    stale_enrichments: stale_enrichments.length,
+  };
+
+  return { files, symbols, imports, graph, stale_enrichments, summary };
+}

package/src/core/graph/drift/reporter.ts

@@ -0,0 +1,77 @@
+import type { ClassifiedDrift, DriftSeverity } from '../../../types/index.js';
+
+const SEVERITY_ORDER: DriftSeverity[] = ['breaking', 'warning', 'info', 'stale'];
+
+const SEVERITY_LABELS: Record<DriftSeverity, string> = {
+  breaking: 'BREAKING',
+  warning: 'WARNING',
+  info: 'INFO',
+  stale: 'STALE ENRICHMENT',
+};
+
+/**
+ * render — converts a ClassifiedDrift into a formatted string for stdout.
+ * Returns terminal-formatted text or JSON depending on options.json.
+ */
+export function render(
+  drift: ClassifiedDrift,
+  baselineDate: string,
+  currentDate: string,
+  options: { json: boolean; breakingOnly: boolean },
+): string {
+  const { json, breakingOnly } = options;
+
+  const filteredChanges = breakingOnly
+    ? drift.changes.filter((c) => c.severity === 'breaking')
+    : drift.changes;
+
+  // ── JSON format ───────────────────────────────────────────────────────────
+  if (json) {
+    return JSON.stringify(
+      {
+        baseline_generated_at: baselineDate,
+        current_generated_at: currentDate,
+        has_breaking: drift.has_breaking,
+        changes: filteredChanges,
+        summary: drift.summary,
+      },
+      null,
+      2,
+    );
+  }
+
+  // ── Terminal format ───────────────────────────────────────────────────────
+  const lines: string[] = [];
+  lines.push(`Drift Report: baseline (${baselineDate}) → current (${currentDate})`);
+  lines.push('');
+
+  if (filteredChanges.length === 0) {
+    lines.push('No drift detected.');
+    return lines.join('\n');
+  }
+
+  for (const severity of SEVERITY_ORDER) {
+    const group = filteredChanges.filter((c) => c.severity === severity);
+    if (group.length === 0) continue;
+
+    lines.push(`${SEVERITY_LABELS[severity]} (${group.length})`);
+    for (const change of group) {
+      lines.push(`  ${change.message}`);
+      if (change.detail) {
+        lines.push(`  ${change.detail}`);
+      }
+      lines.push(`  → ${change.suggestion}`);
+    }
+    lines.push('');
+  }
+
+  const s = drift.summary;
+  lines.push(
+    `Summary: ${s.files_added} added, ${s.files_removed} removed, ${s.files_modified} modified` +
+      ` | ${s.symbols_added + s.symbols_removed + s.symbols_changed} symbol changes` +
+      ` | ${s.imports_added + s.imports_removed} import changes` +
+      ` | ${s.stale_enrichments} stale enrichments`,
+  );
+
+  return lines.join('\n');
+}

package/src/core/graph/enricher.ts

@@ -0,0 +1,251 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
+import type { RequestOptions } from '@google/generative-ai';
+import pLimit from 'p-limit';
+import { z } from 'zod';
+import { NomosError } from '../errors.js';
+import type { NomosConfig, FileNode, SemanticInfo } from '../../types/index.js';
+import { AuthManager } from '../auth/manager.js';
+
+// ─── Zod schema for Gemini response validation ────────────────────────────────
+
+const SemanticResponseSchema = z.object({
+  overview: z.string(),
+  purpose: z.string(),
+  key_logic: z.array(z.string()),
+  usage_context: z.array(z.string()),
+});
+
+// ─── Gemini responseSchema (passed to generationConfig) ──────────────────────
+
+const GEMINI_RESPONSE_SCHEMA = {
+  type: SchemaType.OBJECT,
+  properties: {
+    overview: { type: SchemaType.STRING },
+    purpose: { type: SchemaType.STRING },
+    key_logic: { type: SchemaType.ARRAY, items: { type: SchemaType.STRING } },
+    usage_context: { type: SchemaType.ARRAY, items: { type: SchemaType.STRING } },
+  },
+  required: ['overview', 'purpose', 'key_logic', 'usage_context'],
+};
+
+// ─── SemanticEnricher ─────────────────────────────────────────────────────────
+
+export class SemanticEnricher {
+  private readonly client: GoogleGenerativeAI;
+  private readonly limit: ReturnType<typeof pLimit>;
+  private readonly requestOptions: RequestOptions | undefined;
+
+  constructor(
+    private readonly projectRoot: string,
+    private readonly config: NomosConfig['graph'],
+    private readonly logger: {
+      info(msg: string): void;
+      warn(msg: string): void;
+      error(msg: string): void;
+    },
+    apiKey?: string,
+    quotaProjectId?: string,
+  ) {
+    const key = apiKey ?? process.env['GEMINI_API_KEY'];
+    if (!key && config.ai_enrichment) {
+      throw new NomosError(
+        'graph_ai_key_missing',
+        'No credentials found. Set GEMINI_API_KEY or run: arc auth login',
+      );
+    }
+    this.client = new GoogleGenerativeAI(key ?? '');
+    this.limit = pLimit(config.ai_concurrency);
+    if (quotaProjectId) {
+      this.requestOptions = {
+        customHeaders: { 'x-goog-user-project': quotaProjectId },
+      };
+    }
+  }
+
+  static async create(
+    projectRoot: string,
+    config: NomosConfig['graph'],
+    logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void },
+    authManager?: AuthManager | null,
+  ): Promise<SemanticEnricher> {
+    // Priority 1: GEMINI_API_KEY (no quota header — billing is tied to the API key's project)
+    const envKey = process.env['GEMINI_API_KEY'];
+    if (envKey) {
+      return new SemanticEnricher(projectRoot, config, logger, envKey);
+    }
+    // Priority 2: OAuth credentials + quota project
+    if (authManager?.isLoggedIn()) {
+      const token = await authManager.getAccessToken();
+      const creds = authManager.loadCredentials();
+      return new SemanticEnricher(projectRoot, config, logger, token, creds?.quota_project_id);
+    }
+    // No key and enrichment enabled — let constructor throw
+    return new SemanticEnricher(projectRoot, config, logger);
+  }
+
+  /**
+   * Enriches all file nodes with AI-generated semantic metadata.
+   * Mutates `FileNode.semantic` in-place.
+   * Returns count of failures (files that could not be enriched).
+   *
+   * [GAP-3 FIX] Checks `cancellationFlag.cancelled` between each batch.
+   * [AMB-2 FIX] Reads file content from disk, not from ScanResult.
+   */
+  async enrich(
+    fileNodes: Map<string, FileNode>,
+    cancellationFlag: { cancelled: boolean },
+  ): Promise<number> {
+    const gapMs = Math.ceil(60000 / this.config.ai_requests_per_minute);
+    let failures = 0;
+    const entries = [...fileNodes.entries()];
+
+    for (let i = 0; i < entries.length; i++) {
+      // [GAP-3 FIX] Check cancellation flag between each file
+      if (cancellationFlag.cancelled) {
+        this.logger.info('[nomos:graph:info] Enrichment cancelled — stopping early.');
+        break;
+      }
+
+      const [, fileNode] = entries[i];
+
+      // Staleness check: skip if source_hash matches current hash
+      if (fileNode.semantic !== null && fileNode.semantic.source_hash === fileNode.hash) {
+        continue;
+      }
+
+      const success = await this.limit(() => this.enrichFile(fileNode, gapMs));
+      if (!success) failures++;
+    }
+
+    return failures;
+  }
+
+  private async enrichFile(fileNode: FileNode, gapMs: number): Promise<boolean> {
+    // [AMB-2 FIX] Read file content from disk
+    let content: string;
+    try {
+      content = await fs.readFile(path.join(this.projectRoot, fileNode.file), 'utf-8');
+    } catch (err) {
+      this.logger.error(
+        `[nomos:graph:error] Failed to read ${fileNode.file}: ${String(err)}`,
+      );
+      fileNode.semantic = null;
+      return false;
+    }
+
+    // Truncate at last complete line before max_file_chars
+    if (content.length > this.config.max_file_chars) {
+      const truncated = content.slice(0, this.config.max_file_chars);
+      const lastNewline = truncated.lastIndexOf('\n');
+      content = lastNewline > 0 ? truncated.slice(0, lastNewline) : truncated;
+    }
+
+    // Build prompt
+    const exports = fileNode.symbols
+      .filter((s) => s.exported)
+      .map((s) => (s.signature ? `${s.name}: ${s.signature}` : s.name))
+      .join(', ');
+
+    const prompt = [
+      `File: ${fileNode.file}`,
+      `Language: ${fileNode.language}`,
+      `Exports: ${exports || '(none)'}`,
+      `Used by: ${fileNode.dependents.join(', ') || '(none)'}`,
+      '---',
+      content,
+      '---',
+      'Respond in JSON matching this schema exactly:',
+      '{ "overview": string, "purpose": string, "key_logic": string[], "usage_context": string[] }',
+    ].join('\n');
+
+    // Retry with exponential backoff: 3 retries, delays of 2s, 4s, 8s
+    const retryDelays = [2000, 4000, 8000];
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= 3; attempt++) {
+      if (attempt > 0) {
+        await sleep(retryDelays[attempt - 1]);
+      }
+
+      try {
+        const model = this.client.getGenerativeModel({
+          model: this.config.ai_model,
+          generationConfig: {
+            responseMimeType: 'application/json',
+            responseSchema: GEMINI_RESPONSE_SCHEMA,
+          } as never,
+        }, this.requestOptions);
+
+        const result = await model.generateContent(prompt);
+        const text = result.response.text();
+
+        // Enforce minimum gap between requests
+        await sleep(gapMs);
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          this.logger.warn(
+            `[nomos:graph:warn] Non-JSON response for ${fileNode.file}: ${text.slice(0, 200)}`,
+          );
+          fileNode.semantic = null;
+          return false;
+        }
+
+        const validated = SemanticResponseSchema.safeParse(parsed);
+        if (!validated.success) {
+          this.logger.warn(
+            `[nomos:graph:warn] Zod validation failed for ${fileNode.file}: ${text.slice(0, 200)}`,
+          );
+          fileNode.semantic = null;
+          return false;
+        }
+
+        const { overview, purpose, key_logic, usage_context } = validated.data;
+        fileNode.semantic = {
+          overview,
+          purpose,
+          key_logic,
+          usage_context,
+          source_hash: fileNode.hash,
+          enriched_at: new Date().toISOString(),
+          model: this.config.ai_model,
+        } satisfies SemanticInfo;
+        fileNode.enrichment_status = 'semantic';
+
+        return true;
+      } catch (err: unknown) {
+        lastError = err;
+        if (!isRetryableError(err) || attempt >= 3) break;
+      }
+    }
+
+    this.logger.error(
+      `[nomos:graph:error] AI enrichment failed for ${fileNode.file} after 3 retries — skipping. ${String(lastError)}`,
+    );
+    fileNode.semantic = null;
+    return false;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryableError(err: unknown): boolean {
+  if (err instanceof Error) {
+    const msg = err.message;
+    return (
+      msg.includes('429') ||
+      msg.includes('503') ||
+      msg.includes('Too Many Requests') ||
+      msg.includes('Service Unavailable')
+    );
+  }
+  return false;
+}