@mxf-dev/core 1.0.0 → 2.0.0

package/dist/mxp/BinaryProtocolLayer.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**
@@ -41,8 +41,19 @@ export class BinaryProtocolLayer {
     // Compression thresholds and settings
     compressionThresholds = {
         minSize: 1024, // Only compress messages > 1KB
-        brotliThreshold: 10240, // Use Brotli for messages > 10KB
-        gzipThreshold: 1024 // Use Gzip for smaller messages
+        brotliThreshold: 10240 // Use Brotli for messages > 10KB
+    };
+    /** Counters for getCompressionStats(). Updated on every encode. */
+    stats = {
+        totalCompressions: 0,
+        totalOriginalBytes: 0,
+        totalCompressedBytes: 0,
+        algorithmUsage: {
+            none: 0,
+            gzip: 0,
+            brotli: 0,
+            msgpack: 0
+        }
     };
     constructor() {
         this.logger = new Logger('info', 'BinaryProtocolLayer', 'server');
@@ -118,6 +129,11 @@ export class BinaryProtocolLayer {
                 default:
                     throw new Error(`Unknown encoding format: ${format}`);
             }
+            // Record the measured result so getCompressionStats() reports reality
+            this.stats.totalCompressions++;
+            this.stats.totalOriginalBytes += originalSize;
+            this.stats.totalCompressedBytes += result.compressedSize;
+            this.stats.algorithmUsage[result.algorithm]++;
             // Emit compression event for analytics using proper payload creator
             const bandwidthEventPayload = createMxpBandwidthOptimizationEventPayload(Events.Mxp.BANDWIDTH_OPTIMIZATION_COMPLETE, agentId || 'system', channelId, {
                 operationId: crypto.randomUUID(),
@@ -128,72 +144,64 @@ export class BinaryProtocolLayer {
                 timestamp: Date.now()
             }, { source: 'BinaryProtocolLayer' });
             EventBus.server.emit(Events.Mxp.BANDWIDTH_OPTIMIZATION_COMPLETE, bandwidthEventPayload);
-            //     format: result.format,
-            //     algorithm: result.algorithm,
-            //     originalSize,
-            //     compressedSize: result.compressedSize,
-            //     compressionRatio: result.compressionRatio,
-            //     bandwidthSaved: originalSize - result.compressedSize
-            // });
             return result;
         }
         catch (error) {
+            const message_ = error instanceof Error ? error.message : String(error);
             this.logger.error('Message encoding failed', {
-                error: error instanceof Error ? error.message : String(error),
+                error: message_,
                 channelId,
                 messageType: message.type
             });
-            // Fallback: return original JSON
-            const jsonData = JSON.stringify(message);
-            const originalBuffer = Buffer.from(jsonData, 'utf8');
-            return {
-                data: originalBuffer,
-                format: 'json',
-                algorithm: 'none',
-                originalSize: originalBuffer.length,
-                compressedSize: originalBuffer.length,
-                compressionRatio: 1.0
-            };
+            // No silent fallback to plain JSON: the caller asked for an encoded
+            // message and must find out that it did not get one.
+            throw new Error(`Binary protocol encoding failed for '${message.type}': ${message_}`);
         }
     }
     /**
-     * Decode compressed message back to original format
+     * Decode an encoded message back to its original form.
+     *
+     * @throws If the payload cannot be decoded. A corrupt message is an error,
+     *         not an empty result.
      */
     decodeMessage(compressedData) {
         try {
-            let message;
             switch (compressedData.format) {
-                case 'json':
-                    // Plain JSON
+                case 'json': {
                     const jsonString = compressedData.data.toString('utf8');
-                    message = JSON.parse(jsonString);
-                    break;
+                    return JSON.parse(jsonString);
+                }
                 case 'msgpack':
-                    // MessagePack format
-                    message = msgpack.decode(compressedData.data);
-                    break;
-                case 'msgpack-compressed':
-                    // MessagePack + Brotli compression
+                    return msgpack.decode(compressedData.data);
+                case 'msgpack-compressed': {
                     const decompressedMsgpack = zlib.brotliDecompressSync(compressedData.data);
-                    message = msgpack.decode(decompressedMsgpack);
-                    break;
+                    return msgpack.decode(decompressedMsgpack);
+                }
                 default:
                     throw new Error(`Unknown encoding format: ${compressedData.format}`);
             }
-            // ;
-            return message;
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
             this.logger.error('Message decoding failed', {
-                error: error instanceof Error ? error.message : String(error),
+                error: message,
                 format: compressedData.format,
                 algorithm: compressedData.algorithm
             });
-            return null;
+            throw new Error(`Binary protocol decoding failed (${compressedData.format}): ${message}`);
         }
     }
     /**
-     * Batch compress multiple messages with intelligent batching
+     * Encode a group of messages as one or more batches.
+     *
+     * Batches that exceed maxBatchSize are split in half recursively until each
+     * part fits, and EVERY part is returned. An earlier version encoded only the
+     * first half and discarded the rest, silently losing messages.
+     *
+     * @returns One CompressionResult per batch, or null when bandwidth
+     *          optimization is disabled or there is nothing to send.
+     * @throws If a batch cannot be encoded, or a single message is too large to
+     *         fit in maxBatchSize on its own.
      */
     batchEncode(messages, channelId, agentId, options = {}) {
         this.validator.assertIsArray(messages, 'Messages must be an array');
@@ -206,46 +214,35 @@ export class BinaryProtocolLayer {
             return null;
         }
         const maxBatchSize = options.maxBatchSize || 32768; // 32KB default
-        try {
-            // Create batch envelope
-            const batchMessage = {
-                type: 'mxp_batch',
-                payload: {
-                    version: '2.0',
-                    messageCount: messages.length,
-                    messages: messages
-                },
-                metadata: {
-                    batchId: `batch_${uuidv4()}`,
-                    timestamp: Date.now(),
-                    compressionLevel: options.compressionLevel || 'standard'
-                }
-            };
-            // Check if batch exceeds size limit
-            const batchJson = JSON.stringify(batchMessage);
-            const batchBuffer = Buffer.from(batchJson, 'utf8');
-            if (batchBuffer.length > maxBatchSize) {
-                this.logger.warn(`Batch size ${batchBuffer.length} exceeds limit ${maxBatchSize}, splitting`);
-                // Split into smaller batches (recursive approach)
-                const midpoint = Math.floor(messages.length / 2);
-                const firstHalf = messages.slice(0, midpoint);
-                const secondHalf = messages.slice(midpoint);
-                // Process first half only for now (in full implementation would handle both)
-                return this.batchEncode(firstHalf, channelId, agentId, options);
-            }
-            // Compress the batch
-            const compressionResult = this.encodeMessage(batchMessage, channelId, agentId);
-            if (compressionResult) {
+        // Create batch envelope
+        const batchMessage = {
+            type: 'mxp_batch',
+            payload: {
+                version: '2.0',
+                messageCount: messages.length,
+                messages: messages
+            },
+            metadata: {
+                batchId: `batch_${uuidv4()}`,
+                timestamp: Date.now(),
+                compressionLevel: options.compressionLevel || 'standard'
             }
-            return compressionResult;
+        };
+        // Check if batch exceeds size limit
+        const batchBuffer = Buffer.from(JSON.stringify(batchMessage), 'utf8');
+        if (batchBuffer.length <= maxBatchSize) {
+            const encoded = this.encodeMessage(batchMessage, channelId, agentId);
+            return encoded ? [encoded] : null;
         }
-        catch (error) {
-            this.logger.error('Batch encoding failed', {
-                error: error instanceof Error ? error.message : String(error),
-                messageCount: messages.length
-            });
-            return null;
+        if (messages.length === 1) {
+            throw new Error(`Message '${messages[0].type}' is ${batchBuffer.length} bytes, which exceeds the ` +
+                `maximum batch size of ${maxBatchSize} bytes and cannot be split further.`);
         }
+        this.logger.warn(`Batch size ${batchBuffer.length} exceeds limit ${maxBatchSize}, splitting`);
+        const midpoint = Math.floor(messages.length / 2);
+        const firstHalf = this.batchEncode(messages.slice(0, midpoint), channelId, agentId, options);
+        const secondHalf = this.batchEncode(messages.slice(midpoint), channelId, agentId, options);
+        return [...(firstHalf ?? []), ...(secondHalf ?? [])];
     }
     /**
      * Select optimal encoding format based on message characteristics
@@ -273,40 +270,30 @@ export class BinaryProtocolLayer {
         return MxpConfigManager.getInstance().isFeatureEnabled(channelId, 'bandwidthOptimization', agentId);
     }
     /**
-     * Get compression statistics for monitoring
+     * Compression statistics measured from the encodes this instance performed.
+     *
+     * averageCompressionRatio is compressedBytes/originalBytes across all
+     * encodes (1.0 = no reduction), and is 0 before anything has been encoded.
      */
     getCompressionStats() {
-        // In full implementation, these would be tracked
+        const { totalCompressions, totalOriginalBytes, totalCompressedBytes } = this.stats;
         return {
-            totalCompressions: 0,
-            averageCompressionRatio: 0.3, // 70% reduction typical
-            totalBandwidthSaved: 0,
-            algorithmUsage: {
-                'none': 0,
-                'gzip': 0,
-                'brotli': 0,
-                'msgpack': 0
-            }
+            totalCompressions,
+            averageCompressionRatio: totalOriginalBytes > 0
+                ? totalCompressedBytes / totalOriginalBytes
+                : 0,
+            totalBandwidthSaved: totalOriginalBytes - totalCompressedBytes,
+            algorithmUsage: { ...this.stats.algorithmUsage }
         };
     }
     /**
-     * Create streaming compression for real-time communication
-     * Placeholder for future implementation with Socket.IO streaming
+     * Reset the compression counters (used by tests).
      */
-    createCompressionStream(channelId, agentId) {
-        // Check if compression is enabled
-        if (!this.shouldApplyCompression(channelId, agentId)) {
-            return null;
-        }
-        // In full implementation, would return Transform stream
-        // For now, return configuration object
-        return {
-            channelId,
-            agentId,
-            compressionEnabled: true,
-            algorithm: 'gzip', // Start with gzip for streaming
-            flushInterval: 100 // Flush every 100ms for low latency
-        };
+    resetCompressionStats() {
+        this.stats.totalCompressions = 0;
+        this.stats.totalOriginalBytes = 0;
+        this.stats.totalCompressedBytes = 0;
+        this.stats.algorithmUsage = { none: 0, gzip: 0, brotli: 0, msgpack: 0 };
     }
 }
 // Note: Use BinaryProtocolLayer.getInstance() to get the singleton instance

package/dist/mxp/BinaryProtocolLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryProtocolLayer.js","sourceRoot":"","sources":["../../src/mxp/BinaryProtocolLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,0CAA0C,EAAE,MAAM,kCAAkC,CAAC;AAC9F,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,MAAM,MAAM,QAAQ,CAAC;AAsB5B,MAAM,OAAO,mBAAmB;IACpB,MAAM,CAAC,QAAQ,GAA+B,IAAI,CAAC;IAE1C,MAAM,CAAS;IACf,SAAS,GAAG,qBAAqB,CAAC,qBAAqB,CAAC,CAAC;IAE1E,sCAAsC;IACrB,qBAAqB,GAAG;QACrC,OAAO,EAAE,IAAI,EAAO,+BAA+B;QACnD,eAAe,EAAE,KAAK,EAAG,iCAAiC;QAC1D,aAAa,EAAE,IAAI,CAAM,gCAAgC;KAC5D,CAAC;IAEF;QACI,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,WAAW;QACrB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC;YAChC,mBAAmB,CAAC,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAC7D,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IACxC,CAAC;IAED;;;OAGG;IACI,aAAa,CAChB,OAAmB,EACnB,SAAiB,EACjB,OAAgB;QAEhB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC,SAAS,EAAE,wBAAwB,CAAC,CAAC;QAE3E,6CAA6C;QAC7C,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC,gBAAgB,CACzE,SAAS,EACT,uBAAuB,EACvB,OAAO,CACV,CAAC;QAEF,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,CAAC,4CAA4C;QAC7D,CAAC;QAED,IAAI,CAAC;YACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAE7B,kCAAkC;YAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACrD,MAAM,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC;YAE3C,IAAI;YAEJ,oCAAoC;YACpC,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAC/D,IAAI,MAAyB,CAAC;YAE9B,QAAQ,MAAM,EAAE,CAAC;gBACb,KAAK,MAAM;oBACP,2CAA2C;oBAC3C,MAAM,GAAG;wBACL,IAAI,EAAE,cAAc;wBACpB,MAAM,EAAE,MAAM;wBACd,SAAS,EAAE,MAAM;wBACjB,YAAY;wBACZ,cAAc,EAAE,YAAY;wBAC5B,gBAAgB,EAAE,GAAG;qBACxB,CAAC;oBACF,MAAM;gBAEV,KAAK,SAAS;oBACV,iEAAiE;oBACjE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;oBACzD,MAAM,GAAG;wBACL,IAAI,EAAE,WAAW;wBACjB,MAAM,EAAE,SAAS;wBACjB,SAAS,EAAE,SAAS;wBACpB,YAAY;wBACZ,cAAc,EAAE,WAAW,CAAC,MAAM;wBAClC,gBAAgB,EAAE,WAAW,CAAC,MAAM,GAAG,YAAY;qBACtD,CAAC;oBACF,MAAM;gBAEV,KAAK,oBAAoB;oBACrB,oDAAoD;oBACpD,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC3D,MAAM,cAAc,GAAG,IAAI,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;oBAC9D,MAAM,GAAG;wBACL,IAAI,EAAE,cAAc;wBACpB,MAAM,EAAE,oBAAoB;wBAC5B,SAAS,EAAE,QAAQ;wBACnB,YAAY;wBACZ,cAAc,EAAE,cAAc,CAAC,MAAM;wBACrC,gBAAgB,EAAE,cAAc,CAAC,MAAM,GAAG,YAAY;qBACzD,CAAC;oBACF,MAAM;gBAEV;oBACI,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;YAC9D,CAAC;YAED,oEAAoE;YACpE,MAAM,qBAAqB,GAAG,0CAA0C,CACpE,MAAM,CAAC,GAAG,CAAC,+BAA+B,EAC1C,OAAO,IAAI,QAAQ,EACnB,SAAS,EACT;gBACI,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE;gBAChC,YAAY;gBACZ,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,QAAQ,EAAE,MAAM,CAAC,MAA8D;gBAC/E,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACxB,EACD,EAAE,MAAM,EAAE,qBAAqB,EAAE,CACpC,CAAC;YACF,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,+BAA+B,EAAE,qBAAqB,CAAC,CAAC;YAExF,6BAA6B;YAC7B,mCAAmC;YACnC,oBAAoB;YACpB,6CAA6C;YAC7C,iDAAiD;YACjD,2DAA2D;YAC3D,MAAM;YAEN,OAAO,MAAM,CAAC;QAElB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE;gBACzC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,SAAS;gBACT,WAAW,EAAE,OAAO,CAAC,IAAI;aAC5B,CAAC,CAAC;YAEH,iCAAiC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACrD,OAAO;gBACH,IAAI,EAAE,cAAc;gBACpB,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,MAAM;gBACjB,YAAY,EAAE,cAAc,CAAC,MAAM;gBACnC,cAAc,EAAE,cAAc,CAAC,MAAM;gBACrC,gBAAgB,EAAE,GAAG;aACxB,CAAC;QACN,CAAC;IACL,CAAC;IAED;;OAEG;IACI,aAAa,CAAC,cAAiC;QAClD,IAAI,CAAC;YACD,IAAI,OAAmB,CAAC;YAExB,QAAQ,cAAc,CAAC,MAAM,EAAE,CAAC;gBAC5B,KAAK,MAAM;oBACP,aAAa;oBACb,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBACxD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAe,CAAC;oBAC/C,MAAM;gBAEV,KAAK,SAAS;oBACV,qBAAqB;oBACrB,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAe,CAAC;oBAC5D,MAAM;gBAEV,KAAK,oBAAoB;oBACrB,mCAAmC;oBACnC,MAAM,mBAAmB,GAAG,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;oBAC3E,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAe,CAAC;oBAC5D,MAAM;gBAEV;oBACI,MAAM,IAAI,KAAK,CAAC,4BAA4B,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7E,CAAC;YAED,IAAI;YAEJ,OAAO,OAAO,CAAC;QAEnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE;gBACzC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,MAAM,EAAE,cAAc,CAAC,MAAM;gBAC7B,SAAS,EAAE,cAAc,CAAC,SAAS;aACtC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;OAEG;IACI,WAAW,CACd,QAAsB,EACtB,SAAiB,EACjB,OAAgB,EAChB,UAGI,EAAE;QAEN,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC;QAEpE,6CAA6C;QAC7C,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC,gBAAgB,CACzE,SAAS,EACT,uBAAuB,EACvB,OAAO,CACV,CAAC;QAEF,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC,CAAC,eAAe;QAEnE,IAAI,CAAC;YACD,wBAAwB;YACxB,MAAM,YAAY,GAAe;gBAC7B,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACL,OAAO,EAAE,KAAK;oBACd,YAAY,EAAE,QAAQ,CAAC,MAAM;oBAC7B,QAAQ,EAAE,QAAQ;iBACrB;gBACD,QAAQ,EAAE;oBACN,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE;oBAC5B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;oBACrB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,UAAU;iBAC3D;aACJ,CAAC;YAEF,oCAAoC;YACpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;YAC/C,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAEnD,IAAI,WAAW,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;gBACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,MAAM,kBAAkB,YAAY,aAAa,CAAC,CAAC;gBAE9F,kDAAkD;gBAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACjD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC9C,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAE5C,6EAA6E;gBAC7E,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YACpE,CAAC;YAED,qBAAqB;YACrB,MAAM,iBAAiB,GAAG,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YAE/E,IAAI,iBAAiB,EAAE,CAAC;YACxB,CAAC;YAED,OAAO,iBAAiB,CAAC;QAE7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;gBACvC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,YAAY,EAAE,QAAQ,CAAC,MAAM;aAChC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,OAAmB,EAAE,IAAY;QACzD,oDAAoD;QACpD,IAAI,IAAI,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,CAAC;YAC5C,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,mDAAmD;QACnD,IAAI,IAAI,GAAG,IAAI,CAAC,qBAAqB,CAAC,eAAe,EAAE,CAAC;YACpD,OAAO,oBAAoB,CAAC;QAChC,CAAC;QAED,oDAAoD;QACpD,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,oBAAoB,CAAC;QAChC,CAAC;QAED,gEAAgE;QAChE,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;OAEG;IACI,sBAAsB,CAAC,SAAiB,EAAE,OAAgB;QAC7D,OAAO,gBAAgB,CAAC,WAAW,EAAE,CAAC,gBAAgB,CAClD,SAAS,EACT,uBAAuB,EACvB,OAAO,CACV,CAAC;IACN,CAAC;IAED;;OAEG;IACI,mBAAmB;QAMtB,iDAAiD;QACjD,OAAO;YACH,iBAAiB,EAAE,CAAC;YACpB,uBAAuB,EAAE,GAAG,EAAE,wBAAwB;YACtD,mBAAmB,EAAE,CAAC;YACtB,cAAc,EAAE;gBACZ,MAAM,EAAE,CAAC;gBACT,MAAM,EAAE,CAAC;gBACT,QAAQ,EAAE,CAAC;gBACX,SAAS,EAAE,CAAC;aACf;SACJ,CAAC;IACN,CAAC;IAED;;;OAGG;IACI,uBAAuB,CAAC,SAAiB,EAAE,OAAgB;QAC9D,kCAAkC;QAClC,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC;QAChB,CAAC;QAGD,wDAAwD;QACxD,uCAAuC;QACvC,OAAO;YACH,SAAS;YACT,OAAO;YACP,kBAAkB,EAAE,IAAI;YACxB,SAAS,EAAE,MAAM,EAAE,gCAAgC;YACnD,aAAa,EAAE,GAAG,CAAE,oCAAoC;SAC3D,CAAC;IACN,CAAC;;AAGL,4EAA4E"}
+{"version":3,"file":"BinaryProtocolLayer.js","sourceRoot":"","sources":["../../src/mxp/BinaryProtocolLayer.ts"],"names":[],"mappings":"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"}

package/dist/mxp/ContextCompressionEngine.d.ts

@@ -14,23 +14,31 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 import { ChannelMessage, AgentMessage } from '../schemas/MessageSchemas.js';
 import { ConversationMessage } from '../interfaces/ConversationMessage.js';
 export interface CompressedContext {
+    /** The most recent messages, kept verbatim. */
     recent: any[];
+    /** Structured summary standing in for the older messages. Lossy. */
     compressed: string;
+    /** Measured token estimate of the messages that were summarized. */
     originalTokens: number;
+    /** Measured token estimate of the summary that replaced them. */
     compressedTokens: number;
+    /** compressedTokens / originalTokens, measured after the fact. */
     ratio: number;
+    /** Reference IDs for context stored instead of summarized. */
     contextReferences: string[];
 }
 export interface CompressionOptions {
+    /** Number of recent messages kept verbatim (default: 5). */
     windowSize?: number;
-    compressionRatio?: number;
+    /** Terms that must appear in the summary even if no section captured them. */
     preserveKeywords?: string[];
+    /** Store large blocks as retrievable references instead of summarizing. */
     useContextReferences?: boolean;
     channelId: string;
     agentId?: string;
@@ -41,14 +49,25 @@ export declare class ContextCompressionEngine {
     private readonly validator;
     private contextCache;
     private readonly maxCacheSize;
+    /** Counters for getCompressionStats(). Updated on every compression. */
+    private readonly stats;
     private constructor();
     /**
      * Get the singleton instance of ContextCompressionEngine
      */
     static getInstance(): ContextCompressionEngine;
     /**
-     * Compress conversation history using intelligent sliding window approach
-     * Only processes if context compression is enabled for the channel/agent
+     * Replace older conversation history with a structured summary, keeping the
+     * most recent `windowSize` messages verbatim.
+     *
+     * This is LOSSY: detail in the older messages that no summary section
+     * captures is discarded. The returned token counts and ratio are measured,
+     * not projected, so the caller can see how much was dropped.
+     *
+     * @returns null when context compression is disabled for this channel/agent.
+     * @throws If summarization fails. There is no "return the recent messages and
+     *         pretend it worked" path — a caller that thinks it has the earlier
+     *         context when it does not will act on missing information.
      */
     compressConversation(messages: (ChannelMessage | AgentMessage)[], options: CompressionOptions): Promise<CompressedContext | null>;
     /**
@@ -60,16 +79,36 @@ export declare class ContextCompressionEngine {
      */
     getContextByReference(contextId: string): any[] | null;
     /**
-     * Apply semantic deduplication to remove similar messages
-     * This is a simplified version - in full implementation would use PatternLearningService
+     * Drop messages whose content is identical to one already seen.
+     *
+     * This is an exact-match filter: content is lowercased, stripped of
+     * punctuation and repeated whitespace, then hashed. Messages that merely
+     * say the same thing in different words are both kept — there is no
+     * semantic similarity here, and the method no longer claims otherwise.
+     */
+    private removeExactDuplicates;
+    /**
+     * Summarize messages into a structured digest.
+     *
+     * Delegates to StructuredSummaryBuilder, which extracts the primary request,
+     * key decisions, tool executions, errors, verbatim user directives, and
+     * current state. Deterministic, local, and lossy — no model is called.
+     *
+     * @throws If the summary cannot be built.
+     */
+    private summarizeMessages;
+    /**
+     * Adapt a ChannelMessage/AgentMessage onto the ConversationMessage shape the
+     * summary builder consumes.
      */
-    private applySemanticDeduplication;
+    private toConversationMessage;
     /**
-     * Compress content using SystemLLM (placeholder - integrates with existing SystemLlmService)
+     * Pull the text out of the message shapes that flow through the framework.
+     * Returns null when there is no readable content.
      */
-    private compressWithSystemLLM;
+    private extractContent;
     /**
-     * Normalize message content for deduplication
+     * Normalize message content for exact-duplicate detection
      */
     private normalizeContent;
     /**
@@ -81,7 +120,11 @@ export declare class ContextCompressionEngine {
      */
     shouldApplyCompression(channelId: string, agentId?: string): boolean;
     /**
-     * Get compression statistics for monitoring
+     * Compression statistics measured from the work this instance actually did.
+     *
+     * averageCompressionRatio is summarizedTokens/originalTokens across every
+     * compression (1.0 = no reduction), and is 0 before anything has been
+     * compressed.
      */
     getCompressionStats(): {
         totalCompressions: number;
@@ -89,6 +132,10 @@ export declare class ContextCompressionEngine {
         cacheSize: number;
         contextReferencesCreated: number;
     };
+    /**
+     * Reset the compression counters (used by tests).
+     */
+    resetCompressionStats(): void;
     /**
      * Clear the context cache (useful for testing or memory management)
      */

package/dist/mxp/ContextCompressionEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextCompressionEngine.d.ts","sourceRoot":"","sources":["../../src/mxp/ContextCompressionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAcH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAU5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,wBAAwB;IACjC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAyC;IAEhE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAC/E,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAO;IAEpC,OAAO;IAIP;;OAEG;WACW,WAAW,IAAI,wBAAwB;IAOrD;;;OAGG;IACU,oBAAoB,CAC7B,QAAQ,EAAE,CAAC,cAAc,GAAG,YAAY,CAAC,EAAE,EAC3C,OAAO,EAAE,kBAAkB,GAC5B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAwIpC;;OAEG;YACW,sBAAsB;IA0BpC;;OAEG;IACI,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI;IAU7D;;;OAGG;YACW,0BAA0B;IAkCxC;;OAEG;YACW,qBAAqB;IAyCnC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;OAEG;IACI,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAQ3E;;OAEG;IACI,mBAAmB,IAAI;QAC1B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,uBAAuB,EAAE,MAAM,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB,EAAE,MAAM,CAAC;KACpC;IASD;;OAEG;IACI,UAAU,IAAI,IAAI;IAMzB;;;;;;;;OAQG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAQvE;;;OAGG;IACI,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAK1D;;;;;;;;OAQG;IACI,6BAA6B,CAChC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,eAAe,GAAE,MAAU,GAC5B,mBAAmB,EAAE,GAAG,IAAI;IAsC/B;;;;;;OAMG;IACI,wBAAwB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG;QAC9D,QAAQ,EAAE,mBAAmB,EAAE,CAAC;QAChC,SAAS,EAAE,mBAAmB,EAAE,CAAC;QACjC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;KACnC;CA6BJ"}
+{"version":3,"file":"ContextCompressionEngine.d.ts","sourceRoot":"","sources":["../../src/mxp/ContextCompressionEngine.ts"],"names":[],"mappings":"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"}