teyyare 0.2.8 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@ Teyyare is the first real integration workload for both projects, proving that a
              replication / transport
                        │
                        ▼
-                      TCP
+                      TCP (Multi-Channel)
                        │
                        ▼
                  Remote Teyyare
@@ -37,7 +37,7 @@ Teyyare is the first real integration workload for both projects, proving that a
                      flush
                        │
                        ▼
-                     Disk
+                     Disk (writev + pre-allocation)
 ```
 
 ---
@@ -52,9 +52,9 @@ Teyyare is the first real integration workload for both projects, proving that a
 
 ---
 
-## Data Flow & Zero-Copy Architecture
+## Architecture & Systems Optimizations
 
-### Sender Hot Path
+### 1. Sender Hot Path
 ```text
 FileHandle.read()
       │
@@ -76,29 +76,46 @@ MutableGeneration
 FrozenGeneration [metaBuf, payloadArena]
       │
       ▼
-Raptiye.submitBatch() (scatter/gather sendv)
+Raptiye.submitBatch() (In-Flight Sliding Window up to 128 MB)
       │
       ▼
-TCP (corked writev)
+Multi-Channel TCP Pool (Zero-Allocation Round-Robin sendv)
 ```
 
-### Receiver Hot Path
+### 2. Receiver Hot Path
 ```text
-TCP
+Multi-Channel TCP
  │
  ▼
-Raptiye (frame decode + CRC32 verification)
+Zero-Copy Pointer Framer (O(1) cursor, no shift(), scratch header reuse)
+ │
+ ▼
+Raptiye (Frame decode + verification)
  │
  ▼
 FrozenGeneration (O(1) zero-copy view via FrozenArenaStore.fromBuffers)
  │
  ▼
-Teyyare chunk consumer
+Chunk Coalescing Engine (Merges contiguous chunk runs)
+ │
+ ▼
+FileHandle.writev(buffers, startOffset) (Direct native scatter-gather writes)
  │
  ▼
-FileHandle.write(payload, 0, length, offset) (Direct random-access write)
+Debounced Asynchronous State Persistence (.teyyare-state)
 ```
 
+### 3. Key Systems Optimizations Implemented
+
+- **Disk Pre-Allocation (`FileHandle.truncate(targetSize)`)**: Zero-fragmentation disk pre-allocation upon receiving `FILE_BEGIN`, eliminating filesystem dynamic block allocation latency during high-speed writes.
+- **Native Scatter-Gather Writes (`writev`)**: Receiver coalesces contiguous chunks arriving in the same generation batch into a single system call via `writev`, reducing write syscalls by ~87.5%.
+- **Debounced Asynchronous State Saving**: `.teyyare-state` persistence is debounced to disk (every 250ms or 32 chunks) and drained cleanly before final file rename, completely eliminating blocking JSON serialization from the hot-path.
+- **In-Flight ACK Pipelining (Sliding Window)**: Supports up to 32 concurrent batches and 128 MB in-flight capacity. Senders stream generations continuously across 4–8 parallel TCP channels without stalling on single-batch ACKs.
+- **Pointer-Based Zero-Copy TCP Framer**: Eliminated $O(N)$ array `shift()` operations and repeated `Buffer.allocUnsafe` calls on the TCP stream reader using an $O(1)$ cursor and amortized array compaction.
+- **Zero-Allocation Channel Selection**: Eliminated `pool.filter` garbage collector churn in `TCPTransport.prototype.sendv` and `send` using an in-place circular lookup.
+- **Dynamic WAN Tuning**: `PULL_REQUEST` carries client-specified `--chunk-size` (e.g. 2 MB) and `--batch-size` (e.g. 16 MB) to saturate high-latency, high-bandwidth WAN connections.
+- **Multi-Channel Out-of-Order Packet Resilience**: Resilient state reconciliation for `TRANSFER_BEGIN`, `FILE_BEGIN`, `FILE_END`, and `TRANSFER_END` packets arriving out-of-order across parallel TCP sockets.
+
 ---
 
 ## CLI Usage
@@ -109,72 +126,95 @@ FileHandle.write(payload, 0, length, offset) (Direct random-access write)
 teyyare serve --port 7421 --dir /destination/folder
 ```
 
-### Send File or Directory
+### Send File or Directory (Push)
 ```bash
-# Single file transfer
-teyyare send ./large-file.bin 127.0.0.1:7421:/tmp/large-file.bin
+# Single file transfer with 4 parallel channels
+teyyare send ./large-file.bin 127.0.0.1:7421:/tmp/large-file.bin -c 4
 
-# Directory transfer with nested files
-teyyare send ./dist server.local:7421:/var/www/app
+# Directory transfer with nested hierarchy
+teyyare send ./dist server.local:7421:/var/www/app -c 4
 ```
 
