@hivemind-os/collective-core 0.2.0

package/src/reputation/score-calculator.ts

@@ -0,0 +1,133 @@
+import type { AgentCard, ReputationEvent, ReputationScore } from '@hivemind-os/collective-types';
+
+interface CapabilityAccumulator {
+  successes: number;
+  failures: number;
+  totalLatency: number;
+  latencyCount: number;
+}
+
+export class ReputationScoreCalculator {
+  computeScore(agentCard: AgentCard, events: ReputationEvent[]): ReputationScore {
+    const relatedEvents = events.filter((event) => event.subject === agentCard.did);
+    const eventSuccesses = relatedEvents.filter((event) => event.outcome === 'success').length;
+    const eventFailures = relatedEvents.filter((event) => event.outcome === 'failure' || event.outcome === 'timeout' || event.outcome === 'cancelled').length;
+    const eventDisputes = relatedEvents.filter((event) => event.type === 'dispute_opened' || event.outcome === 'disputed').length;
+    const completed = Math.max(agentCard.totalTasksCompleted ?? 0, eventSuccesses);
+    const failed = Math.max(agentCard.totalTasksFailed ?? 0, eventFailures);
+    const disputed = Math.max(agentCard.totalTasksDisputed ?? 0, eventDisputes);
+    const totalTasks = completed + failed;
+    const successRate = totalTasks === 0 ? 0 : completed / totalTasks;
+    const latencyEvents = relatedEvents.filter((event): event is ReputationEvent & { latencyMs: number } => typeof event.latencyMs === 'number');
+    const averageLatencyMs = latencyEvents.length === 0
+      ? 0
+      : Math.round(latencyEvents.reduce((sum, event) => sum + event.latencyMs, 0) / latencyEvents.length);
+    const totalEarningsMist = maxBigInt(
+      agentCard.totalEarningsMist ?? 0n,
+      relatedEvents.reduce((sum, event) => sum + paymentAmountToMist(event), 0n),
+    );
+
+    const capabilityAccumulators: Record<string, CapabilityAccumulator> = {};
+    for (const event of relatedEvents) {
+      const current = capabilityAccumulators[event.capability] ?? { successes: 0, failures: 0, totalLatency: 0, latencyCount: 0 };
+      if (event.outcome === 'success') {
+        current.successes += 1;
+      }
+      if (event.outcome === 'failure' || event.outcome === 'timeout' || event.outcome === 'cancelled') {
+        current.failures += 1;
+      }
+      if (typeof event.latencyMs === 'number') {
+        current.totalLatency += event.latencyMs;
+        current.latencyCount += 1;
+      }
+      capabilityAccumulators[event.capability] = current;
+    }
+
+    const capabilityScores = Object.fromEntries(
+      Object.entries(capabilityAccumulators).map(([capability, value]) => {
+        const taskCount = value.successes + value.failures;
+        return [
+          capability,
+          {
+            successRate: taskCount === 0 ? 0 : value.successes / taskCount,
+            taskCount,
+            averageLatencyMs: value.latencyCount === 0 ? 0 : Math.round(value.totalLatency / value.latencyCount),
+          },
+        ];
+      }),
+    ) as ReputationScore['capabilityScores'];
+
+    return {
+      did: agentCard.did,
+      successRate,
+      totalTasks,
+      totalDisputes: disputed,
+      averageLatencyMs,
+      totalEarningsMist,
+      stakeAmount: agentCard.stakeMist ?? 0n,
+      registeredAt: agentCard.registeredAt,
+      lastActiveAt: Math.max(
+        agentCard.updatedAt,
+        ...relatedEvents.map((event) => Date.parse(event.timestamp)).filter(Number.isFinite),
+        0,
+      ),
+      capabilityScores,
+    };
+  }
+
+  rankByReputation(agents: AgentCard[], scores: Map<string, ReputationScore>): AgentCard[] {
+    return [...agents].sort((left, right) => compareScores(scores.get(right.did), scores.get(left.did)));
+  }
+}
+
+function compareScores(left?: ReputationScore, right?: ReputationScore): number {
+  if (!left && !right) {
+    return 0;
+  }
+  if (!left) {
+    return -1;
+  }
+  if (!right) {
+    return 1;
+  }
+  return (
+    compareNumber(left.successRate, right.successRate) ||
+    compareNumber(left.totalTasks, right.totalTasks) ||
+    compareNumber(right.totalDisputes, left.totalDisputes) ||
+    compareBigInt(left.stakeAmount, right.stakeAmount) ||
+    compareBigInt(left.totalEarningsMist, right.totalEarningsMist) ||
+    compareNumber(right.registeredAt, left.registeredAt)
+  );
+}
+
+function paymentAmountToMist(event: ReputationEvent): bigint {
+  if (!event.paymentAmount) {
+    return 0n;
+  }
+  if (event.paymentAmount.currency.toUpperCase() !== 'MIST') {
+    return 0n;
+  }
+  try {
+    return BigInt(event.paymentAmount.amount);
+  } catch {
+    return 0n;
+  }
+}
+
+function compareNumber(left: number, right: number): number {
+  if (left === right) {
+    return 0;
+  }
+  return left > right ? 1 : -1;
+}
+
+function compareBigInt(left: bigint, right: bigint): number {
+  if (left === right) {
+    return 0;
+  }
+  return left > right ? 1 : -1;
+}
+
+function maxBigInt(left: bigint, right: bigint): bigint {
+  return left > right ? left : right;
+}

