adaptive-bitmask 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harry Jiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,454 @@
+# adaptive-bitmask
+
+**The Sub-10ms Shared Cognition Engine for Multi-Agent Systems.**
+
+Achieve an **85x bandwidth reduction** (753 bytes -> exactly 24 bytes) for multi-agent coordination. Instead of shipping bloated JSON payloads between agents, `adaptive-bitmask` uses dynamically-pruned semantic bitmasks to achieve sub-10ms coordination latency.
+
+**🎉 Production-Ready v1.0.0-rc.1** - [93.3% production test pass rate](./PRODUCTION_ROADMAP.md) with sub-millisecond coordination for 1000+ agents.
+
+**To view the paper: "Go to files" -> "Adaptive Protocol(5)"**
+
+```bash
+npm install adaptive-bitmask
+```
+
+## ✨ Production Features
+
+- **🚀 Sub-10ms Coordination** - 0.08ms average latency, 1.26ms for 2000 agents
+- **📦 Zero Dependencies** - Core engine has no runtime dependencies
+- **🛡️ Production Hardening** - Error handling, circuit breakers, graceful degradation
+- **📊 Built-in Monitoring** - Health checks, metrics collection, structured logging
+- **🔌 Transport Layers** - WebSocket and HTTP with production features
+- **🔒 Enterprise Security** - Input validation, rate limiting, authentication hooks
+
+## Quick Start (The "Instant Magic" Way)
+
+With the high-level `SharedCognition` wrapper, you can coordinate a massive swarm in just 3 lines of code.
+
+```typescript
+import { SharedCognition } from 'adaptive-bitmask';
+
+// 1. Initialize the engine (auto-manages schema, coordinator, and arbiter)
+const cognition = new SharedCognition();
+
+// 2. Feed it your agents' current observations
+const { decision, activeFeatures, latencyMs } = cognition.processSwarmTick([
+  ['price_up', 'volume_spike', 'momentum_strong'], // Agent 1
+  ['price_up', 'breakout_detected'],               // Agent 2
+  ['volume_spike', 'EMERGENCY_halt']               // Agent 3
+]);
+
+// 3. That's it. 
+console.log(`Swarm decided to ${decision} in ${latencyMs.toFixed(2)}ms`);
+console.log(`Consensus features:`, activeFeatures);
+```
+
+## 🌐 Real-World Deployments
+
+### High-Frequency Trading
+```typescript
+// 1000 trading bots coordinating in 0.66ms
+const tradingCognition = new SharedCognition({
+  arbiter: { executeThreshold: 0.60, emergencyOverride: true }
+});
+```
+
+### IoT Sensor Networks
+```typescript
+// 200 sensors reaching consensus in 0.20ms
+const iotCognition = new SharedCognition({
+  schema: { emergencyPrefix: 'EMERGENCY_' }
+});
+```
+
+### Chat Moderation Systems
+```typescript
+// 150 moderation agents deciding in 0.07ms
+const moderationCognition = new SharedCognition({
+  arbiter: { executeThreshold: 0.70 }
+});
+```
+
+## 🔧 Production Deployment
+
+### Docker
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN npm ci --only=production
+EXPOSE 8080 8081
+CMD ["node", "dist/index.js"]
+```
+
+### Kubernetes
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: adaptive-bitmask
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: adaptive-bitmask
+  template:
+    spec:
+      containers:
+      - name: adaptive-bitmask
+        image: adaptive-bitmask:latest
+        ports:
+        - containerPort: 8080  # WebSocket
+        - containerPort: 8081  # HTTP API
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "250m"
+          limits:
+            memory: "1Gi"
+            cpu: "500m"
+```
+
+### Monitoring
+```bash
+# Health check
+curl http://localhost:8081/api/health
+
+# Metrics endpoint
+curl http://localhost:8081/api/metrics
+```
+
+## 📊 Performance Benchmarks
+
+| Agent Count | Avg Latency | Max Latency | Memory Usage |
+|-------------|-------------|-------------|--------------|
+| 100         | 0.09ms      | 0.75ms      | ~50MB        |
+| 500         | 0.27ms      | 2.05ms      | ~120MB       |
+| 1000        | 0.66ms      | 3.12ms      | ~200MB       |
+| 2000        | 1.26ms      | 5.84ms      | ~350MB       |
+
+*All benchmarks run on M2 MacBook Pro with Node.js v20*
+
+## 🛠️ Transport Layers
+
+### WebSocket Transport
+```typescript
+import { createWebSocketTransport } from 'adaptive-bitmask';
+
+const wsTransport = createWebSocketTransport({
+  port: 8080,
+  maxConnections: 1000,
+  enableCompression: true
+});
+
+// Real-time bidirectional coordination
+wsTransport.on('message', ({ agentId, message }) => {
+  console.log(`Agent ${agentId}:`, message);
+});
+```
+
+### HTTP Transport
+```typescript
+import { createHttpTransport } from 'adaptive-bitmask';
+
+const httpTransport = createHttpTransport({
+  port: 8081,
+  enableCors: true,
+  rateLimitPerMinute: 1000
+});
+
+// REST API for coordination
+fetch('http://localhost:8081/api/coordinate', {
+  method: 'POST',
+  body: bitmaskMessage.toBytes()
+});
+```
+
+## 📈 Monitoring & Observability
+
+### Health Checks
+```json
+{
+  "status": "HEALTHY",
+  "uptime": 3600000,
+  "version": "1.0.0-rc.1",
+  "metrics": {
+    "messagesProcessed": 1000000,
+    "memoryUsageMB": 256,
+    "avgLatencyUs": 85
+  }
+}
+```
+
+### Metrics Collection
+```typescript
+import { MetricsCollector, Logger } from 'adaptive-bitmask';
+
+const metrics = new MetricsCollector();
+const logger = Logger.getInstance();
+
+// Automatic performance tracking
+metrics.recordCoordinationLatency(85); // microseconds
+logger.info('Coordination', 'Decision made', { 
+  decision: 'EXECUTE', 
+  agentCount: 1000 
+});
+```
+
+## 🚨 Error Handling & Recovery
+
+```typescript
+import { 
+  ValidationError, 
+  CircuitBreaker, 
+  TimeoutManager,
+  RecoveryManager 
+} from 'adaptive-bitmask';
+
+// Circuit breaker for resilience
+const circuitBreaker = new CircuitBreaker(5); // 5 failures threshold
+
+// Timeout protection
+await TimeoutManager.withTimeout(
+  coordinationOperation(),
+  10000, // 10s timeout
+  'swarm-coordination'
+);
+
+// Retry with exponential backoff
+await RecoveryManager.withRetry(
+  failingOperation,
+  3, // max retries
+  1000 // base delay
+);
+```
+
+---
+
+## Advanced Usage / Internal Engine
+
+For hardcore engineers who want direct access to the raw mathematical primitives and binary serialization logic.
+
+Based on the [Adaptive Bitmask Protocol paper](https://arxiv.org/abs/TODO) (Jiang, 2026):
+
+```
+Layer 0: SchemaManager    ← Feature-to-bit mappings, frequency pruning
+Layer 1: Worker Agents    ← Encode observations as 64-bit bitmasks
+Layer 2: Coordinator      ← OR-aggregate, compute per-bit confidence
+Layer 3: Arbiter          ← Weighted scoring → EXECUTE / SYNTHESIZE / REJECT
+```
+
+**24-byte wire format:**
+| Offset | Type | Field |
+|--------|------|-------|
+| 0-7 | uint64 | Feature bitmask |
+| 8-11 | uint32 | Agent ID |
+| 12-19 | int64 | Timestamp (ms) |
+| 20-23 | uint32 | Schema version |
+
+## Key Features
+
+**Schema Management** — Dynamic feature-to-bit mapping with frequency-based pruning. Emergency features (bits 56-63) are never pruned regardless of activation frequency.
+
+```typescript
+const schema = new SchemaManager({ emergencyPrefix: 'EMERGENCY_' });
+schema.registerAll(myFeatures);
+schema.recordActivations(observedFeatures);
+schema.prune();  // retains top-56 by frequency + all emergency features
+
+// Paper-aligned collision math utilities
+const p = schema.theoreticalCollisionRate;
+// p = 1 - (1 - 1/64)^(m - 1), where m = activeFeatureCount
+
+const excluded = schema.expectedExcludedFeatures(80);
+// E[excluded] = m - 64 * (1 - (1 - 1/64)^m)
+```
+
+**Schema Distribution** — Deterministic schema export/import with fingerprinting for cross-node compatibility checks.
+
+```typescript
+const exported = schema.exportSchema();
+// Send exported JSON through your control plane
+
+const replica = new SchemaManager();
+replica.importSchema(exported);
+// replica.fingerprint === schema.fingerprint
+```
+
+**Binary Serialization** — Messages serialize to exactly 24 bytes. Round-trips through `serialize()` / `deserialize()` for any transport layer.
+
+```typescript
+const bytes = msg.toBytes();     // Uint8Array(24)
+const restored = BitmaskMessage.deserialize(bytes);
+```
+
+**Weighted Scoring** — Configurable importance weights per bit position. Domain-specific presets included.
+
+```typescript
+import { createFinancialArbiter, createRoboticArbiter } from 'adaptive-bitmask';
+
+const arbiter = createFinancialArbiter();  // emergency bits weighted 0.45
+const arbiter = createRoboticArbiter();    // obstacle detection weighted 0.30
+```
+
+**Paper-Canonical Strategy Arbitration (Section 6)** — Rank strategy candidates by `s_final = 0.6*s_raw + 0.4*c`, then apply lead/synthesis thresholds.
+
+```typescript
+const result = arbiter.scoreStrategies([
+  { id: 'trend', mask: trendMask, confidence: trendConf },
+  { id: 'mean_revert', mask: mrMask, confidence: mrConf },
+  { id: 'breakout', mask: boMask, confidence: boConf },
+], {
+  leadThreshold: 0.15,
+  rejectThreshold: 0.40,
+});
+```
+
+Legacy compatibility: `arbiter.score(mask, confidence?)` remains unchanged for existing integrations.
+
+**Bitwise Primitives** — Full suite of 64-bit operations using BigInt for precision.
+
+```typescript
+import { setBit, popcount, merge, delta, hammingDistance } from 'adaptive-bitmask';
+```
+
+**Strict Encoding Mode** — Fail fast on unknown features to catch schema drift at ingestion time.
+
+```typescript
+const { mask } = encode(features, schema.featureToBit, {
+  throwOnUnknownFeatures: true,
+});
+```
+
+**Stale Schema Policy** — Choose how coordinators handle version-mismatched messages.
+
+```typescript
+const coordinator = new Coordinator({
+  schemaVersion: schema.version,
+  staleMessagePolicy: 'drop', // 'accept' | 'warn' | 'drop'
+});
+```
+
+**Telemetry Hooks** — Attach runtime callbacks for coordination and decision metrics.
+
+```typescript
+const coordinator = new Coordinator({
+  onTelemetry: (event) => {
+    if (event.type === 'round_aggregated') {
+      console.log(event.result.aggregationTimeUs);
+    }
+  },
+});
+
+const arbiter = new Arbiter({
+  onTelemetry: (event) => {
+    if (event.type === 'decision') {
+      console.log(event.result.finalScore);
+    }
+  },
+});
+```
+
+## Performance
+
+Measured on the protocol simulation (1,000 trials):
+
+| Operation | Mean | p99 |
+|-----------|------|-----|
+| Encode features | 2.0μs | 3.9μs |
+| Serialize message | 0.5μs | 0.8μs |
+| Aggregate (10 agents) | 84μs | 122μs |
+| Score (weighted linear) | 15μs | 26μs |
+| **Full pipeline (no LLM)** | **110μs** | **159μs** |
+
+The protocol overhead is negligible. LLM inference (6.8ms) accounts for 97.7% of end-to-end latency.
+
+## Migration Notes (`0.1.x` -> `0.2.0-rc.0`)
+
+`BitmaskMessage` validation is now strict:
+- `deserialize()` now requires exactly `24` bytes (not "at least 24")
+- constructor throws for out-of-range `mask`, `agentId`, `schemaVersion`, or unsafe `timestampMs`
+
+Coordinator behavior adds explicit stale handling:
+- new config: `staleMessagePolicy: 'accept' | 'warn' | 'drop'`
+- aggregate output now includes `droppedStaleMessages`
+
+Schema coordination helpers are now available:
+- `schema.exportSchema()` / `schema.importSchema(...)`
+- deterministic `schema.fingerprint` for compatibility checks
+
+## Transport
+
+This library is **transport-agnostic**. The 24-byte message format works with any transport layer:
+
+```typescript
+// WebSocket
+ws.send(msg.toBytes());
+
+// gRPC (as bytes field)
+grpcStream.write({ payload: msg.toBytes() });
+
+// HTTP (base64 or raw body)
+fetch('/coordinate', { body: msg.serialize() });
+
+// Vercel AI SDK (coming soon)
+```
+
+Optional helper for control-plane metadata:
+
+```typescript
+import { createEnvelope, decodeEnvelope } from 'adaptive-bitmask';
+
+const envelope = createEnvelope(msg, schema.fingerprint, 'round-42');
+const restored = decodeEnvelope(envelope, schema.fingerprint);
+```
+
+See [examples/transport.ts](/Users/hjiang/Developer/adaptive-bitmask/examples/transport.ts) for end-to-end transport payload patterns.
+
+## Benchmarking
+
+```bash
+npm run benchmark
+```
+
+Writes benchmark results to `benchmarks/latest.json`.
+
+```bash
+npm run benchmark:run
+npm run benchmark:check
+```
+
+`benchmark:check` fails if an operation regresses beyond both thresholds:
+- relative: `BENCH_MAX_REGRESSION_PCT` (default `40`)
+- absolute: `BENCH_MAX_ABS_REGRESSION_US` (default `1.5`)
+- baseline file: `BENCH_BASELINE_PATH` (default `benchmarks/baseline.json`)
+
+## API Reference
+
+### Bitmask Primitives
+
+`empty()` · `setBit(mask, pos)` · `clearBit(mask, pos)` · `testBit(mask, pos)` · `popcount(mask)` · `activeBits(mask)` · `forEachSetBit(mask, fn)` · `merge(a, b)` · `intersect(a, b)` · `delta(prev, next)` · `hammingDistance(a, b)` · `hasEmergency(mask)` · `toBytes(mask)` · `fromBytes(buf)` · `encode(features, schema, options?)` · `decode(mask, reverseSchema)`
+
+### SchemaManager
+
+`new SchemaManager(config?)` · `.register(feature)` · `.registerAll(features)` · `.recordActivations(features)` · `.prune()` · `.snapshot()` · `.exportSchema()` · `.importSchema(exported)` · `.expectedExcludedFeatures(featureCount?)` · `.theoreticalCollisionRate` · `.fingerprint` · `.featureToBit` · `.bitToFeatures` · `.version`
+
+### BitmaskMessage
+
+`new BitmaskMessage(data)` · `BitmaskMessage.now(mask, agentId, version)` · `.serialize()` · `.toBytes()` · `BitmaskMessage.deserialize(buf)` · `.sizeBytes` · `.compressionVsJson`
+
+### Arbiter
+
+`new Arbiter(config?)` · `.score(mask, confidence?)` (legacy) · `.scoreStrategies(candidates, options?)` (paper-canonical) · `.scoreMessages(messages, version?)` · `.setWeight(pos, weight)` · `createFinancialArbiter()` · `createRoboticArbiter()` (`onTelemetry`)
+
+### Coordinator
+
+`new Coordinator(config?)` · `.startRound()` · `.receive(msg)` · `.receiveAll(msgs)` · `.aggregate()` · `.schemaVersion` (`staleMessagePolicy`: `'accept' | 'warn' | 'drop'`, `onTelemetry`)
+
+### Transport Envelope
+
+`createEnvelope(msg, schemaFingerprint, roundId?)` · `decodeEnvelope(envelope, expectedSchemaFingerprint?)`
+
+## License
+
+MIT

package/dist/ai/index.d.mts

@@ -0,0 +1,123 @@
+import { S as SchemaManager, C as Coordinator, A as Arbiter, b as CoordinatorConfig, c as ArbiterConfig, D as Decision, d as ArbiterResult } from '../coordinator-Df48t6yJ.mjs';
+import * as ai from 'ai';
+import { LanguageModelV1Middleware } from 'ai';
+import { z } from 'zod';
+
+/**
+ * CoordinationSession — Lifecycle manager for bitmask-based agent coordination.
+ *
+ * Wraps SchemaManager + Coordinator + Arbiter into a single object
+ * that AI SDK tools and middleware can reference.
+ */
+
+interface CoordinationSessionConfig {
+    /** Initial feature vocabulary to register. */
+    features: string[];
+    /** Prefix for emergency features. Default: 'EMERGENCY_' */
+    emergencyPrefix?: string;
+    /** Explicit emergency features (alternative to prefix). */
+    emergencyFeatures?: string[];
+    /** Coordinator configuration overrides. */
+    coordinatorConfig?: Partial<CoordinatorConfig>;
+    /** Arbiter configuration overrides. */
+    arbiterConfig?: Partial<ArbiterConfig>;
+}
+interface ReportResult {
+    accepted: boolean;
+    mapped: number;
+    unmapped: number;
+}
+interface DecisionResult {
+    decision: Decision;
+    aggregatedFeatures: string[];
+    confidence: Map<number, number>;
+    result: ArbiterResult;
+}
+declare class CoordinationSession {
+    readonly schema: SchemaManager;
+    readonly coordinator: Coordinator;
+    readonly arbiter: Arbiter;
+    private readonly _agentIds;
+    constructor(config: CoordinationSessionConfig);
+    /** Deterministic agent ID: FNV-1a hash of name → uint32. */
+    agentId(name: string): number;
+    /** Start a new coordination round. Clears the coordinator buffer. */
+    startRound(): void;
+    /** Encode features + create message + receive in one call. */
+    report(agentName: string, features: string[]): ReportResult;
+    /** Aggregate current buffer + score via arbiter. */
+    decide(): DecisionResult;
+}
+
+declare function createCoordinationTools(session: CoordinationSession): {
+    reportObservation: ai.Tool<z.ZodObject<{
+        agentName: z.ZodString;
+        features: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        agentName: string;
+        features: string[];
+    }, {
+        agentName: string;
+        features: string[];
+    }>, {
+        accepted: boolean;
+        mapped: number;
+        unmapped: number;
+    }> & {
+        execute: (args: {
+            agentName: string;
+            features: string[];
+        }, options: ai.ToolExecutionOptions) => PromiseLike<{
+            accepted: boolean;
+            mapped: number;
+            unmapped: number;
+        }>;
+    };
+    getConsensus: ai.Tool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {
+        features: string[];
+        confidence: Record<string, number>;
+        agentCount: number;
+    }> & {
+        execute: (args: {}, options: ai.ToolExecutionOptions) => PromiseLike<{
+            features: string[];
+            confidence: Record<string, number>;
+            agentCount: number;
+        }>;
+    };
+    requestDecision: ai.Tool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {
+        decision: Decision;
+        score: number;
+        features: string[];
+        hasEmergency: boolean;
+    }> & {
+        execute: (args: {}, options: ai.ToolExecutionOptions) => PromiseLike<{
+            decision: Decision;
+            score: number;
+            features: string[];
+            hasEmergency: boolean;
+        }>;
+    };
+};
+
+/**
+ * Coordination middleware for the Vercel AI SDK.
+ *
+ * Optionally injects consensus state into the system prompt and/or
+ * auto-encodes tool call names as bitmask observations.
+ */
+
+interface CoordinationMiddlewareOptions {
+    /** Inject current consensus into system prompt before each LLM call. Default: false. */
+    injectConsensus?: boolean;
+    /**
+     * Auto-encode tool call names as bitmask observations after generation. Default: false.
+     * When enabled, tool calls whose names match registered schema features are
+     * automatically reported to the coordinator. Requires agentName.
+     */
+    autoEncodeToolCalls?: boolean;
+    /** Required when autoEncodeToolCalls is true. Identifies this agent in the coordinator. */
+    agentName?: string;
+}
+declare function createCoordinationMiddleware(session: CoordinationSession, options?: CoordinationMiddlewareOptions): LanguageModelV1Middleware;
+
+export { type CoordinationMiddlewareOptions, CoordinationSession, type CoordinationSessionConfig, type DecisionResult, type ReportResult, createCoordinationMiddleware, createCoordinationTools };