@hivemind-os/collective-core 0.2.0

package/src/routing/fan-out.ts

@@ -0,0 +1,266 @@
+import { AggregationMode, type MultiProviderRequest, type MultiProviderResult, type ProviderScore } from '@hivemind-os/collective-types';
+
+import type { CircuitBreaker } from './circuit-breaker.js';
+import type { PerformanceTracker } from './performance.js';
+
+export interface ProviderExecutionOutput {
+  value: unknown;
+  aggregateValue?: unknown;
+  cost?: bigint;
+}
+
+export interface FanOutExecutorOptions {
+  executeProvider: (
+    provider: ProviderScore,
+    request: MultiProviderRequest,
+    context: { signal: AbortSignal },
+  ) => Promise<ProviderExecutionOutput>;
+  circuitBreaker?: Pick<CircuitBreaker, 'allowRequest' | 'recordSuccess' | 'recordFailure'>;
+  performanceTracker?: Pick<PerformanceTracker, 'recordCompletion'>;
+  now?: () => number;
+}
+
+interface ExecutionOutcome {
+  provider: ProviderScore;
+  status: 'success' | 'failure' | 'timeout';
+  durationMs: number;
+  result?: ProviderExecutionOutput;
+  error?: string;
+}
+
+export class FanOutExecutor {
+  private readonly now: () => number;
+
+  constructor(private readonly options: FanOutExecutorOptions) {
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  async execute(request: MultiProviderRequest, providers: ProviderScore[]): Promise<MultiProviderResult> {
+    const selectedProviders = providers.slice(0, Math.max(1, Math.floor(request.fanOutCount)));
+    if (selectedProviders.length === 0) {
+      return {
+        results: [],
+        totalCost: 0n,
+      };
+    }
+
+    const controllers = new Map<string, AbortController>();
+    const runPromises = selectedProviders.map((provider) => {
+      const controller = new AbortController();
+      controllers.set(provider.did, controller);
+      return this.runProvider(provider, request, controller.signal);
+    });
+
+    let aggregatedResult: unknown;
+
+    switch (request.aggregation) {
+      case AggregationMode.FIRST_SUCCESS: {
+        const firstSuccess = await this.waitForFirstSuccess(runPromises);
+        if (firstSuccess) {
+          aggregatedResult = firstSuccess.result?.aggregateValue ?? firstSuccess.result?.value;
+          abortRemaining(controllers, firstSuccess.provider.did);
+        }
+        break;
+      }
+      case AggregationMode.MAJORITY: {
+        const majority = await this.waitForMajority(runPromises, selectedProviders.length);
+        if (majority) {
+          aggregatedResult = majority.result?.aggregateValue ?? majority.result?.value;
+          abortRemaining(controllers, majority.provider.did);
+        }
+        break;
+      }
+      case AggregationMode.ALL:
+      case AggregationMode.BEST:
+      default:
+        break;
+    }
+
+    const outcomes = await Promise.all(runPromises);
+    const orderedOutcomes = selectedProviders.map(
+      (provider) => outcomes.find((entry) => entry.provider.did === provider.did) ?? {
+        provider,
+        status: 'timeout' as const,
+        durationMs: 0,
+        error: 'Provider execution did not complete.',
+      },
+    );
+
+    if (request.aggregation === AggregationMode.ALL) {
+      aggregatedResult = orderedOutcomes
+        .filter((entry) => entry.status === 'success')
+        .map((entry) => entry.result?.aggregateValue ?? entry.result?.value);
+    }
+
+    if (request.aggregation === AggregationMode.BEST) {
+      const fastest = orderedOutcomes
+        .filter((entry): entry is ExecutionOutcome & { result: ProviderExecutionOutput } => entry.status === 'success' && entry.result !== undefined)
+        .sort((left, right) => left.durationMs - right.durationMs)[0];
+      aggregatedResult = fastest?.result.aggregateValue ?? fastest?.result.value;
+    }
+
+    const totalCost = orderedOutcomes.reduce((sum, entry) => sum + (entry.status === 'success' ? entry.result?.cost ?? 0n : 0n), 0n);
+
+    return {
+      results: orderedOutcomes.map((entry) => ({
+        provider: entry.provider.did,
+        status: entry.status,
+        result: entry.result?.value,
+        durationMs: entry.durationMs,
+        error: entry.error,
+      })),
+      aggregatedResult,
+      totalCost,
+    };
+  }
+
+  private async runProvider(
+    provider: ProviderScore,
+    request: MultiProviderRequest,
+    signal: AbortSignal,
+  ): Promise<ExecutionOutcome> {
+    const startedAt = this.now();
+    if (this.options.circuitBreaker?.allowRequest && !this.options.circuitBreaker.allowRequest(provider.did)) {
+      return {
+        provider,
+        status: 'timeout',
+        durationMs: 0,
+        error: 'Provider circuit breaker is not ready to accept a probe request.',
+      };
+    }
+
+    try {
+      const result = await executeWithControls(
+        this.options.executeProvider(provider, request, { signal }),
+        signal,
+        request.timeout,
+      );
+      const durationMs = this.now() - startedAt;
+      this.options.circuitBreaker?.recordSuccess(provider.did);
+      this.options.performanceTracker?.recordCompletion(provider.did, request.capability, durationMs, true);
+      return {
+        provider,
+        status: 'success',
+        durationMs,
+        result,
+      };
+    } catch (error) {
+      const durationMs = this.now() - startedAt;
+      const status = classifyFailure(error);
+      const wasCancelled = signal.aborted && status === 'timeout';
+      if (!wasCancelled) {
+        this.options.circuitBreaker?.recordFailure(provider.did);
+        this.options.performanceTracker?.recordCompletion(provider.did, request.capability, durationMs, false);
+      }
+      return {
+        provider,
+        status,
+        durationMs,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  private async waitForFirstSuccess(outcomes: Array<Promise<ExecutionOutcome>>): Promise<ExecutionOutcome | undefined> {
+    const pending = [...outcomes];
+    while (pending.length > 0) {
+      const next = await Promise.race(pending.map(async (entry, index) => ({ index, value: await entry })));
+      if (next.value.status === 'success') {
+        return next.value;
+      }
+      pending.splice(next.index, 1);
+    }
+
+    return undefined;
+  }
+
+  private async waitForMajority(outcomes: Array<Promise<ExecutionOutcome>>, totalProviders: number): Promise<ExecutionOutcome | undefined> {
+    const pending = [...outcomes];
+    const buckets = new Map<string, { count: number; outcome: ExecutionOutcome }>();
+    const threshold = Math.floor(totalProviders / 2) + 1;
+
+    while (pending.length > 0) {
+      const next = await Promise.race(pending.map(async (entry, index) => ({ index, value: await entry })));
+      pending.splice(next.index, 1);
+      if (next.value.status !== 'success' || !next.value.result) {
+        continue;
+      }
+
+      const hash = stableStringify(next.value.result.aggregateValue ?? next.value.result.value);
+      const current = buckets.get(hash) ?? { count: 0, outcome: next.value };
+      current.count += 1;
+      buckets.set(hash, current);
+      if (current.count >= threshold) {
+        return current.outcome;
+      }
+    }
+
+    return undefined;
+  }
+}
+
+function abortRemaining(controllers: Map<string, AbortController>, winningDid: string): void {
+  for (const [providerDid, controller] of controllers.entries()) {
+    if (providerDid !== winningDid) {
+      controller.abort(new Error('Aborted after aggregate result was determined.'));
+    }
+  }
+}
+
+function classifyFailure(error: unknown): 'failure' | 'timeout' {
+  if (error instanceof Error && /timed out|aborted/i.test(error.message)) {
+    return 'timeout';
+  }
+  return 'failure';
+}
+
+async function executeWithControls<T>(promise: Promise<T>, signal: AbortSignal, timeoutMs?: number): Promise<T> {
+  if (signal.aborted) {
+    throw signal.reason ?? new Error('Provider execution aborted.');
+  }
+
+  return await new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(signal.reason ?? new Error('Provider execution aborted.'));
+    };
+    const timer = typeof timeoutMs === 'number' && timeoutMs > 0
+      ? setTimeout(() => {
+          cleanup();
+          reject(new Error(`Provider request timed out after ${timeoutMs}ms.`));
+        }, timeoutMs)
+      : undefined;
+    const cleanup = () => {
+      signal.removeEventListener('abort', onAbort);
+      if (timer) {
+        clearTimeout(timer);
+      }
+    };
+
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return typeof value === 'bigint' ? value.toString() : JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
+  return `{${entries.join(',')}}`;
+}

package/src/routing/index.ts

@@ -0,0 +1,4 @@
+export * from './circuit-breaker.js';
+export * from './fan-out.js';
+export * from './performance.js';
+export * from './selector.js';

package/src/routing/performance.ts

@@ -0,0 +1,244 @@
+import Database from 'better-sqlite3';
+
+export interface PerformanceTrackerOptions {
+  dbPath?: string;
+  now?: () => number;
+  maxSamplesPerCapability?: number;
+}
+
+interface DurationRow {
+  duration_ms: bigint | number;
+}
+
+interface AggregateRow {
+  success_count: bigint | number;
+  failure_count: bigint | number;
+  last_updated: bigint | number;
+}
+
+interface MetricRow {
+  provider_did: string;
+  capability: string;
+  avg_duration_ms: bigint | number;
+  p50: bigint | number;
+  p95: bigint | number;
+  success_count: bigint | number;
+  failure_count: bigint | number;
+  last_updated: bigint | number;
+}
+
+export interface ProviderCapabilityPerformance {
+  capability: string;
+  avgDurationMs: number;
+  p50: number;
+  p95: number;
+  successCount: number;
+  failureCount: number;
+  lastUpdated: number;
+}
+
+export interface ProviderPerformanceStats {
+  providerDid: string;
+  avgDurationMs: number;
+  p50: number;
+  p95: number;
+  successCount: number;
+  failureCount: number;
+  lastUpdated?: number;
+  capabilities: ProviderCapabilityPerformance[];
+}
+
+export class PerformanceTracker {
+  private readonly db: Database.Database;
+  private readonly now: () => number;
+  private readonly maxSamplesPerCapability: number;
+
+  constructor(options: PerformanceTrackerOptions = {}) {
+    this.db = new Database(options.dbPath ?? ':memory:');
+    this.db.defaultSafeIntegers(true);
+    this.now = options.now ?? (() => Date.now());
+    this.maxSamplesPerCapability = Math.max(10, Math.floor(options.maxSamplesPerCapability ?? 500));
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS provider_metric_samples (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        provider_did TEXT NOT NULL,
+        capability TEXT NOT NULL,
+        duration_ms INTEGER NOT NULL,
+        success INTEGER NOT NULL,
+        recorded_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_provider_metric_samples_lookup
+        ON provider_metric_samples(provider_did, capability, recorded_at);
+      CREATE TABLE IF NOT EXISTS provider_metrics (
+        provider_did TEXT NOT NULL,
+        capability TEXT NOT NULL,
+        avg_duration_ms INTEGER NOT NULL,
+        p50 INTEGER NOT NULL,
+        p95 INTEGER NOT NULL,
+        success_count INTEGER NOT NULL,
+        failure_count INTEGER NOT NULL,
+        last_updated INTEGER NOT NULL,
+        PRIMARY KEY (provider_did, capability)
+      );
+    `);
+  }
+
+  recordCompletion(provider: string, capability: string, durationMs: number, success: boolean): void {
+    if (!provider.trim()) {
+      throw new Error('provider must be a non-empty string.');
+    }
+    if (!capability.trim()) {
+      throw new Error('capability must be a non-empty string.');
+    }
+    if (!Number.isFinite(durationMs)) {
+      throw new Error('durationMs must be finite.');
+    }
+
+    const normalizedDuration = Math.max(0, Math.round(durationMs));
+    const recordedAt = this.now();
+    const transaction = this.db.transaction(() => {
+      this.db
+        .prepare(
+          `INSERT INTO provider_metric_samples (provider_did, capability, duration_ms, success, recorded_at)
+           VALUES (?, ?, ?, ?, ?)`,
+        )
+        .run(provider, capability, normalizedDuration, success ? 1 : 0, recordedAt);
+      this.db
+        .prepare(
+          `DELETE FROM provider_metric_samples
+           WHERE id IN (
+             SELECT id
+             FROM provider_metric_samples
+             WHERE provider_did = ? AND capability = ?
+             ORDER BY recorded_at DESC, id DESC
+             LIMIT -1 OFFSET ?
+           )`,
+        )
+        .run(provider, capability, this.maxSamplesPerCapability);
+
+      const durations = this.db
+        .prepare(
+          `SELECT duration_ms
+           FROM provider_metric_samples
+           WHERE provider_did = ? AND capability = ?
+           ORDER BY duration_ms ASC, recorded_at ASC`,
+        )
+        .all(provider, capability) as DurationRow[];
+      const aggregate = this.db
+        .prepare(
+          `SELECT
+             COALESCE(SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END), 0) AS success_count,
+             COALESCE(SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END), 0) AS failure_count,
+             COALESCE(MAX(recorded_at), 0) AS last_updated
+           FROM provider_metric_samples
+           WHERE provider_did = ? AND capability = ?`,
+        )
+        .get(provider, capability) as AggregateRow;
+
+      const numericDurations = durations.map((entry) => Number(entry.duration_ms));
+      const avgDurationMs = numericDurations.length === 0
+        ? 0
+        : Math.round(numericDurations.reduce((sum, entry) => sum + entry, 0) / numericDurations.length);
+      const p50 = percentile(numericDurations, 0.5);
+      const p95 = percentile(numericDurations, 0.95);
+
+      this.db
+        .prepare(
+          `INSERT INTO provider_metrics (
+             provider_did, capability, avg_duration_ms, p50, p95, success_count, failure_count, last_updated
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(provider_did, capability) DO UPDATE SET
+             avg_duration_ms = excluded.avg_duration_ms,
+             p50 = excluded.p50,
+             p95 = excluded.p95,
+             success_count = excluded.success_count,
+             failure_count = excluded.failure_count,
+             last_updated = excluded.last_updated`,
+        )
+        .run(
+          provider,
+          capability,
+          avgDurationMs,
+          p50,
+          p95,
+          Number(aggregate.success_count),
+          Number(aggregate.failure_count),
+          Number(aggregate.last_updated),
+        );
+    });
+
+    transaction();
+  }
+
+  getEstimatedLatency(provider: string, capability: string): number | undefined {
+    const row = this.db
+      .prepare(
+        `SELECT avg_duration_ms, p50, p95
+         FROM provider_metrics
+         WHERE provider_did = ? AND capability = ?`,
+      )
+      .get(provider, capability) as Pick<MetricRow, 'avg_duration_ms' | 'p50' | 'p95'> | undefined;
+    if (!row) {
+      return undefined;
+    }
+
+    return Number(row.p50 ?? row.avg_duration_ms ?? row.p95);
+  }
+
+  getProviderStats(provider: string): ProviderPerformanceStats {
+    const rows = this.db
+      .prepare(
+        `SELECT provider_did, capability, avg_duration_ms, p50, p95, success_count, failure_count, last_updated
+         FROM provider_metrics
+         WHERE provider_did = ?
+         ORDER BY capability ASC`,
+      )
+      .all(provider) as MetricRow[];
+
+    const capabilities = rows.map((row) => ({
+      capability: row.capability,
+      avgDurationMs: Number(row.avg_duration_ms),
+      p50: Number(row.p50),
+      p95: Number(row.p95),
+      successCount: Number(row.success_count),
+      failureCount: Number(row.failure_count),
+      lastUpdated: Number(row.last_updated),
+    }));
+
+    if (capabilities.length === 0) {
+      return {
+        providerDid: provider,
+        avgDurationMs: 0,
+        p50: 0,
+        p95: 0,
+        successCount: 0,
+        failureCount: 0,
+        capabilities: [],
+      };
+    }
+
+    return {
+      providerDid: provider,
+      avgDurationMs: Math.round(capabilities.reduce((sum, entry) => sum + entry.avgDurationMs, 0) / capabilities.length),
+      p50: Math.round(capabilities.reduce((sum, entry) => sum + entry.p50, 0) / capabilities.length),
+      p95: Math.round(capabilities.reduce((sum, entry) => sum + entry.p95, 0) / capabilities.length),
+      successCount: capabilities.reduce((sum, entry) => sum + entry.successCount, 0),
+      failureCount: capabilities.reduce((sum, entry) => sum + entry.failureCount, 0),
+      lastUpdated: Math.max(...capabilities.map((entry) => entry.lastUpdated)),
+      capabilities,
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+function percentile(values: number[], percentileRank: number): number {
+  if (values.length === 0) {
+    return 0;
+  }
+
+  const index = Math.min(values.length - 1, Math.max(0, Math.ceil(values.length * percentileRank) - 1));
+  return values[index] ?? 0;
+}