package/src/reputation/serialization.ts

@@ -0,0 +1,37 @@
+import type { ReputationEvent } from '@hivemind-os/collective-types';
+
+const encoder = new TextEncoder();
+
+export type UnsignedReputationEvent = Omit<ReputationEvent, 'signature'>;
+
+export function serializeReputationEventPayload(event: UnsignedReputationEvent): Uint8Array {
+  return encoder.encode(JSON.stringify(toSerializableUnsignedEvent(event)));
+}
+
+export function serializeReputationEvent(event: ReputationEvent): Uint8Array {
+  return encoder.encode(JSON.stringify(toSerializableEvent(event)));
+}
+
+function toSerializableUnsignedEvent(event: UnsignedReputationEvent): Record<string, unknown> {
+  return {
+    eventId: event.eventId,
+    type: event.type,
+    subject: event.subject,
+    author: event.author,
+    taskId: event.taskId,
+    outcome: event.outcome,
+    rating: event.rating,
+    capability: event.capability,
+    paymentAmount: event.paymentAmount,
+    latencyMs: event.latencyMs,
+    timestamp: event.timestamp,
+    nonce: event.nonce,
+  };
+}
+
+function toSerializableEvent(event: ReputationEvent): Record<string, unknown> {
+  return {
+    ...toSerializableUnsignedEvent(event),
+    signature: event.signature,
+  };
+}

package/src/reputation/store.ts