-### Progress Display
-```text
-Teyyare
+### Pull File or Directory (Download)
+```bash
+# Single file download from remote server with 8 channels and 2MB WAN chunks
+teyyare pull 38.242.216.102:7421:/root/cdn/app.zip ./ -c 8 --chunk-size 2M --batch-size 16M
+
+# Directory pull
+teyyare pull server:7421:/backup/db.tar.zst ./ -c 4
+```
+
+### CLI Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `-c, --channels <n>` | Number of parallel TCP socket channels | `4` (remote), `1` (local) |
+| `--chunk-size <size>` | Chunk size, e.g. `512K`, `1M`, `2M`, `4M` | `2M` (remote), `1M` (local) |
+| `--batch-size <size>` | Generation batch size, e.g. `8M`, `16M` | `8x chunk size` |
+| `--port <port>` | Server port number | `7421` |
+| `--dir <path>` | Root directory for `serve` command | Current directory (`./`) |
+
+---
 
-backup.tar.zst
+## Progress Display
 
-6.42 / 10.00 GB
-64.2%
+```text
+Teyyare [Download]
+
+app.zip
 
-throughput       312 MB/s
-ETA              00:11
+333.54 MB / 333.54 MB
+100.0%
 
-chunks           6574 / 10240
-generation       822
-inflight gen     4
-inflight bytes   31.8 MB
+network speed    324.5 MB/s
+disk speed       1240.2 MB/s
+channels         8
+ETA              --:--
 
-muttafa queue    2
-raptiye RTT      18 ms
-TCP pressure     0
+chunks           167 / 167
+generation       21
+verified CRC32   167
+resume hits      0
 ```
 
 ---
 
-## Benchmarks & Ablation Analysis
+## Test Suite & Softscope Profiling
 
-Run the benchmark suite with:
+### 1. Unit & Integration Tests
+Run all 24 automated tests covering protocol encoding, generation ownership, backpressure, chaos recovery, and multi-channel transfers:
 ```bash
