adaptive-bitmask 1.0.0-rc.1

package/dist/index.d.mts

@@ -0,0 +1,431 @@
+import { WebSocket } from 'ws';
+import { S as SchemaManager, C as Coordinator, A as Arbiter, a as SchemaConfig, b as CoordinatorConfig, c as ArbiterConfig, d as ArbiterResult, B as BitmaskMessage } from './coordinator-Df48t6yJ.mjs';
+export { e as AggregationResult, f as ArbiterTelemetryEvent, g as BITMASK_WIDTH, h as BitConfidence, i as Bitmask, j as BitmaskMessageData, k as CoordinatorDropReason, l as CoordinatorTelemetryEvent, D as Decision, E as EMERGENCY_RANGE, m as EncodeOptions, n as ExportedSchema, H as HIGH_FREQ_RANGE, M as MED_FREQ_RANGE, o as MESSAGE_SIZE_BYTES, P as PruneResult, p as SchemaSnapshot, q as ScoreStrategiesOptions, r as StaleMessagePolicy, s as StrategyCandidate, t as StrategyDecisionResult, u as StrategyScore, v as activeBits, w as clearBit, x as createFinancialArbiter, y as createRoboticArbiter, z as decode, F as delta, G as emergencyBits, I as empty, J as encode, K as forEachSetBit, L as fromBytes, N as hammingDistance, O as hasEmergency, Q as intersect, R as merge, T as popcount, U as setBit, V as testBit, W as toBytes } from './coordinator-Df48t6yJ.mjs';
+
+/**
+ * WebSocket transport layer for adaptive-bitmask
+ *
+ * Real-time bidirectional communication for multi-agent coordination
+ */
+
+interface WebSocketTransportConfig {
+    /** WebSocket server port */
+    port: number;
+    /** Maximum concurrent connections */
+    maxConnections?: number;
+    /** Connection timeout in milliseconds */
+    connectionTimeoutMs?: number;
+    /** Message timeout in milliseconds */
+    messageTimeoutMs?: number;
+    /** Enable compression */
+    enableCompression?: boolean;
+    /** Circuit breaker failure threshold */
+    circuitBreakerThreshold?: number;
+    /** Health check interval */
+    healthCheckIntervalMs?: number;
+}
+interface ConnectedAgent {
+    id: number;
+    socket: WebSocket;
+    lastSeen: number;
+    messagesReceived: number;
+    messagesSent: number;
+    schemaVersion: number;
+}
+interface TransportMessage {
+    type: 'BITMASK_MESSAGE' | 'HEARTBEAT' | 'ERROR' | 'SCHEMA_UPDATE';
+    payload: Uint8Array | object;
+    timestamp: number;
+    agentId?: number;
+}
+declare class WebSocketTransport {
+    private server;
+    private agents;
+    private nextAgentId;
+    private logger;
+    private metrics;
+    private circuitBreaker;
+    private config;
+    private isShuttingDown;
+    constructor(config: WebSocketTransportConfig);
+    private setupEventHandlers;
+    private handleConnection;
+    private handleMessage;
+    private processMessage;
+    private parseMessage;
+    private sendMessage;
+    private handleDisconnection;
+    private startHeartbeat;
+    private startHealthChecks;
+    broadcast(message: TransportMessage): void;
+    sendToAgent(agentId: number, message: TransportMessage): void;
+    getConnectedAgents(): ConnectedAgent[];
+    getAgentCount(): number;
+    getMetrics(): MetricsCollector;
+    shutdown(): Promise<void>;
+    private listeners;
+    private emit;
+    on(event: 'message' | 'disconnection', listener: Function): void;
+    off(event: 'message' | 'disconnection', listener: Function): void;
+}
+declare function createWebSocketTransport(config: WebSocketTransportConfig): WebSocketTransport;
+
+/**
+ * HTTP/REST transport layer for adaptive-bitmask
+ *
+ * Simple REST API for multi-agent coordination over HTTP
+ */
+
+interface HttpTransportConfig {
+    /** HTTP server port */
+    port: number;
+    /** Request timeout in milliseconds */
+    requestTimeoutMs?: number;
+    /** Maximum request body size */
+    maxBodySize?: number;
+    /** Enable CORS */
+    enableCors?: boolean;
+    /** Circuit breaker failure threshold */
+    circuitBreakerThreshold?: number;
+    /** Rate limiting requests per minute */
+    rateLimitPerMinute?: number;
+}
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: Buffer;
+    timestamp: number;
+}
+interface HttpResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body?: string | Buffer;
+    timestamp: number;
+}
+declare class HttpTransport {
+    private server;
+    private logger;
+    private metrics;
+    private circuitBreaker;
+    private config;
+    private requestCounts;
+    private isShuttingDown;
+    constructor(config: HttpTransportConfig);
+    private handleRequest;
+    private processRequest;
+    private parseRequestBody;
+    private routeRequest;
+    private handleCoordinate;
+    private handleHealth;
+    private handleMetrics;
+    private handleGetSchema;
+    private handleUpdateSchema;
+    private sendResponse;
+    private isRateLimited;
+    private startRateLimitCleanup;
+    start(): void;
+    shutdown(): Promise<void>;
+    getMetrics(): MetricsCollector;
+    private listeners;
+    private emit;
+    on(event: 'message', listener: Function): void;
+    off(event: 'message', listener: Function): void;
+}
+declare function createHttpTransport(config: HttpTransportConfig): HttpTransport;
+
+/**
+ * Production-grade logging and telemetry for adaptive-bitmask
+ *
+ * Provides structured logging, metrics collection, and observability
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4
+}
+interface LogEntry {
+    timestamp: number;
+    level: LogLevel;
+    component: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+}
+interface Metrics {
+    coordinationLatencyUs: number[];
+    messageProcessingTimeUs: number[];
+    encodingTimeUs: number[];
+    decodingTimeUs: number[];
+    messagesProcessed: number;
+    agentsConnected: number;
+    featuresActive: number;
+    schemaVersion: number;
+    errorsByType: Record<string, number>;
+    timeouts: number;
+    circuitBreakerTrips: number;
+    memoryUsageMB: number;
+    bufferUtilization: number;
+    lastReset: number;
+    uptimeMs: number;
+}
+interface HealthStatus {
+    status: 'HEALTHY' | 'DEGRADED' | 'UNHEALTHY';
+    uptime: number;
+    version: string;
+    timestamp: number;
+    checks: {
+        memory: boolean;
+        latency: boolean;
+        errorRate: boolean;
+        circuitBreakers: boolean;
+    };
+    metrics: {
+        messagesProcessed: number;
+        agentsConnected: number;
+        coordinationLatencyUs: {
+            mean: number;
+            p50: number;
+            p95: number;
+            p99: number;
+            max: number;
+            min: number;
+        };
+        memoryUsageMB: number;
+        errorsByType: Record<string, number>;
+    };
+}
+declare class Logger {
+    private static instance;
+    private logLevel;
+    private logs;
+    private maxLogSize;
+    private onLog?;
+    private constructor();
+    static getInstance(): Logger;
+    setLogLevel(level: LogLevel): void;
+    setLogCallback(callback: (entry: LogEntry) => void): void;
+    private shouldLog;
+    private createLogEntry;
+    private addLog;
+    debug(component: string, message: string, metadata?: Record<string, unknown>): void;
+    info(component: string, message: string, metadata?: Record<string, unknown>): void;
+    warn(component: string, message: string, metadata?: Record<string, unknown>): void;
+    error(component: string, message: string, error?: Error, metadata?: Record<string, unknown>): void;
+    fatal(component: string, message: string, error?: Error, metadata?: Record<string, unknown>): void;
+    getRecentLogs(count?: number): LogEntry[];
+    getLogsByLevel(level: LogLevel): LogEntry[];
+    clearLogs(): void;
+}
+declare class MetricsCollector {
+    private metrics;
+    private startTime;
+    private logger;
+    constructor();
+    private initializeMetrics;
+    recordCoordinationLatency(latencyUs: number): void;
+    recordMessageProcessingTime(timeUs: number): void;
+    recordEncodingTime(timeUs: number): void;
+    recordDecodingTime(timeUs: number): void;
+    incrementMessagesProcessed(): void;
+    setAgentsConnected(count: number): void;
+    setFeaturesActive(count: number): void;
+    setSchemaVersion(version: number): void;
+    recordError(errorType: string): void;
+    recordTimeout(): void;
+    recordCircuitBreakerTrip(): void;
+    updateMemoryUsage(): void;
+    setBufferUtilization(utilization: number): void;
+    getMetrics(): Metrics;
+    getLatencyStats(): {
+        mean: number;
+        p50: number;
+        p95: number;
+        p99: number;
+        max: number;
+        min: number;
+    };
+    reset(): void;
+}
+declare class HealthChecker {
+    private metrics;
+    private logger;
+    private version;
+    constructor(metrics: MetricsCollector);
+    getHealthStatus(): HealthStatus;
+    private getErrorRate;
+    startHealthCheck(intervalMs?: number): void;
+}
+declare class Profiler {
+    private static sessions;
+    private logger;
+    static startSession(sessionId: string): void;
+    static recordEvent(sessionId: string, event: string, data?: unknown): void;
+    static endSession(sessionId: string): Array<{
+        event: string;
+        time: number;
+        data?: unknown;
+    }>;
+    private static getLogger;
+}
+declare function createProductionLogger(config?: {
+    level?: LogLevel;
+    maxLogSize?: number;
+    enableConsole?: boolean;
+}): Logger;
+declare function createMetricsCollector(autoUpdateMs?: number): MetricsCollector;
+
+/**
+ * Production-grade error handling for adaptive-bitmask
+ *
+ * Provides structured error classes, validation, and graceful degradation
+ */
+declare class AdaptiveBitmaskError extends Error {
+    readonly code: string;
+    readonly category: 'VALIDATION' | 'RUNTIME' | 'NETWORK' | 'SYSTEM';
+    readonly context?: Record<string, unknown>;
+    readonly timestamp: number;
+    constructor(message: string, code: string, category: 'VALIDATION' | 'RUNTIME' | 'NETWORK' | 'SYSTEM', context?: Record<string, unknown>);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        category: "VALIDATION" | "RUNTIME" | "NETWORK" | "SYSTEM";
+        context: Record<string, unknown> | undefined;
+        timestamp: number;
+        stack: string | undefined;
+    };
+}
+declare class ValidationError extends AdaptiveBitmaskError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class SchemaValidationError extends ValidationError {
+    constructor(message: string, schemaVersion?: number, feature?: string);
+}
+declare class MessageValidationError extends ValidationError {
+    constructor(message: string, agentId?: number, messageSize?: number);
+}
+declare class RuntimeError extends AdaptiveBitmaskError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class CoordinatorError extends RuntimeError {
+    constructor(message: string, agentCount?: number, deadlineMs?: number);
+}
+declare class ArbiterError extends RuntimeError {
+    constructor(message: string, score?: number, decision?: string);
+}
+declare class NetworkError extends AdaptiveBitmaskError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class TimeoutError extends NetworkError {
+    constructor(message: string, timeoutMs?: number, operation?: string);
+}
+declare class SystemError extends AdaptiveBitmaskError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare class MemoryError extends SystemError {
+    constructor(message: string, memoryUsage?: number, limit?: number);
+}
+declare class Validator {
+    static validateAgentId(agentId: number): void;
+    static validateFeatureName(feature: string): void;
+    static validateFeatureArray(features: string[]): void;
+    static validateSchemaVersion(version: number): void;
+    static validateDeadlineMs(deadlineMs: number): void;
+    static validateTimeout(timeoutMs: number, operation: string): void;
+}
+declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly recoveryTimeoutMs;
+    private readonly monitoringPeriodMs;
+    private failures;
+    private lastFailureTime;
+    private state;
+    constructor(failureThreshold?: number, recoveryTimeoutMs?: number, monitoringPeriodMs?: number);
+    execute<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+    private recordFailure;
+    private reset;
+    getStatus(): {
+        state: "CLOSED" | "OPEN" | "HALF_OPEN";
+        failures: number;
+        lastFailureTime: number;
+        isHealthy: boolean;
+    };
+}
+declare class TimeoutManager {
+    static withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T>;
+}
+declare class RecoveryManager {
+    static withRetry<T>(operation: () => Promise<T>, maxRetries?: number, baseDelayMs?: number, operationName?: string): Promise<T>;
+}
+
+interface SharedCognitionConfig {
+    schema?: SchemaConfig;
+    coordinator?: CoordinatorConfig;
+    arbiter?: ArbiterConfig;
+    /** Automatically register unknown features when they are observed. Default: true. */
+    autoRegister?: boolean;
+}
+interface SwarmTickResult {
+    /** The final decision: EXECUTE, SYNTHESIZE, or REJECT */
+    decision: ArbiterResult['decision'];
+    /** Final confidence-adjusted composite score [0, 1] */
+    finalScore: number;
+    /** End-to-end latency in milliseconds */
+    latencyMs: number;
+    /** Array of features that were active in the consensus mask */
+    activeFeatures: string[];
+    /** Full result from the Arbiter for advanced inspection */
+    arbiterResult: ArbiterResult;
+}
+/**
+ * SharedCognition
+ *
+ * The high-level wrapper that sits on top of the adaptive-bitmask core engine.
+ * Tailored for instant multi-agent coordination without boilerplate.
+ */
+declare class SharedCognition {
+    schema: SchemaManager;
+    coordinator: Coordinator;
+    arbiter: Arbiter;
+    autoRegister: boolean;
+    constructor(config?: SharedCognitionConfig);
+    /**
+     * Process a single coordination tick across the entire swarm.
+     *
+     * 1. Encodes all agent string observations into 64-bit masks
+     * 2. Routes through the Meta-Coordinator
+     * 3. Arbitrates a final decision
+     *
+     * @param agentObservations Array of string feature arrays, one per agent
+     * @returns The unified swarm decision and latency
+     */
+    processSwarmTick(agentObservations: string[][]): SwarmTickResult;
+}
+
+interface TransportEnvelope {
+    /** Schema fingerprint expected by sender. */
+    schemaFingerprint: string;
+    /** Optional round identifier from transport layer. */
+    roundId?: string;
+    /** 24-byte bitmask payload. */
+    payload: Uint8Array;
+}
+/**
+ * Wrap a bitmask message with schema metadata for transport-level validation.
+ * Payload stays exactly the protocol 24-byte message.
+ */
+declare function createEnvelope(message: BitmaskMessage, schemaFingerprint: string, roundId?: string): TransportEnvelope;
+/**
+ * Validate an envelope and decode the underlying 24-byte message.
+ */
+declare function decodeEnvelope(envelope: TransportEnvelope, expectedSchemaFingerprint?: string): BitmaskMessage;
+
+export { AdaptiveBitmaskError, Arbiter, ArbiterConfig, ArbiterError, ArbiterResult, BitmaskMessage, CircuitBreaker, type ConnectedAgent, Coordinator, CoordinatorConfig, CoordinatorError, HealthChecker, type HealthStatus, type HttpRequest, type HttpResponse, HttpTransport, type HttpTransportConfig, type LogEntry, LogLevel, Logger, MemoryError, MessageValidationError, type Metrics, MetricsCollector, NetworkError, Profiler, RecoveryManager, RuntimeError, SchemaConfig, SchemaManager, SchemaValidationError, SharedCognition, type SharedCognitionConfig, type SwarmTickResult, SystemError, TimeoutError, TimeoutManager, type TransportEnvelope, type TransportMessage, ValidationError, Validator, WebSocketTransport, type WebSocketTransportConfig, createEnvelope, createHttpTransport, createMetricsCollector, createProductionLogger, createWebSocketTransport, decodeEnvelope };