adaptive-bitmask 1.0.0-rc.1

package/dist/ai/index.js

@@ -0,0 +1,1141 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ai/index.ts
+var ai_exports = {};
+__export(ai_exports, {
+  CoordinationSession: () => CoordinationSession,
+  createCoordinationMiddleware: () => createCoordinationMiddleware,
+  createCoordinationTools: () => createCoordinationTools
+});
+module.exports = __toCommonJS(ai_exports);
+
+// src/transports/websocket.ts
+var import_ws = require("ws");
+
+// src/message.ts
+var MESSAGE_SIZE_BYTES = 24;
+var UINT32_MAX = 4294967295;
+var UINT64_MAX = (1n << 64n) - 1n;
+var BitmaskMessage = class _BitmaskMessage {
+  mask;
+  agentId;
+  timestampMs;
+  schemaVersion;
+  constructor(data) {
+    this._assertValid(data);
+    this.mask = data.mask;
+    this.agentId = data.agentId;
+    this.timestampMs = data.timestampMs;
+    this.schemaVersion = data.schemaVersion;
+  }
+  /** Create a message with current timestamp. */
+  static now(mask, agentId, schemaVersion) {
+    return new _BitmaskMessage({
+      mask,
+      agentId,
+      timestampMs: Date.now(),
+      schemaVersion
+    });
+  }
+  /** Wire size in bytes. */
+  get sizeBytes() {
+    return MESSAGE_SIZE_BYTES;
+  }
+  /**
+   * Serialize to 24-byte ArrayBuffer (little-endian).
+   *
+   * This is the canonical wire format. gRPC/WebSocket transports
+   * should send these bytes directly.
+   */
+  serialize() {
+    const buf = new ArrayBuffer(MESSAGE_SIZE_BYTES);
+    const view = new DataView(buf);
+    view.setBigUint64(0, this.mask, true);
+    view.setUint32(8, this.agentId, true);
+    view.setBigInt64(12, BigInt(this.timestampMs), true);
+    view.setUint32(20, this.schemaVersion, true);
+    return buf;
+  }
+  /** Serialize to Uint8Array. */
+  toBytes() {
+    return new Uint8Array(this.serialize());
+  }
+  /**
+   * Deserialize from ArrayBuffer or Uint8Array.
+   * Validates length before parsing.
+   */
+  static deserialize(data) {
+    const buf = data instanceof Uint8Array ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) : data;
+    if (buf.byteLength !== MESSAGE_SIZE_BYTES) {
+      throw new Error(
+        `Invalid message: expected exactly ${MESSAGE_SIZE_BYTES} bytes, got ${buf.byteLength}`
+      );
+    }
+    const view = new DataView(buf);
+    return new _BitmaskMessage({
+      mask: view.getBigUint64(0, true),
+      agentId: view.getUint32(8, true),
+      timestampMs: Number(view.getBigInt64(12, true)),
+      schemaVersion: view.getUint32(20, true)
+    });
+  }
+  /**
+   * JSON-equivalent size for comparison.
+   * Useful for demonstrating compression ratio.
+   */
+  get jsonSize() {
+    return JSON.stringify({
+      mask: this.mask.toString(),
+      agentId: this.agentId,
+      timestampMs: this.timestampMs,
+      schemaVersion: this.schemaVersion
+    }).length;
+  }
+  /** Compression ratio vs JSON encoding. */
+  get compressionVsJson() {
+    return this.jsonSize / MESSAGE_SIZE_BYTES;
+  }
+  /** Human-readable string for debugging. */
+  toString() {
+    return `BitmaskMessage(agent=${this.agentId}, v=${this.schemaVersion}, bits=${this.mask.toString(2).padStart(64, "0")}, t=${this.timestampMs})`;
+  }
+  _assertValid(data) {
+    if (typeof data.mask !== "bigint") {
+      throw new TypeError(`mask must be bigint, got ${typeof data.mask}`);
+    }
+    if (data.mask < 0n || data.mask > UINT64_MAX) {
+      throw new RangeError(`mask out of uint64 range: ${data.mask.toString()}`);
+    }
+    this._assertUint32("agentId", data.agentId);
+    this._assertUint32("schemaVersion", data.schemaVersion);
+    if (!Number.isSafeInteger(data.timestampMs)) {
+      throw new RangeError(
+        `timestampMs must be a safe integer, got ${data.timestampMs}`
+      );
+    }
+  }
+  _assertUint32(field, value) {
+    if (!Number.isInteger(value) || value < 0 || value > UINT32_MAX) {
+      throw new RangeError(
+        `${field} must be an integer in [0, ${UINT32_MAX}], got ${value}`
+      );
+    }
+  }
+};
+
+// src/bitmask.ts
+var BITMASK_WIDTH = 64;
+var EMERGENCY_RANGE = [56, 63];
+var HIGH_FREQ_RANGE = [0, 47];
+var MED_FREQ_RANGE = [48, 55];
+var SINGLE_BIT_TO_POSITION = new Map(
+  Array.from({ length: BITMASK_WIDTH }, (_, i) => [1n << BigInt(i), i])
+);
+function activeBits(mask) {
+  const bits = [];
+  forEachSetBit(mask, (bit) => bits.push(bit));
+  return bits;
+}
+function forEachSetBit(mask, fn) {
+  if (mask < 0n) {
+    throw new RangeError("Bitmask must be non-negative");
+  }
+  let m = mask;
+  while (m !== 0n) {
+    const leastSignificantBit = m & -m;
+    const position = SINGLE_BIT_TO_POSITION.get(leastSignificantBit);
+    if (position === void 0) {
+      throw new Error(`Invalid 64-bit mask: ${mask.toString()}`);
+    }
+    fn(position);
+    m ^= leastSignificantBit;
+  }
+}
+function hasEmergency(mask) {
+  const emergencyMask = 0xFFn << 56n;
+  return (mask & emergencyMask) !== 0n;
+}
+function encode(features, schema, options = {}) {
+  let mask = 0n;
+  let mapped = 0;
+  let unmapped = 0;
+  const unknownFeatures = [];
+  for (const feature of features) {
+    const bit = schema.get(feature);
+    if (bit !== void 0) {
+      mask |= 1n << BigInt(bit);
+      mapped++;
+    } else {
+      unmapped++;
+      unknownFeatures.push(feature);
+    }
+  }
+  if (options.throwOnUnknownFeatures && unknownFeatures.length > 0) {
+    const uniqueUnknown = [...new Set(unknownFeatures)];
+    throw new Error(
+      `Unknown features (${uniqueUnknown.length}): ${uniqueUnknown.join(", ")}`
+    );
+  }
+  return { mask, mapped, unmapped };
+}
+function decode(mask, reverseSchema) {
+  const features = [];
+  for (let i = 0; i < BITMASK_WIDTH; i++) {
+    if (mask & 1n << BigInt(i)) {
+      const feats = reverseSchema.get(i);
+      if (feats) {
+        features.push(...feats);
+      }
+    }
+  }
+  return features;
+}
+
+// src/schema.ts
+var MAX_EMERGENCY_FEATURES = EMERGENCY_RANGE[1] - EMERGENCY_RANGE[0] + 1;
+var MAX_REGULAR_FEATURES = HIGH_FREQ_RANGE[1] - HIGH_FREQ_RANGE[0] + 1 + (MED_FREQ_RANGE[1] - MED_FREQ_RANGE[0] + 1);
+var FNV_OFFSET_64 = 0xcbf29ce484222325n;
+var FNV_PRIME_64 = 0x100000001b3n;
+var MASK_64 = (1n << 64n) - 1n;
+var SchemaManager = class {
+  _version = 0;
+  _featureToBit = /* @__PURE__ */ new Map();
+  _bitToFeatures = /* @__PURE__ */ new Map();
+  _activationCounts = /* @__PURE__ */ new Map();
+  _totalActivations = 0;
+  _emergencyFeatures;
+  _emergencyPrefix;
+  _maxFeatures;
+  constructor(config = {}) {
+    this._maxFeatures = config.maxFeatures ?? BITMASK_WIDTH;
+    this._emergencyPrefix = config.emergencyPrefix ?? "EMERGENCY_";
+    this._emergencyFeatures = new Set(config.emergencyFeatures ?? []);
+  }
+  /** Current schema version. */
+  get version() {
+    return this._version;
+  }
+  /** Read-only view of feature → bit mapping. */
+  get featureToBit() {
+    return this._featureToBit;
+  }
+  /** Read-only view of bit → features mapping. */
+  get bitToFeatures() {
+    return this._bitToFeatures;
+  }
+  /** Number of actively mapped features. */
+  get activeFeatureCount() {
+    return this._featureToBit.size;
+  }
+  /** Deterministic fingerprint of current schema mapping and version. */
+  get fingerprint() {
+    return this._computeFingerprint(
+      this._version,
+      this._featureToBit,
+      this._emergencyPrefix,
+      this._emergencyFeatures
+    );
+  }
+  /** Check if a feature is an emergency feature. */
+  isEmergency(feature) {
+    return this._emergencyFeatures.has(feature) || feature.startsWith(this._emergencyPrefix);
+  }
+  /**
+   * Register a feature in the schema.
+   * Emergency features are pinned to bits 56-63.
+   * Regular features fill bits 0-55 in order.
+   *
+   * Returns the assigned bit position, or -1 if schema is full.
+   */
+  register(feature) {
+    const existing = this._featureToBit.get(feature);
+    if (existing !== void 0) return existing;
+    if (this._featureToBit.size >= this._maxFeatures) return -1;
+    if (this.isEmergency(feature)) {
+      return this._registerEmergency(feature);
+    }
+    return this._registerRegular(feature);
+  }
+  /**
+   * Register multiple features at once.
+   * Returns a map of feature → assigned bit position.
+   */
+  registerAll(features) {
+    const result = /* @__PURE__ */ new Map();
+    for (const feature of features) {
+      result.set(feature, this.register(feature));
+    }
+    return result;
+  }
+  /**
+   * Record feature activations for frequency tracking.
+   * Call this every coordination round with the observed features.
+   */
+  recordActivations(features) {
+    for (const feature of features) {
+      const count = this._activationCounts.get(feature) ?? 0;
+      this._activationCounts.set(feature, count + 1);
+      this._totalActivations++;
+    }
+  }
+  /**
+   * Frequency-based pruning (Section 3.3).
+   *
+   * Sorts features by activation frequency, retains:
+   * - All emergency features in bits 56-63 (never pruned)
+   * - Top 48 regular features in bits 0-47 (high-frequency)
+   * - Next 8 regular features in bits 48-55 (medium-frequency)
+   *
+   * Increments schema version.
+   */
+  prune() {
+    const knownFeatures = this._collectKnownFeatures();
+    const emergencyList = knownFeatures.filter((feature) => this.isEmergency(feature)).sort((a, b) => this._compareByFrequencyThenName(a, b));
+    const regularList = knownFeatures.filter((feature) => !this.isEmergency(feature)).sort((a, b) => this._compareByFrequencyThenName(a, b));
+    const newFeatureToBit = /* @__PURE__ */ new Map();
+    const newBitToFeatures = /* @__PURE__ */ new Map();
+    const [emergStart] = EMERGENCY_RANGE;
+    for (let i = 0; i < Math.min(emergencyList.length, MAX_EMERGENCY_FEATURES); i++) {
+      const bit = emergStart + i;
+      const feature = emergencyList[i];
+      newFeatureToBit.set(feature, bit);
+      newBitToFeatures.set(bit, [feature]);
+    }
+    const [highStart] = HIGH_FREQ_RANGE;
+    const highCount = HIGH_FREQ_RANGE[1] - HIGH_FREQ_RANGE[0] + 1;
+    for (let i = 0; i < Math.min(regularList.length, highCount); i++) {
+      const bit = highStart + i;
+      const feature = regularList[i];
+      newFeatureToBit.set(feature, bit);
+      newBitToFeatures.set(bit, [feature]);
+    }
+    const [medStart] = MED_FREQ_RANGE;
+    for (let i = highCount; i < Math.min(regularList.length, MAX_REGULAR_FEATURES); i++) {
+      const bit = medStart + (i - highCount);
+      const feature = regularList[i];
+      newFeatureToBit.set(feature, bit);
+      newBitToFeatures.set(bit, [feature]);
+    }
+    const excludedFeatures = [
+      ...regularList.slice(MAX_REGULAR_FEATURES),
+      ...emergencyList.slice(MAX_EMERGENCY_FEATURES)
+    ];
+    const mappingChanged = !this._mapsEqual(this._featureToBit, newFeatureToBit);
+    if (mappingChanged) {
+      this._featureToBit = newFeatureToBit;
+      this._bitToFeatures = newBitToFeatures;
+      this._version++;
+    }
+    return {
+      pruned: excludedFeatures.length,
+      retained: this._featureToBit.size,
+      version: this._version,
+      excludedFeatures
+    };
+  }
+  /** Get a serializable snapshot of the current schema state. */
+  snapshot() {
+    let emergencyCount = 0;
+    for (const [feat] of this._featureToBit) {
+      if (this.isEmergency(feat)) emergencyCount++;
+    }
+    return {
+      version: this._version,
+      featureToBit: new Map(this._featureToBit),
+      bitToFeatures: new Map(
+        [...this._bitToFeatures].map(([k, v]) => [k, [...v]])
+      ),
+      totalTracked: this._activationCounts.size,
+      activeFeatures: this._featureToBit.size,
+      emergencyCount
+    };
+  }
+  /**
+   * Export canonical schema state for distribution.
+   * Entries are sorted by bit (then feature) for deterministic serialization.
+   */
+  exportSchema() {
+    const entries = [...this._featureToBit.entries()].sort((a, b) => {
+      if (a[1] !== b[1]) return a[1] - b[1];
+      return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+    }).map(([feature, bit]) => [feature, bit]);
+    return {
+      version: this._version,
+      entries,
+      emergencyPrefix: this._emergencyPrefix,
+      emergencyFeatures: [...this._emergencyFeatures].sort(
+        (a, b) => a < b ? -1 : a > b ? 1 : 0
+      ),
+      fingerprint: this.fingerprint
+    };
+  }
+  /**
+   * Import an exported schema state.
+   * Replaces active mappings and resets activation counters.
+   */
+  importSchema(schema) {
+    this._assertExportedSchema(schema);
+    const newFeatureToBit = /* @__PURE__ */ new Map();
+    const newBitToFeatures = /* @__PURE__ */ new Map();
+    for (const [feature, bit] of schema.entries) {
+      newFeatureToBit.set(feature, bit);
+      newBitToFeatures.set(bit, [feature]);
+    }
+    const expectedFingerprint = this._computeFingerprint(
+      schema.version,
+      newFeatureToBit,
+      schema.emergencyPrefix,
+      new Set(schema.emergencyFeatures)
+    );
+    if (schema.fingerprint !== expectedFingerprint) {
+      throw new Error(
+        `Schema fingerprint mismatch: expected ${expectedFingerprint}, got ${schema.fingerprint}`
+      );
+    }
+    this._featureToBit = newFeatureToBit;
+    this._bitToFeatures = newBitToFeatures;
+    this._emergencyPrefix = schema.emergencyPrefix;
+    this._emergencyFeatures = new Set(schema.emergencyFeatures);
+    this._activationCounts.clear();
+    this._totalActivations = 0;
+    this._version = schema.version;
+  }
+  /** Get activation frequency for a feature. */
+  getFrequency(feature) {
+    return this._activationCounts.get(feature) ?? 0;
+  }
+  /** Get all features ranked by activation frequency. */
+  getRankedFeatures() {
+    const ranked = [];
+    for (const [feature, count] of this._activationCounts) {
+      ranked.push({
+        feature,
+        count,
+        bit: this._featureToBit.get(feature)
+      });
+    }
+    ranked.sort((a, b) => b.count - a.count);
+    return ranked;
+  }
+  /** Reset all activation counts (but keep schema mappings). */
+  resetCounts() {
+    this._activationCounts.clear();
+    this._totalActivations = 0;
+  }
+  /**
+   * Collision probability for a specific feature:
+   * P(collision) = 1 - (1 - 1/64)^(m - 1)
+   * where m is active feature count.
+   */
+  get theoreticalCollisionRate() {
+    const m = this._featureToBit.size;
+    if (m <= 1) return 0;
+    return 1 - Math.pow(1 - 1 / BITMASK_WIDTH, m - 1);
+  }
+  /**
+   * Expected excluded feature count under uniform assignment:
+   * E[excluded] = m - 64 * (1 - (1 - 1/64)^m)
+   */
+  expectedExcludedFeatures(featureCount = this._featureToBit.size) {
+    if (!Number.isInteger(featureCount) || featureCount < 0) {
+      throw new RangeError(
+        `featureCount must be a non-negative integer, got ${featureCount}`
+      );
+    }
+    if (featureCount === 0) return 0;
+    return featureCount - BITMASK_WIDTH * (1 - Math.pow(1 - 1 / BITMASK_WIDTH, featureCount));
+  }
+  // ── Private ──
+  _registerEmergency(feature) {
+    const [start, end] = EMERGENCY_RANGE;
+    for (let bit = start; bit <= end; bit++) {
+      if (!this._bitToFeatures.has(bit)) {
+        this._featureToBit.set(feature, bit);
+        this._bitToFeatures.set(bit, [feature]);
+        this._version++;
+        return bit;
+      }
+    }
+    return -1;
+  }
+  _registerRegular(feature) {
+    const [highStart, highEnd] = HIGH_FREQ_RANGE;
+    for (let bit = highStart; bit <= highEnd; bit++) {
+      if (!this._bitToFeatures.has(bit)) {
+        this._featureToBit.set(feature, bit);
+        this._bitToFeatures.set(bit, [feature]);
+        this._version++;
+        return bit;
+      }
+    }
+    const [medStart, medEnd] = MED_FREQ_RANGE;
+    for (let bit = medStart; bit <= medEnd; bit++) {
+      if (!this._bitToFeatures.has(bit)) {
+        this._featureToBit.set(feature, bit);
+        this._bitToFeatures.set(bit, [feature]);
+        this._version++;
+        return bit;
+      }
+    }
+    return -1;
+  }
+  _collectKnownFeatures() {
+    const all = /* @__PURE__ */ new Set();
+    for (const feature of this._activationCounts.keys()) all.add(feature);
+    for (const feature of this._featureToBit.keys()) all.add(feature);
+    for (const feature of this._emergencyFeatures) all.add(feature);
+    return [...all];
+  }
+  _compareByFrequencyThenName(a, b) {
+    const countA = this._activationCounts.get(a) ?? 0;
+    const countB = this._activationCounts.get(b) ?? 0;
+    if (countA !== countB) return countB - countA;
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  }
+  _mapsEqual(a, b) {
+    if (a.size !== b.size) return false;
+    for (const [feature, bit] of a) {
+      if (b.get(feature) !== bit) return false;
+    }
+    return true;
+  }
+  _assertExportedSchema(schema) {
+    if (!Number.isInteger(schema.version) || schema.version < 0) {
+      throw new RangeError(`Schema version must be a non-negative integer, got ${schema.version}`);
+    }
+    if (typeof schema.fingerprint !== "string" || schema.fingerprint.length === 0) {
+      throw new TypeError("Schema fingerprint must be a non-empty string");
+    }
+    const seenFeatures = /* @__PURE__ */ new Set();
+    const seenBits = /* @__PURE__ */ new Set();
+    for (const [feature, bit] of schema.entries) {
+      if (!feature || typeof feature !== "string") {
+        throw new TypeError(`Invalid feature name in schema export: ${String(feature)}`);
+      }
+      if (!Number.isInteger(bit) || bit < 0 || bit >= BITMASK_WIDTH) {
+        throw new RangeError(`Invalid bit position in schema export: ${bit}`);
+      }
+      if (seenFeatures.has(feature)) {
+        throw new Error(`Duplicate feature in schema export: ${feature}`);
+      }
+      if (seenBits.has(bit)) {
+        throw new Error(`Duplicate bit in schema export: ${bit}`);
+      }
+      seenFeatures.add(feature);
+      seenBits.add(bit);
+    }
+  }
+  _computeFingerprint(version, mapping, emergencyPrefix, emergencyFeatures) {
+    const canonicalEntries = [...mapping.entries()].sort((a, b) => {
+      if (a[1] !== b[1]) return a[1] - b[1];
+      if (a[0] < b[0]) return -1;
+      if (a[0] > b[0]) return 1;
+      return 0;
+    }).map(([feature, bit]) => `${bit}:${feature}`).join("|");
+    const canonicalEmergency = [...emergencyFeatures].sort((a, b) => a < b ? -1 : a > b ? 1 : 0).join("|");
+    const canonical = `v=${version};ep=${emergencyPrefix};ef=${canonicalEmergency};m=${canonicalEntries}`;
+    let hash = FNV_OFFSET_64;
+    for (const char of canonical) {
+      hash ^= BigInt(char.codePointAt(0) ?? 0);
+      hash = hash * FNV_PRIME_64 & MASK_64;
+    }
+    return hash.toString(16).padStart(16, "0");
+  }
+};
+
+// src/coordinator.ts
+var Coordinator = class {
+  _buffer = [];
+  _seenAgents = /* @__PURE__ */ new Set();
+  _schemaVersion;
+  _deadlineMs;
+  _staleMessagePolicy;
+  _onTelemetry;
+  _roundStartTime = 0;
+  _aggregationCount = 0;
+  _droppedStaleMessages = 0;
+  constructor(config = {}) {
+    this._deadlineMs = config.deadlineMs ?? 15;
+    this._schemaVersion = config.schemaVersion;
+    this._staleMessagePolicy = config.staleMessagePolicy ?? "accept";
+    this._onTelemetry = config.onTelemetry;
+  }
+  /** Number of messages in current buffer. */
+  get bufferedCount() {
+    return this._buffer.length;
+  }
+  /** Total aggregation rounds performed. */
+  get aggregationCount() {
+    return this._aggregationCount;
+  }
+  /** Update expected schema version. */
+  set schemaVersion(version) {
+    this._schemaVersion = version;
+  }
+  /** Start a new coordination round. Clears the buffer. */
+  startRound() {
+    this._buffer = [];
+    this._seenAgents.clear();
+    this._roundStartTime = performance.now();
+    this._droppedStaleMessages = 0;
+  }
+  /**
+   * Receive a message from an agent.
+   * Returns false if the message was dropped (deadline exceeded or duplicate agent).
+   */
+  receive(message) {
+    if (this._roundStartTime > 0) {
+      const elapsed = performance.now() - this._roundStartTime;
+      if (elapsed > this._deadlineMs) {
+        this._emitTelemetry({
+          type: "message_dropped",
+          agentId: message.agentId,
+          reason: "deadline"
+        });
+        return false;
+      }
+    }
+    const isStale = this._schemaVersion !== void 0 && message.schemaVersion !== this._schemaVersion;
+    if (isStale) {
+      if (this._staleMessagePolicy === "drop") {
+        this._droppedStaleMessages++;
+        this._emitTelemetry({
+          type: "message_dropped",
+          agentId: message.agentId,
+          reason: "stale"
+        });
+        return false;
+      }
+      if (this._staleMessagePolicy === "warn") {
+        console.warn(
+          `adaptive-bitmask: stale schema version from agent ${message.agentId} (expected ${this._schemaVersion}, got ${message.schemaVersion})`
+        );
+      }
+    }
+    if (this._seenAgents.has(message.agentId)) {
+      const idx = this._buffer.findIndex((m) => m.agentId === message.agentId);
+      if (idx !== -1) {
+        this._buffer[idx] = message;
+      }
+      this._emitTelemetry({
+        type: "message_accepted",
+        agentId: message.agentId,
+        stale: isStale,
+        replaced: true
+      });
+      return true;
+    }
+    this._seenAgents.add(message.agentId);
+    this._buffer.push(message);
+    this._emitTelemetry({
+      type: "message_accepted",
+      agentId: message.agentId,
+      stale: isStale,
+      replaced: false
+    });
+    return true;
+  }
+  /**
+   * Receive multiple messages at once.
+   * Returns number of messages accepted.
+   */
+  receiveAll(messages) {
+    let accepted = 0;
+    for (const msg of messages) {
+      if (this.receive(msg)) accepted++;
+    }
+    return accepted;
+  }
+  /**
+   * Aggregate all buffered messages into a consensus result.
+   * Clears the buffer after aggregation.
+   */
+  aggregate() {
+    const t0 = performance.now();
+    let aggregated = 0n;
+    const bitVotes = /* @__PURE__ */ new Map();
+    let staleCount = 0;
+    const uniqueAgents = /* @__PURE__ */ new Set();
+    for (const msg of this._buffer) {
+      uniqueAgents.add(msg.agentId);
+      if (this._schemaVersion !== void 0 && msg.schemaVersion !== this._schemaVersion) {
+        staleCount++;
+      }
+      aggregated |= msg.mask;
+      forEachSetBit(msg.mask, (bit) => {
+        bitVotes.set(bit, (bitVotes.get(bit) ?? 0) + 1);
+      });
+    }
+    const messageCount = this._buffer.length;
+    const confidence = /* @__PURE__ */ new Map();
+    for (const [bit, votes] of bitVotes) {
+      confidence.set(bit, messageCount > 0 ? votes / messageCount : 0);
+    }
+    const elapsed = (performance.now() - t0) * 1e3;
+    this._aggregationCount++;
+    this._buffer = [];
+    this._seenAgents.clear();
+    const result = {
+      aggregatedMask: aggregated,
+      confidence,
+      messageCount,
+      uniqueAgents: uniqueAgents.size,
+      staleMessages: staleCount,
+      droppedStaleMessages: this._droppedStaleMessages,
+      aggregationTimeUs: elapsed
+    };
+    this._emitTelemetry({ type: "round_aggregated", result });
+    return result;
+  }
+  _emitTelemetry(event) {
+    this._onTelemetry?.(event);
+  }
+};
+
+// src/arbiter.ts
+var Arbiter = class {
+  _weights;
+  _weightSum;
+  _executeThreshold;
+  _synthesizeThreshold;
+  _emergencyOverride;
+  _onTelemetry;
+  _decisionCount = 0;
+  constructor(config = {}) {
+    this._executeThreshold = config.executeThreshold ?? 0.55;
+    this._synthesizeThreshold = config.synthesizeThreshold ?? 0.4;
+    this._emergencyOverride = config.emergencyOverride ?? true;
+    this._onTelemetry = config.onTelemetry;
+    this._weights = new Float64Array(BITMASK_WIDTH);
+    if (config.weights) {
+      if (config.weights.length !== BITMASK_WIDTH) {
+        throw new Error(`Weight vector must have ${BITMASK_WIDTH} elements, got ${config.weights.length}`);
+      }
+      this._weights.set(config.weights);
+    } else {
+      this._weights.fill(1);
+    }
+    this._weightSum = this._weights.reduce((sum, w) => sum + w, 0);
+  }
+  /** Number of decisions made since creation. */
+  get decisionCount() {
+    return this._decisionCount;
+  }
+  /** Set the weight for a specific bit position. */
+  setWeight(position, weight) {
+    if (position < 0 || position >= BITMASK_WIDTH) {
+      throw new RangeError(`Position ${position} out of range`);
+    }
+    this._weightSum -= this._weights[position];
+    this._weights[position] = weight;
+    this._weightSum += weight;
+  }
+  /** Get the current weight vector (copy). */
+  get weights() {
+    return Array.from(this._weights);
+  }
+  /**
+   * Score an aggregated bitmask and produce a decision.
+   *
+   * @param aggregatedMask — OR-aggregated mask from all agents
+   * @param confidence — Optional per-bit confidence (fraction of agents that set each bit)
+   */
+  score(aggregatedMask, confidence) {
+    const t0 = performance.now();
+    const active = activeBits(aggregatedMask);
+    const emergency = hasEmergency(aggregatedMask);
+    if (emergency && this._emergencyOverride) {
+      const elapsed2 = (performance.now() - t0) * 1e3;
+      this._decisionCount++;
+      const result2 = {
+        decision: "REJECT",
+        rawScore: 0,
+        confidenceScore: 0,
+        finalScore: 0,
+        activeBitCount: active.length,
+        hasEmergency: true,
+        scoringTimeUs: elapsed2
+      };
+      this._emitTelemetry({ type: "decision", result: result2 });
+      return result2;
+    }
+    let numerator = 0;
+    for (const bit of active) {
+      numerator += this._weights[bit];
+    }
+    const rawScore = this._weightSum > 0 ? numerator / this._weightSum : 0;
+    let confidenceScore = rawScore;
+    if (confidence && confidence.size > 0) {
+      let confNumerator = 0;
+      let confDenominator = 0;
+      for (const bit of active) {
+        const conf = confidence.get(bit) ?? 0;
+        confNumerator += conf * this._weights[bit];
+        confDenominator += this._weights[bit];
+      }
+      confidenceScore = confDenominator > 0 ? confNumerator / confDenominator : rawScore;
+    }
+    const finalScore = Math.min(1, rawScore * 0.6 + confidenceScore * 0.4);
+    let decision;
+    if (finalScore >= this._executeThreshold) {
+      decision = "EXECUTE";
+    } else if (finalScore >= this._synthesizeThreshold) {
+      decision = "SYNTHESIZE";
+    } else {
+      decision = "REJECT";
+    }
+    const elapsed = (performance.now() - t0) * 1e3;
+    this._decisionCount++;
+    const result = {
+      decision,
+      rawScore,
+      confidenceScore,
+      finalScore,
+      activeBitCount: active.length,
+      hasEmergency: emergency,
+      scoringTimeUs: elapsed
+    };
+    this._emitTelemetry({ type: "decision", result });
+    return result;
+  }
+  /**
+   * Convenience: aggregate messages then score.
+   * OR-merges all message masks, computes per-bit confidence,
+   * validates schema versions, then runs scoring.
+   */
+  scoreMessages(messages, expectedSchemaVersion) {
+    if (messages.length === 0) {
+      return {
+        decision: "REJECT",
+        rawScore: 0,
+        confidenceScore: 0,
+        finalScore: 0,
+        activeBitCount: 0,
+        hasEmergency: false,
+        scoringTimeUs: 0,
+        staleCount: 0
+      };
+    }
+    let aggregated = 0n;
+    const bitVotes = /* @__PURE__ */ new Map();
+    let staleCount = 0;
+    for (const msg of messages) {
+      if (expectedSchemaVersion !== void 0 && msg.schemaVersion !== expectedSchemaVersion) {
+        staleCount++;
+      }
+      aggregated |= msg.mask;
+      forEachSetBit(msg.mask, (bit) => {
+        bitVotes.set(bit, (bitVotes.get(bit) ?? 0) + 1);
+      });
+    }
+    const confidence = /* @__PURE__ */ new Map();
+    for (const [bit, votes] of bitVotes) {
+      confidence.set(bit, votes / messages.length);
+    }
+    const result = this.score(aggregated, confidence);
+    this._emitTelemetry({
+      type: "score_messages",
+      messageCount: messages.length,
+      staleCount,
+      result
+    });
+    return { ...result, staleCount };
+  }
+  /**
+   * Paper-canonical strategy ranking and decision logic (Section 6).
+   * Uses ŝ_final = 0.6*ŝ_raw + 0.4*c, then applies:
+   * - EXECUTE if lead > 15 points
+   * - SYNTHESIZE if top strategies are within threshold
+   * - REJECT if top score < 40%
+   */
+  scoreStrategies(candidates, options = {}) {
+    if (candidates.length === 0) {
+      const emptyResult = {
+        decision: "REJECT",
+        leadScore: 0,
+        rankings: []
+      };
+      this._emitTelemetry({ type: "strategy_decision", result: emptyResult });
+      return emptyResult;
+    }
+    const leadThreshold = options.leadThreshold ?? 0.15;
+    const rejectThreshold = options.rejectThreshold ?? 0.4;
+    const rankings = candidates.map((candidate) => {
+      const confidence = candidate.confidence ?? options.globalConfidence;
+      const scored = this._scoreMaskComponents(candidate.mask, confidence);
+      return {
+        id: candidate.id,
+        mask: candidate.mask,
+        rawScore: scored.rawScore,
+        confidenceScore: scored.confidenceScore,
+        finalScore: scored.finalScore
+      };
+    }).sort((a, b) => {
+      if (b.finalScore !== a.finalScore) return b.finalScore - a.finalScore;
+      if (a.id < b.id) return -1;
+      if (a.id > b.id) return 1;
+      return 0;
+    });
+    const top1 = rankings[0];
+    const top2 = rankings[1];
+    const leadScore = top2 ? top1.finalScore - top2.finalScore : top1.finalScore;
+    let result;
+    if (top1.finalScore < rejectThreshold) {
+      result = {
+        decision: "REJECT",
+        leadScore,
+        rankings
+      };
+    } else if (leadScore > leadThreshold) {
+      result = {
+        decision: "EXECUTE",
+        selectedStrategyId: top1.id,
+        leadScore,
+        rankings
+      };
+    } else {
+      const contenders = rankings.slice(0, Math.min(3, rankings.length)).filter((candidate) => top1.finalScore - candidate.finalScore <= leadThreshold);
+      const contenderMasks = contenders.length >= 2 ? contenders.map((candidate) => candidate.mask) : rankings.slice(0, Math.min(2, rankings.length)).map((candidate) => candidate.mask);
+      result = {
+        decision: "SYNTHESIZE",
+        synthesizedMask: this._synthesizeMask(contenderMasks),
+        leadScore,
+        rankings
+      };
+    }
+    this._decisionCount++;
+    this._emitTelemetry({ type: "strategy_decision", result });
+    return result;
+  }
+  _scoreMaskComponents(mask, confidence) {
+    if (hasEmergency(mask) && this._emergencyOverride) {
+      return { rawScore: 0, confidenceScore: 0, finalScore: 0 };
+    }
+    const active = activeBits(mask);
+    let numerator = 0;
+    for (const bit of active) {
+      numerator += this._weights[bit];
+    }
+    const rawScore = this._weightSum > 0 ? numerator / this._weightSum : 0;
+    let confidenceScore = rawScore;
+    if (confidence && confidence.size > 0) {
+      let confNumerator = 0;
+      let confDenominator = 0;
+      for (const bit of active) {
+        const conf = confidence.get(bit) ?? 0;
+        confNumerator += conf * this._weights[bit];
+        confDenominator += this._weights[bit];
+      }
+      confidenceScore = confDenominator > 0 ? confNumerator / confDenominator : rawScore;
+    }
+    return {
+      rawScore,
+      confidenceScore,
+      finalScore: Math.min(1, rawScore * 0.6 + confidenceScore * 0.4)
+    };
+  }
+  _synthesizeMask(masks) {
+    if (masks.length === 0) return 0n;
+    const votes = /* @__PURE__ */ new Map();
+    for (const mask of masks) {
+      forEachSetBit(mask, (bit) => {
+        votes.set(bit, (votes.get(bit) ?? 0) + 1);
+      });
+    }
+    const requiredVotes = Math.floor(masks.length / 2) + 1;
+    let synthesized = 0n;
+    for (const [bit, count] of votes) {
+      if (count >= requiredVotes) {
+        synthesized |= 1n << BigInt(bit);
+      }
+    }
+    return synthesized;
+  }
+  _emitTelemetry(event) {
+    this._onTelemetry?.(event);
+  }
+};
+
+// src/ai/session.ts
+var CoordinationSession = class {
+  schema;
+  coordinator;
+  arbiter;
+  _agentIds = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.schema = new SchemaManager({
+      emergencyPrefix: config.emergencyPrefix ?? "EMERGENCY_",
+      emergencyFeatures: config.emergencyFeatures
+    });
+    this.schema.registerAll(config.features);
+    this.coordinator = new Coordinator({
+      ...config.coordinatorConfig,
+      schemaVersion: this.schema.version
+    });
+    this.arbiter = new Arbiter(config.arbiterConfig);
+  }
+  /** Deterministic agent ID: FNV-1a hash of name → uint32. */
+  agentId(name) {
+    const cached = this._agentIds.get(name);
+    if (cached !== void 0) return cached;
+    let hash = 2166136261;
+    for (let i = 0; i < name.length; i++) {
+      hash ^= name.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+    const id = hash >>> 0;
+    this._agentIds.set(name, id);
+    return id;
+  }
+  /** Start a new coordination round. Clears the coordinator buffer. */
+  startRound() {
+    this.coordinator.startRound();
+  }
+  /** Encode features + create message + receive in one call. */
+  report(agentName, features) {
+    const { mask, mapped, unmapped } = encode(
+      features,
+      this.schema.featureToBit
+    );
+    const msg = BitmaskMessage.now(
+      mask,
+      this.agentId(agentName),
+      this.schema.version
+    );
+    const accepted = this.coordinator.receive(msg);
+    return { accepted, mapped, unmapped };
+  }
+  /** Aggregate current buffer + score via arbiter. */
+  decide() {
+    const { aggregatedMask, confidence } = this.coordinator.aggregate();
+    const aggregatedFeatures = decode(aggregatedMask, this.schema.bitToFeatures);
+    const result = this.arbiter.score(aggregatedMask, confidence);
+    return {
+      decision: result.decision,
+      aggregatedFeatures,
+      confidence,
+      result
+    };
+  }
+};
+
+// src/ai/tools.ts
+var import_ai = require("ai");
+var import_zod = require("zod");
+function createCoordinationTools(session) {
+  const reportObservation = (0, import_ai.tool)({
+    description: "Report observed features to the coordination layer. Each feature string is encoded into the shared bitmask.",
+    parameters: import_zod.z.object({
+      agentName: import_zod.z.string().describe("Name identifying this agent"),
+      features: import_zod.z.array(import_zod.z.string()).describe("Feature names observed by this agent")
+    }),
+    execute: async ({ agentName, features }) => {
+      const result = session.report(agentName, features);
+      return {
+        accepted: result.accepted,
+        mapped: result.mapped,
+        unmapped: result.unmapped
+      };
+    }
+  });
+  const getConsensus = (0, import_ai.tool)({
+    description: "Query the current aggregated consensus state across all agents.",
+    parameters: import_zod.z.object({}),
+    execute: async () => {
+      const { aggregatedMask, confidence, uniqueAgents } = session.coordinator.aggregate();
+      const features = decode(aggregatedMask, session.schema.bitToFeatures);
+      const confidenceObj = {};
+      for (const [bit, conf] of confidence) {
+        confidenceObj[String(bit)] = conf;
+      }
+      return {
+        features,
+        confidence: confidenceObj,
+        agentCount: uniqueAgents
+      };
+    }
+  });
+  const requestDecision = (0, import_ai.tool)({
+    description: "Trigger the arbiter to score the current aggregated state and return a decision.",
+    parameters: import_zod.z.object({}),
+    execute: async () => {
+      const { decision, aggregatedFeatures, result } = session.decide();
+      return {
+        decision,
+        score: result.finalScore,
+        features: aggregatedFeatures,
+        hasEmergency: result.hasEmergency
+      };
+    }
+  });
+  return { reportObservation, getConsensus, requestDecision };
+}
+
+// src/ai/middleware.ts
+function createCoordinationMiddleware(session, options = {}) {
+  const { injectConsensus = false, autoEncodeToolCalls = false, agentName } = options;
+  if (autoEncodeToolCalls && !agentName) {
+    throw new Error("agentName is required when autoEncodeToolCalls is enabled");
+  }
+  const middleware = {};
+  if (injectConsensus) {
+    middleware.transformParams = async ({ params }) => {
+      const { aggregatedMask, confidence } = session.coordinator.aggregate();
+      const features = decode(aggregatedMask, session.schema.bitToFeatures);
+      const emergency = hasEmergency(aggregatedMask);
+      const confidenceEntries = Array.from(confidence.entries()).map(([bit, conf]) => `  bit ${bit}: ${(conf * 100).toFixed(0)}%`).join("\n");
+      const consensusText = [
+        "[Coordination Consensus]",
+        `Features: ${features.length > 0 ? features.join(", ") : "none"}`,
+        `Emergency: ${emergency}`,
+        confidenceEntries ? `Confidence:
+${confidenceEntries}` : ""
+      ].filter(Boolean).join("\n");
+      return {
+        ...params,
+        prompt: [
+          { role: "system", content: consensusText },
+          ...params.prompt
+        ]
+      };
+    };
+  }
+  if (autoEncodeToolCalls) {
+    middleware.wrapGenerate = async ({ doGenerate }) => {
+      const result = await doGenerate();
+      if (result.toolCalls && result.toolCalls.length > 0) {
+        const matchingFeatures = result.toolCalls.map((tc) => tc.toolName).filter((name) => session.schema.featureToBit.has(name));
+        if (matchingFeatures.length > 0) {
+          session.report(agentName, matchingFeatures);
+        }
+      }
+      return result;
+    };
+  }
+  return middleware;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CoordinationSession,
+  createCoordinationMiddleware,
+  createCoordinationTools
+});