adaptive-bitmask 1.0.0-rc.1

package/dist/coordinator-Df48t6yJ.d.mts

@@ -0,0 +1,521 @@
+/**
+ * SchemaManager — Dynamic feature-to-bit mapping with frequency-based pruning.
+ *
+ * Implements Section 3.2-3.4 of the Adaptive Bitmask Protocol:
+ * - Deterministic surjection Φ_t: S_t → {0..63}
+ * - Frequency-based pruning (power-law: 20% of features → 80% of activations)
+ * - Emergency bit reservation (bits 56-63, never pruned)
+ * - Collision-aware schema evolution with versioned epochs
+ */
+interface SchemaConfig {
+    /** Maximum features before triggering a prune. Default: BITMASK_WIDTH */
+    maxFeatures?: number;
+    /** Emergency feature prefix. Features starting with this are pinned to bits 56-63. */
+    emergencyPrefix?: string;
+    /** Custom emergency features (alternative to prefix matching). */
+    emergencyFeatures?: string[];
+}
+interface PruneResult {
+    /** Number of features removed from active schema. */
+    pruned: number;
+    /** Number of features retained. */
+    retained: number;
+    /** Schema version after pruning. */
+    version: number;
+    /** Features that were excluded. */
+    excludedFeatures: string[];
+}
+interface SchemaSnapshot {
+    /** Current version (incremented on every schema change). */
+    version: number;
+    /** Feature → bit position mapping. */
+    featureToBit: ReadonlyMap<string, number>;
+    /** Bit position → feature(s) mapping (reverse lookup). */
+    bitToFeatures: ReadonlyMap<number, string[]>;
+    /** Total features tracked (including inactive). */
+    totalTracked: number;
+    /** Number of active (mapped) features. */
+    activeFeatures: number;
+    /** Number of emergency features mapped. */
+    emergencyCount: number;
+}
+interface ExportedSchema {
+    /** Schema version. */
+    version: number;
+    /** Canonical mapping entries (feature -> bit). */
+    entries: Array<[feature: string, bit: number]>;
+    /** Emergency feature prefix. */
+    emergencyPrefix: string;
+    /** Explicit emergency features. */
+    emergencyFeatures: string[];
+    /** Deterministic fingerprint for compatibility checks. */
+    fingerprint: string;
+}
+declare class SchemaManager {
+    private _version;
+    private _featureToBit;
+    private _bitToFeatures;
+    private _activationCounts;
+    private _totalActivations;
+    private _emergencyFeatures;
+    private _emergencyPrefix;
+    private _maxFeatures;
+    constructor(config?: SchemaConfig);
+    /** Current schema version. */
+    get version(): number;
+    /** Read-only view of feature → bit mapping. */
+    get featureToBit(): ReadonlyMap<string, number>;
+    /** Read-only view of bit → features mapping. */
+    get bitToFeatures(): ReadonlyMap<number, string[]>;
+    /** Number of actively mapped features. */
+    get activeFeatureCount(): number;
+    /** Deterministic fingerprint of current schema mapping and version. */
+    get fingerprint(): string;
+    /** Check if a feature is an emergency feature. */
+    isEmergency(feature: string): boolean;
+    /**
+     * 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: string): number;
+    /**
+     * Register multiple features at once.
+     * Returns a map of feature → assigned bit position.
+     */
+    registerAll(features: string[]): Map<string, number>;
+    /**
+     * Record feature activations for frequency tracking.
+     * Call this every coordination round with the observed features.
+     */
+    recordActivations(features: string[]): void;
+    /**
+     * 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(): PruneResult;
+    /** Get a serializable snapshot of the current schema state. */
+    snapshot(): SchemaSnapshot;
+    /**
+     * Export canonical schema state for distribution.
+     * Entries are sorted by bit (then feature) for deterministic serialization.
+     */
+    exportSchema(): ExportedSchema;
+    /**
+     * Import an exported schema state.
+     * Replaces active mappings and resets activation counters.
+     */
+    importSchema(schema: ExportedSchema): void;
+    /** Get activation frequency for a feature. */
+    getFrequency(feature: string): number;
+    /** Get all features ranked by activation frequency. */
+    getRankedFeatures(): Array<{
+        feature: string;
+        count: number;
+        bit: number | undefined;
+    }>;
+    /** Reset all activation counts (but keep schema mappings). */
+    resetCounts(): void;
+    /**
+     * Collision probability for a specific feature:
+     * P(collision) = 1 - (1 - 1/64)^(m - 1)
+     * where m is active feature count.
+     */
+    get theoreticalCollisionRate(): number;
+    /**
+     * Expected excluded feature count under uniform assignment:
+     * E[excluded] = m - 64 * (1 - (1 - 1/64)^m)
+     */
+    expectedExcludedFeatures(featureCount?: number): number;
+    private _registerEmergency;
+    private _registerRegular;
+    private _collectKnownFeatures;
+    private _compareByFrequencyThenName;
+    private _mapsEqual;
+    private _assertExportedSchema;
+    private _computeFingerprint;
+}
+
+/**
+ * Bitmask — 64-bit semantic feature encoding.
+ *
+ * Core primitive of the Adaptive Bitmask Protocol.
+ * Encodes boolean feature vectors as a single uint64,
+ * enabling O(N) coordination with 85× bandwidth reduction.
+ *
+ * Uses BigInt for true 64-bit precision (no floating-point truncation).
+ */
+declare const BITMASK_WIDTH = 64;
+declare const EMERGENCY_RANGE: [number, number];
+declare const HIGH_FREQ_RANGE: [number, number];
+declare const MED_FREQ_RANGE: [number, number];
+/** A 64-bit bitmask represented as BigInt. */
+type Bitmask = bigint;
+/** Create an empty bitmask. */
+declare function empty(): Bitmask;
+/** Set a specific bit position (0-63). */
+declare function setBit(mask: Bitmask, position: number): Bitmask;
+/** Clear a specific bit position. */
+declare function clearBit(mask: Bitmask, position: number): Bitmask;
+/** Test if a specific bit is set. */
+declare function testBit(mask: Bitmask, position: number): boolean;
+/** Count set bits (population count). */
+declare function popcount(mask: Bitmask): number;
+/** Get all set bit positions. */
+declare function activeBits(mask: Bitmask): number[];
+/** Invoke callback for each set bit position (ascending). */
+declare function forEachSetBit(mask: Bitmask, fn: (position: number) => void): void;
+/** OR-merge two bitmasks (union of features). */
+declare function merge(a: Bitmask, b: Bitmask): Bitmask;
+/** AND-intersect two bitmasks (common features). */
+declare function intersect(a: Bitmask, b: Bitmask): Bitmask;
+/** XOR-delta between two bitmasks (changed features). */
+declare function delta(prev: Bitmask, next: Bitmask): Bitmask;
+/** Hamming distance between two bitmasks. */
+declare function hammingDistance(a: Bitmask, b: Bitmask): number;
+/** Check if emergency bits (56-63) are active. */
+declare function hasEmergency(mask: Bitmask): boolean;
+/** Extract only emergency bits. */
+declare function emergencyBits(mask: Bitmask): Bitmask;
+/**
+ * Serialize bitmask to 8-byte Uint8Array (little-endian).
+ * This is the raw bitmask without metadata.
+ */
+declare function toBytes(mask: Bitmask): Uint8Array;
+/** Deserialize 8-byte Uint8Array to bitmask. */
+declare function fromBytes(buf: Uint8Array): Bitmask;
+interface EncodeOptions {
+    /** Throw if any feature is not present in schema mapping. */
+    throwOnUnknownFeatures?: boolean;
+}
+/**
+ * Encode a set of features into a bitmask given a schema mapping.
+ * Features not in the schema are silently ignored.
+ * Returns the mask and count of mapped/unmapped features.
+ */
+declare function encode(features: string[], schema: ReadonlyMap<string, number>, options?: EncodeOptions): {
+    mask: Bitmask;
+    mapped: number;
+    unmapped: number;
+};
+/**
+ * Decode a bitmask back to feature names.
+ * Ambiguous when collisions exist (multiple features per bit).
+ */
+declare function decode(mask: Bitmask, reverseSchema: ReadonlyMap<number, string[]>): string[];
+
+/**
+ * BitmaskMessage — Wire format for agent coordination.
+ *
+ * Layout (24 bytes):
+ *   [0..7]   uint64  mask            — 64-bit feature bitmask
+ *   [8..11]  uint32  agentId         — Unique agent identifier
+ *   [12..19] int64   timestampMs     — Unix timestamp (millis)
+ *   [20..23] uint32  schemaVersion   — Schema epoch for validation
+ *
+ * All fields little-endian for consistency with x86-64.
+ */
+
+declare const MESSAGE_SIZE_BYTES = 24;
+interface BitmaskMessageData {
+    /** 64-bit feature bitmask. */
+    mask: Bitmask;
+    /** Unique agent identifier. */
+    agentId: number;
+    /** Unix timestamp in milliseconds. */
+    timestampMs: number;
+    /** Schema version this mask was encoded against. */
+    schemaVersion: number;
+}
+declare class BitmaskMessage implements BitmaskMessageData {
+    readonly mask: Bitmask;
+    readonly agentId: number;
+    readonly timestampMs: number;
+    readonly schemaVersion: number;
+    constructor(data: BitmaskMessageData);
+    /** Create a message with current timestamp. */
+    static now(mask: Bitmask, agentId: number, schemaVersion: number): BitmaskMessage;
+    /** Wire size in bytes. */
+    get sizeBytes(): number;
+    /**
+     * Serialize to 24-byte ArrayBuffer (little-endian).
+     *
+     * This is the canonical wire format. gRPC/WebSocket transports
+     * should send these bytes directly.
+     */
+    serialize(): ArrayBuffer;
+    /** Serialize to Uint8Array. */
+    toBytes(): Uint8Array;
+    /**
+     * Deserialize from ArrayBuffer or Uint8Array.
+     * Validates length before parsing.
+     */
+    static deserialize(data: ArrayBuffer | Uint8Array): BitmaskMessage;
+    /**
+     * JSON-equivalent size for comparison.
+     * Useful for demonstrating compression ratio.
+     */
+    get jsonSize(): number;
+    /** Compression ratio vs JSON encoding. */
+    get compressionVsJson(): number;
+    /** Human-readable string for debugging. */
+    toString(): string;
+    private _assertValid;
+    private _assertUint32;
+}
+
+/**
+ * Arbiter — Weighted linear scoring and decision synthesis.
+ *
+ * Implements Section 6 of the Adaptive Bitmask Protocol:
+ * - Weighted linear scoring: ŝ = Σ(w_k · b_k) / Σ(w_k)
+ * - Three-tier decision logic: EXECUTE / SYNTHESIZE / REJECT
+ * - Configurable thresholds and weight vectors
+ * - Sub-millisecond execution (measured: 15μs mean, 26μs p99)
+ */
+
+/** Decision outcome from the arbiter. */
+type Decision = 'EXECUTE' | 'SYNTHESIZE' | 'REJECT';
+/** Full decision result with audit trail. */
+interface ArbiterResult {
+    /** The decision: EXECUTE, SYNTHESIZE, or REJECT. */
+    decision: Decision;
+    /** Raw weighted score [0, 1]. */
+    rawScore: number;
+    /** Confidence-adjusted score [0, 1]. */
+    confidenceScore: number;
+    /** Final composite score [0, 1]. */
+    finalScore: number;
+    /** Number of active bits in the aggregated mask. */
+    activeBitCount: number;
+    /** Whether emergency bits were active. */
+    hasEmergency: boolean;
+    /** Scoring computation time in microseconds. */
+    scoringTimeUs: number;
+}
+/** Per-bit confidence from aggregation (what fraction of agents set this bit). */
+type BitConfidence = Map<number, number>;
+interface StrategyCandidate {
+    /** Stable strategy identifier. */
+    id: string;
+    /** Candidate bitmask for strategy evaluation. */
+    mask: Bitmask;
+    /** Optional per-bit confidence specific to this strategy. */
+    confidence?: BitConfidence;
+}
+interface ScoreStrategiesOptions {
+    /** Minimum lead required for direct execute. Default: 0.15 (15 points). */
+    leadThreshold?: number;
+    /** Minimum top score required to avoid reject. Default: 0.40. */
+    rejectThreshold?: number;
+    /** Fallback confidence map when candidate-level confidence is absent. */
+    globalConfidence?: BitConfidence;
+}
+interface StrategyScore {
+    /** Strategy identifier. */
+    id: string;
+    /** Strategy mask. */
+    mask: Bitmask;
+    /** Raw weighted score ŝ_raw. */
+    rawScore: number;
+    /** Confidence score c. */
+    confidenceScore: number;
+    /** Final composite score ŝ_final = 0.6*ŝ_raw + 0.4*c. */
+    finalScore: number;
+}
+interface StrategyDecisionResult {
+    /** Final decision outcome. */
+    decision: Decision;
+    /** Selected strategy when decision is EXECUTE. */
+    selectedStrategyId?: string;
+    /** Synthesized mask when decision is SYNTHESIZE. */
+    synthesizedMask?: Bitmask;
+    /** Lead score (top1 - top2, or top1 if only one strategy). */
+    leadScore: number;
+    /** Ranked strategy scores (descending finalScore). */
+    rankings: StrategyScore[];
+}
+type ArbiterTelemetryEvent = {
+    type: 'decision';
+    result: ArbiterResult;
+} | {
+    type: 'score_messages';
+    messageCount: number;
+    staleCount: number;
+    result: ArbiterResult;
+} | {
+    type: 'strategy_decision';
+    result: StrategyDecisionResult;
+};
+interface ArbiterConfig {
+    /** Weight vector: importance of each bit position [0..63]. */
+    weights?: number[];
+    /**
+     * Score threshold above which to EXECUTE.
+     * Default: 0.55 (paper Section 6.1).
+     */
+    executeThreshold?: number;
+    /**
+     * Score threshold above which to SYNTHESIZE (below execute).
+     * Default: 0.40 (paper Section 6.1).
+     */
+    synthesizeThreshold?: number;
+    /**
+     * If true, emergency bits trigger immediate REJECT regardless of score.
+     * Default: true.
+     */
+    emergencyOverride?: boolean;
+    /** Optional telemetry callback for runtime observability. */
+    onTelemetry?: (event: ArbiterTelemetryEvent) => void;
+}
+declare class Arbiter {
+    private _weights;
+    private _weightSum;
+    private _executeThreshold;
+    private _synthesizeThreshold;
+    private _emergencyOverride;
+    private _onTelemetry;
+    private _decisionCount;
+    constructor(config?: ArbiterConfig);
+    /** Number of decisions made since creation. */
+    get decisionCount(): number;
+    /** Set the weight for a specific bit position. */
+    setWeight(position: number, weight: number): void;
+    /** Get the current weight vector (copy). */
+    get weights(): number[];
+    /**
+     * 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: Bitmask, confidence?: BitConfidence): ArbiterResult;
+    /**
+     * Convenience: aggregate messages then score.
+     * OR-merges all message masks, computes per-bit confidence,
+     * validates schema versions, then runs scoring.
+     */
+    scoreMessages(messages: BitmaskMessage[], expectedSchemaVersion?: number): ArbiterResult & {
+        staleCount: number;
+    };
+    /**
+     * 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: StrategyCandidate[], options?: ScoreStrategiesOptions): StrategyDecisionResult;
+    private _scoreMaskComponents;
+    private _synthesizeMask;
+    private _emitTelemetry;
+}
+/**
+ * Create a financial trading arbiter with domain-specific weights.
+ * Matches the weight configuration from the paper's evaluation.
+ */
+declare function createFinancialArbiter(overrides?: Partial<ArbiterConfig>): Arbiter;
+/**
+ * Create a robotic coordination arbiter with safety-first weights.
+ */
+declare function createRoboticArbiter(overrides?: Partial<ArbiterConfig>): Arbiter;
+
+/**
+ * Coordinator — Aggregates bitmasks from multiple agents.
+ *
+ * Implements the Meta-Coordinator layer:
+ * - Collects BitmaskMessages from worker agents
+ * - OR-aggregates into unified consensus mask
+ * - Computes per-bit confidence (vote fraction)
+ * - Provides deadline-based collection with timeout
+ */
+
+type StaleMessagePolicy = 'accept' | 'warn' | 'drop';
+type CoordinatorDropReason = 'deadline' | 'stale';
+type CoordinatorTelemetryEvent = {
+    type: 'message_accepted';
+    agentId: number;
+    stale: boolean;
+    replaced: boolean;
+} | {
+    type: 'message_dropped';
+    agentId: number;
+    reason: CoordinatorDropReason;
+} | {
+    type: 'round_aggregated';
+    result: AggregationResult;
+};
+interface AggregationResult {
+    /** OR-aggregated mask (union of all agent observations). */
+    aggregatedMask: Bitmask;
+    /** Per-bit confidence: fraction of agents that set each bit. */
+    confidence: BitConfidence;
+    /** Number of messages aggregated. */
+    messageCount: number;
+    /** Number of unique agents represented. */
+    uniqueAgents: number;
+    /** Number of schema-stale messages (mismatched version). */
+    staleMessages: number;
+    /** Number of stale messages dropped at receive-time. */
+    droppedStaleMessages: number;
+    /** Aggregation time in microseconds. */
+    aggregationTimeUs: number;
+}
+interface CoordinatorConfig {
+    /** Expected number of agents (for pre-allocation). */
+    expectedAgents?: number;
+    /** Deadline in ms — messages arriving after this are dropped. */
+    deadlineMs?: number;
+    /** Expected schema version. Messages with different versions are flagged. */
+    schemaVersion?: number;
+    /** Policy when schema versions mismatch. Default: 'accept'. */
+    staleMessagePolicy?: StaleMessagePolicy;
+    /** Optional telemetry callback for runtime observability. */
+    onTelemetry?: (event: CoordinatorTelemetryEvent) => void;
+}
+declare class Coordinator {
+    private _buffer;
+    private _seenAgents;
+    private _schemaVersion;
+    private _deadlineMs;
+    private _staleMessagePolicy;
+    private _onTelemetry;
+    private _roundStartTime;
+    private _aggregationCount;
+    private _droppedStaleMessages;
+    constructor(config?: CoordinatorConfig);
+    /** Number of messages in current buffer. */
+    get bufferedCount(): number;
+    /** Total aggregation rounds performed. */
+    get aggregationCount(): number;
+    /** Update expected schema version. */
+    set schemaVersion(version: number);
+    /** Start a new coordination round. Clears the buffer. */
+    startRound(): void;
+    /**
+     * Receive a message from an agent.
+     * Returns false if the message was dropped (deadline exceeded or duplicate agent).
+     */
+    receive(message: BitmaskMessage): boolean;
+    /**
+     * Receive multiple messages at once.
+     * Returns number of messages accepted.
+     */
+    receiveAll(messages: BitmaskMessage[]): number;
+    /**
+     * Aggregate all buffered messages into a consensus result.
+     * Clears the buffer after aggregation.
+     */
+    aggregate(): AggregationResult;
+    private _emitTelemetry;
+}
+
+export { Arbiter as A, BitmaskMessage as B, Coordinator as C, type Decision as D, EMERGENCY_RANGE as E, delta as F, emergencyBits as G, HIGH_FREQ_RANGE as H, empty as I, encode as J, forEachSetBit as K, fromBytes as L, MED_FREQ_RANGE as M, hammingDistance as N, hasEmergency as O, type PruneResult as P, intersect as Q, merge as R, SchemaManager as S, popcount as T, setBit as U, testBit as V, toBytes as W, type SchemaConfig as a, type CoordinatorConfig as b, type ArbiterConfig as c, type ArbiterResult as d, type AggregationResult as e, type ArbiterTelemetryEvent as f, BITMASK_WIDTH as g, type BitConfidence as h, type Bitmask as i, type BitmaskMessageData as j, type CoordinatorDropReason as k, type CoordinatorTelemetryEvent as l, type EncodeOptions as m, type ExportedSchema as n, MESSAGE_SIZE_BYTES as o, type SchemaSnapshot as p, type ScoreStrategiesOptions as q, type StaleMessagePolicy as r, type StrategyCandidate as s, type StrategyDecisionResult as t, type StrategyScore as u, activeBits as v, clearBit as w, createFinancialArbiter as x, createRoboticArbiter as y, decode as z };