-npm run bench
+npm test
 ```
 
-### 1. Layer Ablation (50 MB transfer)
-| Layer | Description | Throughput (MB/s) | Duration |
-|---|---|---|---|
-| **A** | raw fs -> TCP -> fs | **581.4 MB/s** | 86ms |
-| **B** | fs -> Muttafa -> TCP -> fs | **306.7 MB/s** | 163ms |
-| **C** | fs -> Raptiye -> fs | **85.5 MB/s** | 585ms |
-| **D** | Teyyare (Muttafa + Raptiye + fs) | **38.0 MB/s** | 1320ms |
+### 2. End-to-End (E2E) Test Suite
+Runs 4 comprehensive end-to-end scenarios (Single Upload, Directory Upload, Single Pull, 50% Resumed Transfer):
+```bash
+npm run e2e
+```
 
-### 2. Chunk & Generation Size Matrix (16 MB transfer)
-| Chunk Size | Generation Size | Throughput (MB/s) | Duration (ms) | Peak RSS (MB) |
-|---|---|---|---|---|
-| **64 KiB** | 4 MiB | 39.7 MB/s | 403ms | 660.8 MB |
-| **256 KiB** | 4 MiB | 34.9 MB/s | 458ms | 679.6 MB |
-| **1 MiB** | 4 MiB | **40.1 MB/s** | 399ms | 757.7 MB |
-| **1 MiB** | 8 MiB | **40.0 MB/s** | 400ms | 718.2 MB |
-| **4 MiB** | 16 MiB | 38.6 MB/s | 414ms | 745.3 MB |
+### 3. Softscope Profiling
+Profile CPU bottlenecks, hot call paths, and memory allocations using [`softscope`](https://github.com/litepacks/softscope):
+```bash
+# Markdown summary to stdout
+npm run e2e:md
+
+# Full interactive terminal dashboard (TUI)
+npm run e2e:profile
+
+# Live metrics during execution
+npm run e2e:live
+```
 
 ---
 
-## Test Suite
+## Benchmark & Throughput Results
 
-Run the full test suite with:
-```bash
-npm test
-```
+### End-to-End Suite Summary (`test/e2e/e2e.js`)
 
-Includes:
-- **Unit Tests**: Packed binary chunk metadata protocol, resume state bitmap, generation lifecycle & ownership assertions.
-- **Integration Tests**: 10 MB single file transfer, directory transfer with small-file packing, resume after 50% interruption with bounded retransmission, slow receiver disk write backpressure with bounded RSS plateau, and deterministic chaos recovery.
+| Scenario | Transfer Size | Duration | Throughput | Verification |
+|---|---|---|---|---|
+| **Single File Upload** (4 channels) | 32.0 MB | 121ms | **264.5 MB/s** | SHA-256 Match |
+| **Directory Upload** (Nested tree) | 16.0 MB | 104ms | **153.9 MB/s** | All files verified |
+| **Single File Pull** (4 channels) | 32.0 MB | 89ms | **359.6 MB/s** | SHA-256 Match |
+| **Resumed Transfer** (50% skipped) | 8.0 MB | 49ms | **163.3 MB/s** | 0 retransmitted bytes |

package/bin/teyyare.js

@@ -4,6 +4,28 @@
  * Teyyare CLI
  */
 
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+
+// Option C: Ensure libuv threadpool has sufficient C++ workers for multi-channel I/O.
+// Node.js defaults to only 4 threads. Multi-channel file transfers (writev, read, sync)
+// require at least 16 threads to avoid C++ threadpool contention.
+const RECOMMENDED_POOL_SIZE = Math.min(128, Math.max(16, (os.availableParallelism ? os.availableParallelism() : 8) * 2));
+if (!process.env.TEYYARE_BOOTSTRAPPED && (!process.env.UV_THREADPOOL_SIZE || Number(process.env.UV_THREADPOOL_SIZE) < 16)) {
+  process.env.UV_THREADPOOL_SIZE = String(RECOMMENDED_POOL_SIZE);
+  process.env.TEYYARE_BOOTSTRAPPED = '1';
+  const child = spawn(process.execPath, process.argv.slice(1), {
+    stdio: 'inherit',
+    env: process.env
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+  // Hold parent until child process finishes
+  await new Promise(() => {});
+}
+
 import path from 'node:path';
 import { serve, send, pull } from '../src/index.js';
 
@@ -61,13 +83,13 @@ async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
-  if (!command || command === '--help' || command === '-h') {
+  if (!command || args.includes('--help') || args.includes('-h')) {
     printUsage();
     process.exit(0);
   }
 
   if (command === '--version' || command === '-v' || command === 'version') {
-    console.log('0.2.7');
+    console.log('0.2.8');
     process.exit(0);
   }
 
@@ -203,7 +225,8 @@ Peak RSS:         ${(snap.peakRSS / (1024 * 1024)).toFixed(2)} MB
 `);
     process.exit(0);
   } else if (command === 'status') {
-    console.log('\x1b[1m\x1b[36mTeyyare\x1b[0m v0.2.7 status: ready');
+    const poolSize = Number(process.env.UV_THREADPOOL_SIZE) || 4;
+    console.log(`\x1b[1m\x1b[36mTeyyare\x1b[0m v0.2.9 status: ready (libuv threadpool: ${poolSize})`);
   } else {
     console.error(`Unknown command: ${command}`);
     printUsage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teyyare",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "High-performance resumable file transfer engine and CLI built on muttafa and raptiye",
   "main": "src/index.js",
   "type": "module",
@@ -8,12 +8,12 @@
     "teyyare": "bin/teyyare.js"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
-    "bench": "node bench/run-all.js",
-    "e2e": "node test/e2e/e2e.js",
-    "e2e:profile": "softscope test/e2e/e2e.js",
-    "e2e:live": "softscope --live test/e2e/e2e.js",
-    "e2e:md": "softscope --md test/e2e/e2e.js"
+    "test": "UV_THREADPOOL_SIZE=16 node --test test/**/*.test.js",
+    "bench": "UV_THREADPOOL_SIZE=16 node bench/run-all.js",
+    "e2e": "UV_THREADPOOL_SIZE=16 node test/e2e/e2e.js",
+    "e2e:profile": "UV_THREADPOOL_SIZE=16 softscope test/e2e/e2e.js",
+    "e2e:live": "UV_THREADPOOL_SIZE=16 softscope --live test/e2e/e2e.js",
+    "e2e:md": "UV_THREADPOOL_SIZE=16 softscope --md test/e2e/e2e.js"
   },
   "keywords": [
     "file-transfer",

package/src/cli/progress.js

@@ -17,6 +17,7 @@ export class ProgressReporter {
 
     this.fileName = '';
     this.bytesDone = 0;
+    this.networkBytesDone = 0;
     this.totalBytes = 0;
     this.chunksDone = 0;
     this.totalChunks = 0;
@@ -35,12 +36,18 @@ export class ProgressReporter {
     this._timer = null;
     this._linesRendered = 0;
     this._speedHistory = [];
+    this._netSpeedHistory = [];
+    this._emaNetSpeed = 0;
+    this._emaSpeed = 0;
   }
 
   start() {
     if (!this.enabled) return;
     this.startTime = Date.now();
     this._speedHistory = [{ time: this.startTime, bytes: this.bytesDone }];
+    this._netSpeedHistory = [{ time: this.startTime, bytes: this.networkBytesDone || this.bytesDone }];
+    this._emaNetSpeed = 0;
+    this._emaSpeed = 0;
     this._timer = setInterval(() => this.render(), this.intervalMs);
   }
 
@@ -58,6 +65,7 @@ export class ProgressReporter {
   update(state = {}) {
     if (state.fileName !== undefined) this.fileName = state.fileName;
     if (state.bytesDone !== undefined) this.bytesDone = state.bytesDone;
+    if (state.networkBytesDone !== undefined) this.networkBytesDone = state.networkBytesDone;
     if (state.totalBytes !== undefined) this.totalBytes = state.totalBytes;
     if (state.chunksDone !== undefined) this.chunksDone = state.chunksDone;
     if (state.totalChunks !== undefined && state.totalChunks > 0) this.totalChunks = state.totalChunks;
@@ -91,7 +99,7 @@ export class ProgressReporter {
     const now = Date.now();
     const elapsedSec = Math.max(0.001, (now - this.startTime) / 1000);
 
-    // Track sliding window (last 2 seconds) for smooth, responsive current speed
+    // 1. Committed bytes speed history (disk commit rate & upload throughput)
     this._speedHistory.push({ time: now, bytes: this.bytesDone });
     while (this._speedHistory.length > 2 && (now - this._speedHistory[0].time) > 2000) {
       this._speedHistory.shift();
@@ -101,15 +109,45 @@ export class ProgressReporter {
     const windowBytes = Math.max(0, this.bytesDone - oldest.bytes);
 
     const avgSpeedMBs = (this.bytesDone / (1024 * 1024)) / elapsedSec;
-    const currentSpeedMBs = windowSec >= 0.4 ? (windowBytes / (1024 * 1024)) / windowSec : avgSpeedMBs;
-    const effectiveSpeed = currentSpeedMBs > 0.05 ? currentSpeedMBs : avgSpeedMBs;
+    const currentSpeedMBs = windowSec >= 0.3 ? (windowBytes / (1024 * 1024)) / windowSec : avgSpeedMBs;
+    const rawSpeed = currentSpeedMBs > 0.05 ? currentSpeedMBs : avgSpeedMBs;
+
+    // Apply Exponential Moving Average (EMA, alpha = 0.20) to filter micro-pauses and jitter
+    if (!this._emaSpeed || this._emaSpeed === 0) {
+      this._emaSpeed = rawSpeed;
+    } else {
+      this._emaSpeed = (0.20 * rawSpeed) + (0.80 * this._emaSpeed);
+    }
+    const effectiveSpeed = this._emaSpeed;
+
+    // 2. Real wire network bytes speed history (streaming sockets)
+    const netBytes = this.networkBytesDone > 0 ? this.networkBytesDone : this.bytesDone;
+    this._netSpeedHistory.push({ time: now, bytes: netBytes });
+    while (this._netSpeedHistory.length > 2 && (now - this._netSpeedHistory[0].time) > 2000) {
+      this._netSpeedHistory.shift();
+    }
+    const netOldest = this._netSpeedHistory[0];
+    const netWindowSec = Math.max(0.001, (now - netOldest.time) / 1000);
+    const netWindowBytes = Math.max(0, netBytes - netOldest.bytes);
+    const netAvgSpeedMBs = (netBytes / (1024 * 1024)) / elapsedSec;
+    const netInstantSpeedMBs = netWindowSec >= 0.3 ? (netWindowBytes / (1024 * 1024)) / netWindowSec : netAvgSpeedMBs;
+    const netRawSpeed = netInstantSpeedMBs > 0.05 ? netInstantSpeedMBs : netAvgSpeedMBs;
+
+    // Smooth network wire rate with Exponential Moving Average (EMA, alpha = 0.20)
+    if (!this._emaNetSpeed || this._emaNetSpeed === 0) {
+      this._emaNetSpeed = netRawSpeed;
+    } else {
+      this._emaNetSpeed = (0.20 * netRawSpeed) + (0.80 * this._emaNetSpeed);
+    }
+    const networkSpeedMBs = this._emaNetSpeed;
 
     const percent = this.totalBytes > 0 ? ((this.bytesDone / this.totalBytes) * 100).toFixed(1) : '0.0';
 
+    const activeSpeed = (this.role === 'receiver' && networkSpeedMBs > 0) ? networkSpeedMBs : effectiveSpeed;
     let etaStr = '--:--';
-    if (effectiveSpeed > 0 && this.totalBytes > this.bytesDone) {
+    if (activeSpeed > 0 && this.totalBytes > this.bytesDone) {
       const remainingBytes = this.totalBytes - this.bytesDone;
-      const remainingSec = Math.round(remainingBytes / (effectiveSpeed * 1024 * 1024));
+      const remainingSec = Math.round(remainingBytes / (activeSpeed * 1024 * 1024));
       const mm = String(Math.floor(remainingSec / 60)).padStart(2, '0');
       const ss = String(remainingSec % 60).padStart(2, '0');
       etaStr = `${mm}:${ss}`;
@@ -117,7 +155,7 @@ export class ProgressReporter {
 
     let lines;
     if (this.role === 'receiver') {
-      const diskStr = this.diskSpeedMBs > 0 ? `${this.diskSpeedMBs.toFixed(1)} MB/s` : `${effectiveSpeed.toFixed(1)} MB/s`;
+      const diskStr = `${effectiveSpeed.toFixed(1)} MB/s`;
       lines = [
         '\x1b[1m\x1b[36mTeyyare [Download]\x1b[0m',
         '',
@@ -126,7 +164,7 @@ export class ProgressReporter {
         `${this.formatBytes(this.bytesDone)} / ${this.formatBytes(this.totalBytes)}`,
         `\x1b[32m${percent}%\x1b[0m`,
         '',
-        `network speed    \x1b[1m${effectiveSpeed.toFixed(1)} MB/s\x1b[0m`,
+        `network speed    \x1b[1m${networkSpeedMBs.toFixed(1)} MB/s\x1b[0m`,
         `disk speed       \x1b[1m${diskStr}\x1b[0m`,
         `channels         ${this.channels}`,
         `ETA              ${etaStr}`,
@@ -167,7 +205,8 @@ export class ProgressReporter {
       process.stdout.write(lines.join('\n') + '\n');
       this._linesRendered = lines.length;
     } else {
-      process.stdout.write(`[Teyyare] ${percent}% | ${effectiveSpeed.toFixed(1)} MB/s | Chunks: ${this.chunksDone}/${this.totalChunks || this.chunksDone} | ETA: ${etaStr}\n`);
+      const reportSpeed = (this.role === 'receiver' && networkSpeedMBs > 0) ? networkSpeedMBs : effectiveSpeed;
+      process.stdout.write(`[Teyyare] ${percent}% | ${reportSpeed.toFixed(1)} MB/s | Chunks: ${this.chunksDone}/${this.totalChunks || this.chunksDone} | ETA: ${etaStr}\n`);
     }
   }
 }

package/src/index.js

@@ -51,6 +51,10 @@ TCPTransport.prototype._attachSocketReader = function(socket) {
   const headerScratch = Buffer.allocUnsafe(HEADER_SIZE);
 
   socket.on('data', (chunk) => {
+    this.bytesReceived = (this.bytesReceived || 0) + chunk.length;
+    if (this.onDataBytes) {
+      this.onDataBytes(chunk.length);
+    }
     chunks.push(chunk);
     bufferedLength += chunk.length;
 
@@ -180,11 +184,19 @@ TCPTransport.prototype._attachSocketReader = function(socket) {
     }
   });
 
+  socket.on('end', () => {
+    socket.destroy();
+  });
+
   socket.on('error', () => {
     socket.destroy();
   });
 };
 
+function isSocketReady(s) {
+  return Boolean(s && !s.destroyed && s.writable && !s.readableEnded && !s.writableEnded && s.readyState === 'open');
+}
+
 TCPTransport.prototype.connectChannels = async function(peer, channelCount = 4) {
   if (channelCount <= 1) return;
   const addr = this.peerAddresses.get(peer);
@@ -193,7 +205,7 @@ TCPTransport.prototype.connectChannels = async function(peer, channelCount = 4)
   }
 
   const pool = this._getPeerPool(peer);
-  const activeSockets = pool.filter((s) => !s.destroyed && s.writable);
+  const activeSockets = pool.filter(isSocketReady);
   const needed = channelCount - activeSockets.length;
   if (needed <= 0) return;
 
@@ -243,30 +255,75 @@ TCPTransport.prototype.connectChannels = async function(peer, channelCount = 4)
   await new Promise((r) => setTimeout(r, 20));
 };
 
+const origGetOrCreate = TCPTransport.prototype._getOrCreateSocket;
+TCPTransport.prototype._getOrCreateSocket = function(peer) {
+  if (!this.started) {
+    return Promise.reject(new Error(`[TCPTransport ${this.id}] Cannot connect: transport closed`));
+  }
+  return origGetOrCreate.call(this, peer).then((socket) => {
+    const pool = this._getPeerPool(peer);
+    if (!pool.includes(socket)) {
+      pool.push(socket);
+    }
+    return socket;
+  });
+};
+
 TCPTransport.prototype.sendv = function(peer, buffers) {
+  if (!this.started) return;
   if (!this._channelIndex) this._channelIndex = new Map();
 
   const pool = this._peerSocketPool ? this._peerSocketPool.get(peer) : null;
+  if (pool && pool.length > 0) {
+    // Purge dead sockets from pool
+    for (let i = pool.length - 1; i >= 0; i--) {
+      if (!isSocketReady(pool[i])) {
+        pool.splice(i, 1);
+      }
+    }
+  }
+
   if (pool && pool.length > 0) {
     let idx = this._channelIndex.get(peer) || 0;
     const poolLen = pool.length;
+    let bestSocket = null;
+    let bestWritableLength = Infinity;
+    let bestIndex = idx;
+
     for (let attempts = 0; attempts < poolLen; attempts++) {
-      const s = pool[(idx + attempts) % poolLen];
-      if (!s.destroyed && s.writable) {
-        this._channelIndex.set(peer, idx + attempts + 1);
-        s.cork();
-        for (let i = 0; i < buffers.length; i++) {
-          s.write(buffers[i]);
+      const candidateIdx = (idx + attempts) % poolLen;
+      const s = pool[candidateIdx];
+      if (isSocketReady(s)) {
+        const qLen = s.writableLength || 0;
+        // Priority 1: Pick idle/drained socket immediately
+        if (qLen === 0) {
+          bestSocket = s;
+          bestIndex = candidateIdx;
+          break;
         }
-        s.uncork();
-        return;
+        // Priority 2: Track least-buffered socket to prevent head-of-line convoy stalls
+        if (qLen < bestWritableLength) {
+          bestWritableLength = qLen;
+          bestSocket = s;
+          bestIndex = candidateIdx;
+        }
+      }
+    }
+
+    if (bestSocket) {
+      this._channelIndex.set(peer, (bestIndex + 1) % poolLen);
+      bestSocket.cork();
+      for (let i = 0; i < buffers.length; i++) {
+        bestSocket.write(buffers[i]);
       }
+      bestSocket.uncork();
+      return;
     }
   }
 
   this._getOrCreateSocket(peer)
     .then((socket) => {
-      if (!socket.destroyed && socket.writable) {
+      if (isSocketReady(socket)) {
         socket.cork();
         for (let i = 0; i < buffers.length; i++) {
           socket.write(buffers[i]);
@@ -278,25 +335,56 @@ TCPTransport.prototype.sendv = function(peer, buffers) {
 };
 
 TCPTransport.prototype.send = function(peer, buffer) {
+  if (!this.started) return;
   if (!this._channelIndex) this._channelIndex = new Map();
 
   const pool = this._peerSocketPool ? this._peerSocketPool.get(peer) : null;
+  if (pool && pool.length > 0) {
+    // Purge dead sockets from pool
+    for (let i = pool.length - 1; i >= 0; i--) {
+      if (!isSocketReady(pool[i])) {
+        pool.splice(i, 1);
+      }
+    }
+  }
+
   if (pool && pool.length > 0) {
     let idx = this._channelIndex.get(peer) || 0;
     const poolLen = pool.length;
+    let bestSocket = null;
+    let bestWritableLength = Infinity;
+    let bestIndex = idx;
+
     for (let attempts = 0; attempts < poolLen; attempts++) {
-      const s = pool[(idx + attempts) % poolLen];
-      if (!s.destroyed && s.writable) {
-        this._channelIndex.set(peer, idx + attempts + 1);
-        s.write(buffer);
-        return;
+      const candidateIdx = (idx + attempts) % poolLen;
+      const s = pool[candidateIdx];
+      if (isSocketReady(s)) {
+        const qLen = s.writableLength || 0;
+        // Priority 1: Pick idle/drained socket immediately
+        if (qLen === 0) {
+          bestSocket = s;
+          bestIndex = candidateIdx;
+          break;
+        }
+        // Priority 2: Track least-buffered socket to prevent head-of-line convoy stalls
+        if (qLen < bestWritableLength) {
+          bestWritableLength = qLen;
+          bestSocket = s;
+          bestIndex = candidateIdx;
+        }
       }
     }
+
+    if (bestSocket) {
+      this._channelIndex.set(peer, (bestIndex + 1) % poolLen);
+      bestSocket.write(buffer);
+      return;
+    }
   }
 
   this._getOrCreateSocket(peer)
     .then((socket) => {
-      if (!socket.destroyed && socket.writable) {
+      if (isSocketReady(socket)) {
         socket.write(buffer);
       }
     })
@@ -305,6 +393,7 @@ TCPTransport.prototype.send = function(peer, buffer) {
 
 const origClose = TCPTransport.prototype.close;
 TCPTransport.prototype.close = async function() {
+  this.started = false;
   if (this._peerSocketPool) {
     for (const pool of this._peerSocketPool.values()) {
       for (const socket of pool) {
@@ -503,6 +592,7 @@ export async function serve({
       await s.abort();
     }
     replication.reset();
+    receiver.reset();
   };
 
   replication.onBatch(async (msg) => {
@@ -551,9 +641,18 @@ export async function serve({
         }));
       }
 
+      // Detect peer channels for optimal pipeline scaling
+      const pool = transport._peerSocketPool ? transport._peerSocketPool.get(entries[0].sourceNode || 1) : null;
+      const detectedChannels = pool && pool.length > 0 ? pool.length : 1;
+      const effectiveBatchBytes = maxBytes || ((chunkSize || 1024 * 1024) * (maxEntries || 8));
+
+      // Dynamically scale replication in-flight window for remote pull client
+      replication.maxInflightBytes = Math.max(128 * 1024 * 1024, detectedChannels * effectiveBatchBytes * 3);
+      replication.maxInflightBatches = Math.max(32, detectedChannels * 4);
+
       const senderOpts = {
-        maxImmutableBuffers: 32,
-        maxConcurrentFlushes: 32
+        maxImmutableBuffers: Math.max(32, detectedChannels * 4),
+        maxConcurrentFlushes: Math.max(32, detectedChannels * 4)
       };
       if (chunkSize) senderOpts.chunkSize = chunkSize;
       if (maxEntries) senderOpts.maxEntries = maxEntries;
@@ -647,20 +746,46 @@ export async function send({
     await transport.connectChannels(2, channels);
   }
 
+  const isRemote = host !== '127.0.0.1' && host !== 'localhost';
+  const defaultChunkSize = isRemote ? 2 * 1024 * 1024 : 1024 * 1024;
+  const defaultMaxEntries = 8;
+  const defaultMaxBytes = defaultChunkSize * defaultMaxEntries;
+
+  const effectiveChunkSize = pipelineOptions.chunkSize || defaultChunkSize;
+  const effectiveMaxEntries = pipelineOptions.maxEntries || defaultMaxEntries;
+  const effectiveMaxBytes = pipelineOptions.maxBytes || defaultMaxBytes;
+
+  const scaledInflightBytes = pipelineOptions.maxInflightBytes || Math.max(128 * 1024 * 1024, channels * effectiveMaxBytes * 3);
+  const scaledInflightBatches = pipelineOptions.maxInflightBatches || Math.max(32, channels * 4);
+
   const replication = new ReplicationPipeline({
     transport,
     localNode: 1,
     remoteNode: 2,
-    maxInflightBatches: pipelineOptions.maxInflightBatches || 32,
-    maxInflightBytes: pipelineOptions.maxInflightBytes || 128 * 1024 * 1024
+    maxInflightBatches: scaledInflightBatches,
+    maxInflightBytes: scaledInflightBytes
   });
 
   const manifest = await TransferManifest.build(sourcePath);
 
+  const effectiveSenderOptions = {
+    chunkSize: effectiveChunkSize,
+    maxEntries: effectiveMaxEntries,
+    maxBytes: effectiveMaxBytes,
+    ...pipelineOptions
+  };
+
+  if (!effectiveSenderOptions.maxImmutableBuffers && channels > 1) {
+    effectiveSenderOptions.maxImmutableBuffers = Math.max(32, channels * 4);
+  }
+  if (!effectiveSenderOptions.maxConcurrentFlushes && channels > 1) {
+    effectiveSenderOptions.maxConcurrentFlushes = effectiveSenderOptions.maxImmutableBuffers;
+  }
+
   const sender = new SenderPipeline({
     replication,
     manifest,
-    options: pipelineOptions,
+    options: effectiveSenderOptions,
     metrics,
     progress,
     knownResumeState
@@ -669,6 +794,7 @@ export async function send({
   try {
     await sender.transfer();
   } finally {
+    if (progress) progress.stop();
     await sender.abort();
     metrics.stop();
     await transport.close();
@@ -727,12 +853,15 @@ export async function pull({
     await transport.connectChannels(2, channels);
   }
 
+  const scaledInflightBytes = pipelineOptions.maxInflightBytes || Math.max(128 * 1024 * 1024, channels * effectiveMaxBytes * 3);
+  const scaledInflightBatches = pipelineOptions.maxInflightBatches || Math.max(32, channels * 4);
+
   const replication = new ReplicationPipeline({
     transport,
     localNode: 1,
     remoteNode: 2,
-    maxInflightBatches: pipelineOptions.maxInflightBatches || 32,
-    maxInflightBytes: pipelineOptions.maxInflightBytes || 128 * 1024 * 1024
+    maxInflightBatches: scaledInflightBatches,
+    maxInflightBytes: scaledInflightBytes
   });
 
   const receiver = new ReceiverPipeline({

package/src/metrics/collector.js

@@ -83,6 +83,7 @@ export class MetricsCollector {
       currentRSS: mem.rss,
       heapUsed: mem.heapUsed,
       external: mem.external,
+      threadpoolSize: Number(process.env.UV_THREADPOOL_SIZE) || 4,
 
       // Teyyare
       fileBytesRead: this.fileBytesRead,

package/src/receiver/pipeline.js

@@ -52,6 +52,18 @@ export class ReceiverPipeline {
     this._batchQueue = [];
     this._processingQueue = false;
 
+    this.networkBytesReceived = 0;
+    if (this.replication && this.replication.transport) {
+      const prevOnDataBytes = this.replication.transport.onDataBytes;
+      this.replication.transport.onDataBytes = (bytes) => {
+        if (prevOnDataBytes) prevOnDataBytes(bytes);
+        this.networkBytesReceived += bytes;
+        if (this.progress) {
+          this.progress.update({ networkBytesDone: this.networkBytesReceived });
+        }
+      };
+    }
+
     // Hook up Raptiye batch handler if autoHookBatch is true
     if (this.replication && autoHookBatch) {
       this.replication.onBatch(async (msg) => {
@@ -100,6 +112,24 @@ export class ReceiverPipeline {
     }
   }
 
+  reset() {
+    this.currentTransferId = null;
+    this.transferFinished = false;
+    this.transferError = null;
+    this._pendingTransferEnd = false;
+    this.expectedFileCount = null;
+    this._completedFileCount = 0;
+    this.completedFiles.clear();
+    this.activeFiles.clear();
+    this._pendingChunks.clear();
+    this._pendingFileEnds.clear();
+    this._batchQueue = [];
+    this._processingQueue = false;
+    this.networkBytesReceived = 0;
+    this._finishResolvers = [];
+    this._errorRejecters = [];
+  }
+
   async waitForCompletion() {
     if (this.transferError) throw this.transferError;
     if (this.transferFinished) return;
@@ -421,7 +451,7 @@ export class ReceiverPipeline {
     }
 
     // 2. Sort by offset to form maximal contiguous runs
-    toWrite.sort((a, b) => Number(a.meta.offset - b.meta.offset));
+    toWrite.sort((a, b) => (a.meta.offset < b.meta.offset ? -1 : (a.meta.offset > b.meta.offset ? 1 : 0)));
 
     let currentRun = [toWrite[0]];
     let currentStartOffset = Number(toWrite[0].meta.offset);
@@ -484,9 +514,6 @@ export class ReceiverPipeline {
 
     // 3. Update progress reporter
     if (this.progress) {
-      const diskTimeSec = Math.max(0.001, (this.metrics ? this.metrics.diskWriteTimeMs : 1) / 1000);
-      const writtenMB = (this.metrics ? this.metrics.fileBytesWritten : 0) / (1024 * 1024);
-      const diskMBs = Number((writtenMB / diskTimeSec).toFixed(1));
       for (const item of toWrite) {
         file.maxChunkSize = Math.max(file.maxChunkSize || 0, item.meta.length);
       }
@@ -496,8 +523,7 @@ export class ReceiverPipeline {
         bytesDone: this.metrics ? this.metrics.fileBytesWritten : 0,
         chunksDone: this.metrics ? this.metrics.chunksVerified : 0,
         totalChunks: realTotalChunks > 0 ? realTotalChunks : undefined,
-        resumeHits: this.metrics ? this.metrics.resumeHits : 0,
-        diskSpeedMBs: diskMBs
+        resumeHits: this.metrics ? this.metrics.resumeHits : 0
       });
     }
 

package/src/sender/pipeline.js

@@ -20,6 +20,25 @@ import {
 import { extractGenerationBuffers } from '../core/generation.js';
 import { FileResumeState } from '../resume/state.js';
 
+/**
+ * Reusable bump allocator that returns its ArrayBuffer to a pool upon reset/release.
+ */
+class PooledBumpAllocator extends BumpAllocator {
+  constructor(capacity, pool = null) {
+    super(capacity);
+    this._pool = pool;
+  }
+
+  reset() {
+    super.reset();
+    if (this._pool && this._pool.length < 16 && !this._pool.includes(this)) {
+      this._pool.push(this);
+    }
+  }
+}
+
+const defaultAllocatorPool = [];
+
 class RaptiyeSink extends Sink {
   /**
    * @param {import('raptiye').ReplicationPipeline} replication
@@ -109,6 +128,8 @@ export class SenderPipeline {
     this.metrics = metrics;
     this.progress = progress;
     this.knownResumeState = knownResumeState;
+    this._allocatorPool = options.allocatorPool || defaultAllocatorPool;
+    this._readScratch = null;
 
     this.transferId = crypto.randomUUID();
 
@@ -119,10 +140,22 @@ export class SenderPipeline {
     this.sink = new RaptiyeSink(this.replication, this.metrics, this.progress);
     this.engine = new MutationEngine({
       sink: this.sink,
-      createStore: () => new ArenaStore({
-        chunkSize: Math.max(64, this.maxEntries),
-        allocator: new BumpAllocator(arenaCapacity)
-      }),
+      createStore: () => {
+        let allocator = null;
+        if (this._allocatorPool && this._allocatorPool.length > 0) {
+          const idx = this._allocatorPool.findIndex((a) => a.capacity >= arenaCapacity);
+          if (idx !== -1) {
+            allocator = this._allocatorPool.splice(idx, 1)[0];
+          }
+        }
+        if (!allocator) {
+          allocator = new PooledBumpAllocator(arenaCapacity, this._allocatorPool);
+        }
+        return new ArenaStore({
+          chunkSize: Math.max(64, this.maxEntries),
+          allocator
+        });
+      },
       maxEntries: this.maxEntries,
       maxBytes: this.maxBytes,
       maxImmutableBuffers: this.maxImmutableBuffers,
@@ -148,6 +181,7 @@ export class SenderPipeline {
 
   async abort() {
     this.aborted = true;
+    this._readScratch = null;
     for (const waiter of this._abortWaiters) {
       waiter();
     }
@@ -264,8 +298,14 @@ export class SenderPipeline {
               continue;
             }
 
-            // Direct read into fresh chunk buffer
-            const chunkBuf = new Uint8Array(chunkLen);
+            // Direct read into reusable chunk buffer (Muttafa copies synchronously into its arena on append)
+            if (!this._readScratch || this._readScratch.byteLength < chunkLen) {
+              this._readScratch = new Uint8Array(Math.max(this.chunkSize, chunkLen));
+            }
+            const chunkBuf = (chunkLen === this._readScratch.byteLength)
+              ? this._readScratch
+              : this._readScratch.subarray(0, chunkLen);
+
             const readStart = Date.now();
             await handle.read(chunkBuf, 0, chunkLen, Number(offset));
             if (this.metrics) {
@@ -340,5 +380,6 @@ export class SenderPipeline {
       });
       this.progress.stop();
     }
+    this._readScratch = null;
   }
 }