@@ -0,0 +1,165 @@
+import Database from 'better-sqlite3';
+
+import type { ReputationEvent } from '@hivemind-os/collective-types';
+
+import { assertValidReputationEvent, parseReputationEvent } from './validation.js';
+
+interface ReputationEventRow {
+  payload_json: string;
+}
+
+export class ReputationStore {
+  private readonly db: Database.Database;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    this.db.defaultSafeIntegers(true);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS reputation_events (
+        event_id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        author TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        outcome TEXT NOT NULL,
+        rating INTEGER,
+        capability TEXT NOT NULL,
+        payment_amount TEXT,
+        payment_currency TEXT,
+        latency_ms INTEGER,
+        timestamp TEXT NOT NULL,
+        timestamp_ms INTEGER NOT NULL,
+        nonce TEXT NOT NULL,
+        signature TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        anchor_id TEXT,
+        anchored_at INTEGER,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS reputation_events_subject_idx ON reputation_events (subject, timestamp_ms DESC);
+      CREATE INDEX IF NOT EXISTS reputation_events_author_idx ON reputation_events (author, timestamp_ms DESC);
+      CREATE INDEX IF NOT EXISTS reputation_events_anchor_idx ON reputation_events (anchor_id);
+    `);
+  }
+
+  async addEvent(event: ReputationEvent): Promise<void> {
+    const validated = assertValidReputationEvent(event);
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO reputation_events (
+          event_id, type, subject, author, task_id, outcome, rating, capability,
+          payment_amount, payment_currency, latency_ms, timestamp, timestamp_ms,
+          nonce, signature, payload_json, anchor_id, anchored_at, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, COALESCE((SELECT anchor_id FROM reputation_events WHERE event_id = ?), NULL), COALESCE((SELECT anchored_at FROM reputation_events WHERE event_id = ?), NULL), ?)`
+      )
+      .run(
+        validated.eventId,
+        validated.type,
+        validated.subject,
+        validated.author,
+        validated.taskId,
+        validated.outcome,
+        validated.rating ?? null,
+        validated.capability,
+        validated.paymentAmount?.amount ?? null,
+        validated.paymentAmount?.currency ?? null,
+        validated.latencyMs ?? null,
+        validated.timestamp,
+        toTimestampMs(validated.timestamp),
+        validated.nonce,
+        validated.signature,
+        JSON.stringify(validated),
+        validated.eventId,
+        validated.eventId,
+        Date.now(),
+      );
+  }
+
+  async getEvents(options: { subject?: string; author?: string; since?: number; limit?: number }): Promise<ReputationEvent[]> {
+    const clauses: string[] = [];
+    const values: Array<string | number> = [];
+    if (options.subject) {
+      clauses.push('subject = ?');
+      values.push(options.subject);
+    }
+    if (options.author) {
+      clauses.push('author = ?');
+      values.push(options.author);
+    }
+    if (typeof options.since === 'number') {
+      clauses.push('timestamp_ms >= ?');
+      values.push(Math.max(0, Math.floor(options.since)));
+    }
+
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+    const rows = this.db
+      .prepare(`SELECT payload_json FROM reputation_events ${where} ORDER BY timestamp_ms DESC LIMIT ?`)
+      .all(...values, normalizeLimit(options.limit)) as ReputationEventRow[];
+    return rows
+      .map((row) => parseStoredEvent(row.payload_json))
+      .filter((event): event is ReputationEvent => Boolean(event));
+  }
+
+  async getUnanchoredEvents(limit = 100): Promise<ReputationEvent[]> {
+    const rows = this.db
+      .prepare('SELECT payload_json FROM reputation_events WHERE anchor_id IS NULL ORDER BY timestamp_ms ASC LIMIT ?')
+      .all(normalizeLimit(limit)) as ReputationEventRow[];
+    return rows
+      .map((row) => parseStoredEvent(row.payload_json))
+      .filter((event): event is ReputationEvent => Boolean(event));
+  }
+
+  async markAnchored(eventIds: string[], anchorId: string): Promise<void> {
+    if (eventIds.length === 0) {
+      return;
+    }
+
+    const placeholders = eventIds.map(() => '?').join(', ');
+    this.db
+      .prepare(`UPDATE reputation_events SET anchor_id = ?, anchored_at = ? WHERE event_id IN (${placeholders})`)
+      .run(anchorId, Date.now(), ...eventIds);
+  }
+
+  async getStats(subject: string): Promise<{ completed: number; failed: number; disputed: number }> {
+    const row = this.db
+      .prepare(
+        `SELECT
+          SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS completed,
+          SUM(CASE WHEN outcome IN ('failure', 'timeout', 'cancelled') THEN 1 ELSE 0 END) AS failed,
+          SUM(CASE WHEN type = 'dispute_opened' OR outcome = 'disputed' THEN 1 ELSE 0 END) AS disputed
+         FROM reputation_events
+         WHERE subject = ?`,
+      )
+      .get(subject) as { completed?: number | bigint | null; failed?: number | bigint | null; disputed?: number | bigint | null } | undefined;
+
+    return {
+      completed: Number(row?.completed ?? 0),
+      failed: Number(row?.failed ?? 0),
+      disputed: Number(row?.disputed ?? 0),
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+function normalizeLimit(limit?: number): number {
+  if (typeof limit !== 'number' || Number.isNaN(limit)) {
+    return 100;
+  }
+  return Math.max(1, Math.floor(limit));
+}
+
+function toTimestampMs(timestamp: string): number {
+  const value = Date.parse(timestamp);
+  return Number.isFinite(value) ? value : 0;
+}
+
+function parseStoredEvent(payloadJson: string): ReputationEvent | null {
+  try {
+    return parseReputationEvent(JSON.parse(payloadJson) as unknown);
+  } catch {
+    return null;
+  }
+}

package/src/reputation/validation.ts

@@ -0,0 +1,135 @@
+import type { ReputationEvent, ReputationEventType } from '@hivemind-os/collective-types';
+
+const EVENT_TYPES = new Set<ReputationEventType>([
+  'task_completion',
+  'task_failure',
+  'task_timeout',
+  'task_cancellation',
+  'dispute_opened',
+  'dispute_resolved',
+  'payment_confirmed',
+]);
+
+const OUTCOMES = new Set<ReputationEvent['outcome']>([
+  'success',
+  'failure',
+  'timeout',
+  'cancelled',
+  'disputed',
+]);
+
+export function assertValidReputationEvent(event: ReputationEvent): ReputationEvent {
+  return parseReputationEvent(event);
+}
+
+export function parseReputationEvent(value: unknown): ReputationEvent {
+  if (!isRecord(value)) {
+    throw new Error('Reputation event must be an object.');
+  }
+
+  const event = {
+    eventId: parseRequiredString(value.eventId, 'eventId'),
+    type: parseEventType(value.type),
+    subject: parseDid(value.subject, 'subject'),
+    author: parseDid(value.author, 'author'),
+    taskId: parseRequiredString(value.taskId, 'taskId'),
+    outcome: parseOutcome(value.outcome),
+    rating: parseOptionalRating(value.rating),
+    capability: parseRequiredString(value.capability, 'capability'),
+    paymentAmount: parseOptionalPaymentAmount(value.paymentAmount),
+    latencyMs: parseOptionalLatencyMs(value.latencyMs),
+    timestamp: parseTimestamp(value.timestamp),
+    nonce: parseRequiredString(value.nonce, 'nonce'),
+    signature: parseRequiredString(value.signature, 'signature'),
+  } satisfies ReputationEvent;
+
+  if (event.subject === event.author) {
+    throw new Error('Reputation event subject must differ from author.');
+  }
+
+  return event;
+}
+
+function parseEventType(value: unknown): ReputationEventType {
+  if (typeof value === 'string' && EVENT_TYPES.has(value as ReputationEventType)) {
+    return value as ReputationEventType;
+  }
+  throw new Error(`Unsupported reputation event type: ${String(value)}`);
+}
+
+function parseOutcome(value: unknown): ReputationEvent['outcome'] {
+  if (typeof value === 'string' && OUTCOMES.has(value as ReputationEvent['outcome'])) {
+    return value as ReputationEvent['outcome'];
+  }
+  throw new Error(`Unsupported reputation outcome: ${String(value)}`);
+}
+
+function parseDid(value: unknown, field: string): string {
+  const did = parseRequiredString(value, field);
+  if (!did.startsWith('did:mesh:') || did.length <= 'did:mesh:'.length) {
+    throw new Error(`${field} must be a valid did:mesh identifier.`);
+  }
+  return did;
+}
+
+function parseRequiredString(value: unknown, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${field} must be a string.`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+  return trimmed;
+}
+
+function parseOptionalRating(value: unknown): number | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > 5) {
+    throw new Error('rating must be an integer between 1 and 5.');
+  }
+  return value as number;
+}
+
+function parseOptionalLatencyMs(value: unknown): number | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error('latencyMs must be a non-negative safe integer.');
+  }
+  return value as number;
+}
+
+function parseOptionalPaymentAmount(value: unknown): ReputationEvent['paymentAmount'] {
+  if (value == null) {
+    return undefined;
+  }
+  if (!isRecord(value)) {
+    throw new Error('paymentAmount must be an object when provided.');
+  }
+
+  const amount = parseRequiredString(value.amount, 'paymentAmount.amount');
+  if (!/^\d+$/.test(amount)) {
+    throw new Error('paymentAmount.amount must be a non-negative integer string.');
+  }
+
+  return {
+    amount,
+    currency: parseRequiredString(value.currency, 'paymentAmount.currency'),
+  };
+}
+
+function parseTimestamp(value: unknown): string {
+  const timestamp = parseRequiredString(value, 'timestamp');
+  if (!Number.isFinite(Date.parse(timestamp))) {
+    throw new Error('timestamp must be a valid ISO-8601 string.');
+  }
+  return timestamp;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/routing/circuit-breaker.ts

@@ -0,0 +1,111 @@
+export enum CircuitBreakerState {
+  CLOSED = 'closed',
+  OPEN = 'open',
+  HALF_OPEN = 'half_open',
+}
+
+interface ProviderCircuitState {
+  state: CircuitBreakerState;
+  consecutiveFailures: number;
+  openedAt?: number;
+  halfOpenProbeInFlight?: boolean;
+}
+
+export interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  recoveryTimeoutMs?: number;
+  now?: () => number;
+}
+
+export class CircuitBreaker {
+  private readonly failureThreshold: number;
+  private readonly recoveryTimeoutMs: number;
+  private readonly now: () => number;
+  private readonly states = new Map<string, ProviderCircuitState>();
+
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.failureThreshold = Math.max(1, Math.floor(options.failureThreshold ?? 3));
+    this.recoveryTimeoutMs = Math.max(0, Math.floor(options.recoveryTimeoutMs ?? 60_000));
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  recordSuccess(providerId: string): void {
+    this.states.set(providerId, {
+      state: CircuitBreakerState.CLOSED,
+      consecutiveFailures: 0,
+      halfOpenProbeInFlight: false,
+    });
+  }
+
+  recordFailure(providerId: string): void {
+    const current = this.getStateRecord(providerId);
+    const nextFailures = current.state === CircuitBreakerState.HALF_OPEN ? this.failureThreshold : current.consecutiveFailures + 1;
+    if (nextFailures >= this.failureThreshold) {
+      this.states.set(providerId, {
+        state: CircuitBreakerState.OPEN,
+        consecutiveFailures: nextFailures,
+        openedAt: this.now(),
+        halfOpenProbeInFlight: false,
+      });
+      return;
+    }
+
+    this.states.set(providerId, {
+      state: CircuitBreakerState.CLOSED,
+      consecutiveFailures: nextFailures,
+      halfOpenProbeInFlight: false,
+    });
+  }
+
+  allowRequest(providerId: string): boolean {
+    const current = this.getStateRecord(providerId);
+    if (current.state === CircuitBreakerState.OPEN) {
+      return false;
+    }
+    if (current.state !== CircuitBreakerState.HALF_OPEN) {
+      return true;
+    }
+    if (current.halfOpenProbeInFlight) {
+      return false;
+    }
+
+    this.states.set(providerId, {
+      ...current,
+      halfOpenProbeInFlight: true,
+    });
+    return true;
+  }
+
+  isOpen(providerId: string): boolean {
+    return this.getState(providerId) === CircuitBreakerState.OPEN;
+  }
+
+  getState(providerId: string): CircuitBreakerState {
+    return this.getStateRecord(providerId).state;
+  }
+
+  private getStateRecord(providerId: string): ProviderCircuitState {
+    const existing = this.states.get(providerId) ?? {
+      state: CircuitBreakerState.CLOSED,
+      consecutiveFailures: 0,
+    };
+
+    if (
+      existing.state === CircuitBreakerState.OPEN
+      && existing.openedAt !== undefined
+      && this.now() - existing.openedAt >= this.recoveryTimeoutMs
+    ) {
+      const recovered: ProviderCircuitState = {
+        state: CircuitBreakerState.HALF_OPEN,
+        consecutiveFailures: existing.consecutiveFailures,
+        openedAt: existing.openedAt,
+        halfOpenProbeInFlight: false,
+      };
+      this.states.set(providerId, recovered);
+      return recovered;
+    }
+
+    this.states.set(providerId, existing);
+    return existing;
+  }
+}