@twinsearth/w2m-dsh-plugin 2.0.8 → 2.0.9

package/src/agent/p2p.mjs

@@ -114,6 +114,42 @@ export const DEFAULT_WINDOW = 32;
 export const DEFAULT_RTO_MS = 300;
 export const MAX_RTO_MS = 3000;
 
+/**
+ * RFC 6298 RTT estimator. The old channel used a constant 300 ms RTO, which is
+ * wrong on both a LAN (too slow) and a lossy WAN (too fast). This keeps SRTT and
+ * RTTVAR and clamps the result; callers still apply per-attempt exponential
+ * backoff on top.
+ */
+export class RttEstimator {
+  constructor({ initialRtoMs = DEFAULT_RTO_MS, minRtoMs = 100, maxRtoMs = MAX_RTO_MS } = {}) {
+    this.srtt = null;
+    this.rttvar = null;
+    this.minRtoMs = minRtoMs;
+    this.maxRtoMs = maxRtoMs;
+    this.rtoMs = Math.min(maxRtoMs, Math.max(minRtoMs, initialRtoMs));
+  }
+
+  sample(rttMs) {
+    if (!Number.isFinite(rttMs) || rttMs < 0) return this.rtoMs;
+    if (this.srtt === null) {
+      this.srtt = rttMs;
+      this.rttvar = rttMs / 2;
+    } else {
+      this.rttvar = 0.75 * this.rttvar + 0.25 * Math.abs(this.srtt - rttMs);
+      this.srtt = 0.875 * this.srtt + 0.125 * rttMs;
+    }
+    this.rtoMs = Math.min(this.maxRtoMs, Math.max(this.minRtoMs, this.srtt + 4 * this.rttvar));
+    return this.rtoMs;
+  }
+
+  reset() {
+    this.srtt = null;
+    this.rttvar = null;
+    this.rtoMs = Math.min(this.maxRtoMs, Math.max(this.minRtoMs, DEFAULT_RTO_MS));
+  }
+}
+
+
 /** Retransmits per fragment before the message is declared undeliverable. */
 export const DEFAULT_MAX_ATTEMPTS = 8;
 
@@ -985,9 +1021,14 @@ export class P2PChannel extends EventEmitter {
     this.session = options.session;
     this.tuning = {
       window: options.tuning?.window ?? DEFAULT_WINDOW,
+      maxWindow: options.tuning?.maxWindow ?? 256,
       rtoMs: options.tuning?.rtoMs ?? DEFAULT_RTO_MS,
       maxAttempts: options.tuning?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
     };
+    /** Adaptive send window: starts at the tuning value, grows on completed messages. */
+    this.window = this.tuning.window;
+    /** RTT/RTO measured from ACK arrival, instead of the fixed 300 ms default. */
+    this.rtt = new RttEstimator({ initialRtoMs: this.tuning.rtoMs, maxRtoMs: MAX_RTO_MS });
 
     const crypto = options.crypto ?? null;
     /** @type {CryptoSession|null} */
@@ -1150,11 +1191,25 @@ export class P2PChannel extends EventEmitter {
     const entry = this.outgoing.get(messageId);
     if (!entry) return;
     entry.acked.add(index);
+    entry.inFlight.delete(index);
+    // Karn: a fragment that was retransmitted has an ambiguous RTT, so only the
+    // first transmission is sampled.
+    if (entry.sentAt.has(index) && !entry.retransmitted.has(index)) {
+      this.rtt.sample(Date.now() - entry.sentAt.get(index));
+      entry.sentAt.delete(index);
+    }
     if (entry.acked.size === entry.fragments.length) {
       this.outgoing.delete(messageId);
       clearTimeout(entry.timer);
+      // A completed message is the only honest RTT-free signal that the path holds more
+      // than the previous window: grow conservatively, and halve on a retransmit timeout.
+      this.window = Math.min(this.tuning.maxWindow, this.window + Math.max(1, Math.floor(this.window / 8)));
       entry.resolve();
+      return;
     }
+    // ACK-driven progress: the next window leaves as soon as a slot frees, instead of
+    // waiting for the RTO timer (the 0.12 MiB/s ceiling).
+    if (entry.pump !== null) entry.pump();
   }
 
   /**
@@ -1207,6 +1262,10 @@ export class P2PChannel extends EventEmitter {
       const entry = {
         fragments,
         acked: new Set(),
+        inFlight: new Set(),
+        sentAt: new Map(),
+        retransmitted: new Set(),
+        pump: null,
         resolve,
         reject,
         attempts: new Map(),
@@ -1215,45 +1274,73 @@ export class P2PChannel extends EventEmitter {
 
       const pump = () => {
         if (this.closed) return;
-        const pending = [];
-        for (let i = 0; i < fragments.length; i += 1) {
-          if (entry.acked.has(i)) continue;
-          pending.push(i);
-          if (pending.length >= this.tuning.window) break;
-        }
-        if (pending.length === 0) return;
-
-        for (const index of pending) {
-          const attempt = (entry.attempts.get(index) ?? 0) + 1;
-          entry.attempts.set(index, attempt);
+        // Send only what the current window has room for. inFlight is the honest
+        // count of fragments the peer has not acknowledged yet; re-sending those
+        // is the timer's job, not pump's.
+        let budget = Math.max(1, this.window - entry.inFlight.size);
+        for (let i = 0; i < fragments.length && budget > 0; i += 1) {
+          if (entry.acked.has(i) || entry.inFlight.has(i)) continue;
+          const attempt = (entry.attempts.get(i) ?? 0) + 1;
+          entry.attempts.set(i, attempt);
           if (attempt > this.tuning.maxAttempts) {
             this.outgoing.delete(messageId);
+            clearTimeout(entry.timer);
+            this.window = Math.max(8, Math.floor(this.window / 2));
             reject(
               new Error(
-                `P2P_FRAGMENT_UNACKED: fragment ${index}/${fragments.length} of message ${messageId} ` +
+                `P2P_FRAGMENT_UNACKED: fragment ${i}/${fragments.length} of message ${messageId} ` +
                   `after ${this.tuning.maxAttempts} attempts`,
               ),
             );
             return;
           }
-          const body = Buffer.alloc(12 + fragments[index].length);
+          entry.inFlight.add(i);
+          if (!entry.sentAt.has(i)) entry.sentAt.set(i, Date.now());
+          budget -= 1;
+          const body = Buffer.alloc(12 + fragments[i].length);
           body.writeUInt32BE(messageId, 0);
-          body.writeUInt32BE(index, 4);
+          body.writeUInt32BE(i, 4);
           body.writeUInt32BE(fragments.length, 8);
-          fragments[index].copy(body, 12);
+          fragments[i].copy(body, 12);
           this.sendFrame(KIND.DATA, body);
         }
 
-        const worst = Math.max(...pending.map((i) => entry.attempts.get(i) ?? 1));
-        const delay = Math.min(this.tuning.rtoMs * 2 ** (worst - 1), MAX_RTO_MS);
+        if (entry.inFlight.size === 0) return;
+        const worst = Math.max(...[...entry.inFlight].map((i) => entry.attempts.get(i) ?? 1));
+        const delay = Math.min(this.rtt.rtoMs * 2 ** (worst - 1), MAX_RTO_MS);
         // One timer per message, not one per channel: a shared field means a second
         // concurrent send silently cancels the first one's retransmission schedule.
         clearTimeout(entry.timer);
         entry.timer = setTimeout(() => {
-          if (this.outgoing.has(messageId)) pump();
+          if (!this.outgoing.has(messageId)) return;
+          // Retransmit the fragments that are still unacknowledged, then schedule again.
+          for (const i of entry.inFlight) {
+            entry.retransmitted.add(i);
+            const attempt = (entry.attempts.get(i) ?? 0) + 1;
+            entry.attempts.set(i, attempt);
+            if (attempt > this.tuning.maxAttempts) {
+              this.outgoing.delete(messageId);
+              this.window = Math.max(8, Math.floor(this.window / 2));
+              reject(
+                new Error(
+                  `P2P_FRAGMENT_UNACKED: fragment ${i}/${fragments.length} of message ${messageId} ` +
+                    `after ${this.tuning.maxAttempts} attempts`,
+                ),
+              );
+              return;
+            }
+            const body = Buffer.alloc(12 + fragments[i].length);
+            body.writeUInt32BE(messageId, 0);
+            body.writeUInt32BE(i, 4);
+            body.writeUInt32BE(fragments.length, 8);
+            fragments[i].copy(body, 12);
+            this.sendFrame(KIND.DATA, body);
+          }
+          pump();
         }, delay);
         entry.timer.unref?.();
       };
+      entry.pump = pump;
 
       pump();
     });

package/src/agent/path-scheduler.mjs

@@ -0,0 +1,106 @@
+/**
+ * PathScheduler: score candidate paths, and switch only on sustained evidence.
+ *
+ * This is deliberately pure policy: no sockets, no timers beyond the overlap
+ * deadline it reports. The caller opens the challenger, keeps the old path for
+ * `keepUntilMs` (make-before-break), then closes it.
+ */
+
+export const PATH_KIND = Object.freeze({
+  IROH_DIRECT: 'iroh-direct',
+  UDP_DIRECT: 'udp-direct',
+  LIBP2P: 'libp2p',
+  IROH_RELAY: 'iroh-relay',
+  CONTROL_PLANE: 'control-plane',
+});
+
+/** Higher is better. The type weight dominates; latency and loss refine it. */
+export const PATH_WEIGHT = Object.freeze({
+  [PATH_KIND.IROH_DIRECT]: 5,
+  [PATH_KIND.UDP_DIRECT]: 4,
+  [PATH_KIND.LIBP2P]: 3,
+  [PATH_KIND.IROH_RELAY]: 2,
+  [PATH_KIND.CONTROL_PLANE]: 1,
+});
+
+export const SCHEDULER_CODE = Object.freeze({
+  OK: 'PATH_OK',
+  NOT_ENCRYPTED: 'PATH_NOT_ENCRYPTED',
+  NO_CANDIDATES: 'PATH_NO_CANDIDATES',
+  SWITCH_PENDING: 'PATH_SWITCH_PENDING',
+  ALL_FAILED: 'ALL_TRANSPORTS_FAILED',
+});
+
+/**
+ * @param {{kind: string, encrypted: boolean, firstFrameRttMs: number, lossRate: number}} path
+ * @returns {number} score; encrypted paths outrank plaintext by a wide margin
+ */
+export function scorePath({ kind, encrypted, firstFrameRttMs = 0, lossRate = 0 }) {
+  const weight = PATH_WEIGHT[kind] ?? 0;
+  if (encrypted !== true) return -1;
+  if (!Number.isFinite(weight) || weight <= 0) return -1;
+  const rtt = Number.isFinite(firstFrameRttMs) ? Math.max(0, firstFrameRttMs) : 1000;
+  const loss = Number.isFinite(lossRate) ? Math.min(1, Math.max(0, lossRate)) : 1;
+  return weight * 1000 - rtt - loss * 2000;
+}
+
+/**
+ * A path switch is allowed only when:
+ *   - the challenger is encrypted;
+ *   - two consecutive samples beat the current path by > 20%;
+ *   - the challenger's kind is at least as preferred as the current one
+ *     (no switching down to a relay while a direct path is healthy).
+ */
+export class PathScheduler {
+  constructor({ overlapMs = 5000, improvement = 1.2, requiredSamples = 2, now = Date.now } = {}) {
+    this.overlapMs = overlapMs;
+    this.improvement = improvement;
+    this.requiredSamples = requiredSamples;
+    this.now = now;
+    this.current = null;
+    this.challenger = null;
+    this.leading = 0;
+    this.lastPlan = null;
+  }
+
+  setCurrent(path) {
+    this.current = path;
+    this.challenger = null;
+    this.leading = 0;
+    return this.current;
+  }
+
+  /** Record one challenger sample; returns a switch plan or null. */
+  observe(path) {
+    if (path?.encrypted !== true) return null;
+    const challengerScore = scorePath(path);
+    const currentScore = this.current === null ? Number.NEGATIVE_INFINITY : scorePath(this.current);
+    if (currentScore === Number.NEGATIVE_INFINITY) {
+      this.current = path;
+      return { switch: false, reason: 'first-path', path };
+    }
+    const sameChallenger = this.challenger !== null && this.challenger.id === path.id;
+    if (challengerScore > currentScore * this.improvement) {
+      this.challenger = path;
+      this.leading = sameChallenger ? this.leading + 1 : 1;
+      if (this.leading < this.requiredSamples) return null;
+      if ((PATH_WEIGHT[path.kind] ?? 0) < (PATH_WEIGHT[this.current.kind] ?? 0)) return null;
+      const plan = { switch: true, from: this.current, to: path, keepUntilMs: this.now() + this.overlapMs, reason: 'better-path' };
+      this.lastPlan = plan;
+      this.current = path;
+      this.challenger = null;
+      this.leading = 0;
+      return plan;
+    }
+    this.challenger = path;
+    this.leading = 0;
+    return null;
+  }
+
+  /** Close the loser only after the overlap window has elapsed. */
+  breakOld(plan, atMs = this.now()) {
+    if (plan?.switch !== true) return { ok: false, code: SCHEDULER_CODE.NOT_ENCRYPTED };
+    if (atMs < plan.keepUntilMs) return { ok: false, code: SCHEDULER_CODE.SWITCH_PENDING, closeAtMs: plan.keepUntilMs };
+    return { ok: true, close: plan.from };
+  }
+}

package/src/agent/transfer/artifact-ref-v3.mjs

@@ -0,0 +1,93 @@
+/**
+ * Optional ArtifactRef v3 (feature-flagged; v2 remains the default on the wire).
+ *
+ * v3 adds an explicit hash algorithm, a Merkle root and a SHA-256 root so a
+ * reader can cross-check the two aggregations. BLAKE3 is not bundled and Node
+ * has no native implementation: when it is unavailable, creation falls back to
+ * SHA-256 and records that decision instead of pretending BLAKE3 was used.
+ */
+import { createHash } from 'node:crypto';
+
+export const REF_V3_VERSION = 3;
+
+export const REF_V3_CODE = Object.freeze({
+  OK: 'REF_V3_OK',
+  BAD_SHAPE: 'REF_V3_BAD_SHAPE',
+  UNSUPPORTED_ALG: 'REF_V3_UNSUPPORTED_ALG',
+  BLAKE3_UNAVAILABLE: 'XFER_BLAKE3_UNAVAILABLE',
+  INCONSISTENT: 'REF_V3_INCONSISTENT',
+});
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest();
+const hex64 = (value) => {
+  if (typeof value !== 'string') return null;
+  const raw = value.startsWith('sha256:') ? value.slice('sha256:'.length) : value;
+  return /^[0-9a-f]{64}$/.test(raw) ? raw : null;
+};
+const isHex64 = (value) => hex64(value) !== null;
+
+/**
+ * Merkle root over chunk digests: leaves are the existing 32-byte chunk hashes;
+ * internal nodes are SHA-256(0x01 || left || right); the final root is
+ * SHA-256(0x02 || root). An odd node is promoted, never duplicated.
+ */
+export function merkleRootSha256(chunkHashesHex) {
+  if (!Array.isArray(chunkHashesHex) || chunkHashesHex.length === 0) return null;
+  let level = chunkHashesHex.map((hex) => {
+    if (!isHex64(hex)) throw new TypeError('chunk hash must be 64 lowercase hex characters');
+    return Buffer.from(hex, 'hex');
+  });
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      if (i + 1 >= level.length) { next.push(level[i]); continue; }
+      next.push(sha256(Buffer.concat([Buffer.from([0x01]), level[i], level[i + 1]])));
+    }
+    level = next;
+  }
+  return sha256(Buffer.concat([Buffer.from([0x02]), level[0]])).toString('hex');
+}
+
+/**
+ * @param {{rootCid: string, sha256Root: string, merkleRoot: string, hashAlg?: string,
+ *          chunkBytes: number, chunkCount: number, size: number, originPeer?: string|null,
+ *          blake3Available?: boolean}} input
+ * @returns {{ok: true, ref: object} | {ok: false, code: string, detail?: string}}
+ */
+export function createRefV3(input) {
+  const requestedAlg = input?.hashAlg === 'blake3' ? 'blake3' : 'sha256';
+  const effectiveAlg = requestedAlg === 'blake3' && input?.blake3Available !== true ? 'sha256' : requestedAlg;
+  const ref = {
+    version: REF_V3_VERSION,
+    rootCid: hex64(input?.rootCid) ?? input?.rootCid,
+    sha256Root: hex64(input?.sha256Root) ?? input?.sha256Root,
+    merkleRoot: input?.merkleRoot,
+    hashAlg: effectiveAlg,
+    ...(effectiveAlg !== requestedAlg ? { fallbackFrom: requestedAlg } : {}),
+    chunkBytes: input?.chunkBytes,
+    chunkCount: input?.chunkCount,
+    size: input?.size,
+    originPeer: typeof input?.originPeer === 'string' ? input.originPeer : null,
+  };
+  return verifyRefV3(ref, { blake3Available: input?.blake3Available === true });
+}
+
+/**
+ * Validate v3 shape and invariants. A BLAKE3 v3 ref cannot be verified on a
+ * runtime without BLAKE3: that is named, not silently downgraded.
+ */
+export function verifyRefV3(ref, { blake3Available = false } = {}) {
+  if (ref === null || typeof ref !== 'object') return { ok: false, code: REF_V3_CODE.BAD_SHAPE, detail: 'ref must be an object' };
+  if (ref.version !== REF_V3_VERSION) return { ok: false, code: REF_V3_CODE.BAD_SHAPE, detail: 'version must be 3' };
+  if (!isHex64(ref.rootCid) || !isHex64(ref.sha256Root) || !isHex64(ref.merkleRoot)) {
+    return { ok: false, code: REF_V3_CODE.BAD_SHAPE, detail: 'rootCid, sha256Root and merkleRoot must be 64-hex' };
+  }
+  if (ref.hashAlg !== 'sha256' && ref.hashAlg !== 'blake3') return { ok: false, code: REF_V3_CODE.UNSUPPORTED_ALG, detail: String(ref.hashAlg) };
+  if (ref.hashAlg === 'blake3' && blake3Available !== true) return { ok: false, code: REF_V3_CODE.BLAKE3_UNAVAILABLE };
+  for (const name of ['chunkBytes', 'chunkCount', 'size']) {
+    if (!Number.isInteger(ref[name]) || ref[name] < (name === 'size' ? 0 : 1)) return { ok: false, code: REF_V3_CODE.BAD_SHAPE, detail: name };
+  }
+  if (ref.chunkCount !== Math.ceil(ref.size / ref.chunkBytes)) return { ok: false, code: REF_V3_CODE.INCONSISTENT, detail: 'chunkCount != ceil(size/chunkBytes)' };
+  if (ref.hashAlg === 'sha256' && hex64(ref.rootCid) !== hex64(ref.sha256Root)) return { ok: false, code: REF_V3_CODE.INCONSISTENT, detail: 'sha256 rootCid must equal sha256Root' };
+  return { ok: true, code: REF_V3_CODE.OK, ref, effectiveAlg: ref.hashAlg };
+}

package/src/agent/transfer/ferry.mjs

@@ -86,6 +86,9 @@ export function verifyRefV2(ref) {
   if (typeof ref.ref !== 'string' || ref.ref === '') return { ok: false, code: 'ARTIFACT_REF_INVALID' };
   if (typeof ref.rootCid !== 'string' || !ROOT.test(ref.rootCid)) return { ok: false, code: 'ARTIFACT_ROOT_INVALID' };
   if (!Number.isSafeInteger(ref.size) || ref.size < 0 || !Number.isSafeInteger(ref.chunkCount) || ref.chunkCount < 0) return { ok: false, code: 'ARTIFACT_REF_INVALID' };
+  const plan = chunkLengths(ref.size, ref.chunkBytes);
+  if (plan.ok !== true) return plan;
+  if (plan.count !== ref.chunkCount) return { ok: false, code: 'ARTIFACT_REF_INCONSISTENT', detail: { expectedChunks: plan.count, chunkCount: ref.chunkCount } };
   if (typeof ref.originPeer !== 'string' || ref.originPeer === '') return { ok: false, code: 'ARTIFACT_ORIGIN_REQUIRED' };
   return { ok: true };
 }
@@ -165,7 +168,7 @@ export function createReceiver({ stateDir, sinkRoot, ref, destination, chunkByte
       if (buf.length !== range.length) return { ok: false, code: 'XFER_CHUNK_LENGTH_INVALID', detail: { expected: range.length, got: buf.length } };
       const digest = sha256(buf);
       if (typeof expectedSha256 !== 'string' || expectedSha256 !== digest) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH', retry: index };
-      if (bitmap.hashes[index] !== null && bitmap.hashes[index] !== digest) return { ok: false, code: 'XFER_CHUNK_CONFLICT' };
+      if (bitmap.hashes[index] !== null && bitmap.hashes[index] !== digest) return { ok: false, code: 'XFER_CHUNK_CONFLICT', recoverable: true, retry: index };
       if (bitmap.hashes[index] === digest) return { ok: true, duplicate: true, index };
       const fd = openSync(partPath, 'r+');
       try { writeSync(fd, buf, 0, buf.length, range.offset); } finally { closeSync(fd); }
@@ -187,6 +190,14 @@ export function createReceiver({ stateDir, sinkRoot, ref, destination, chunkByte
       try { writeFileSync(join(dir, 'done.json'), JSON.stringify({ transferId, rootCid, size: bitmap.size, path: target, at: new Date().toISOString() }), { encoding: 'utf8', mode: 0o600 }); } catch { /* receipt is best effort */ }
       return { ok: true, path: target, verified: true, bytes: bitmap.size, transferId };
     },
+    /** Explicit recovery for a conflicting source: drop the claimed block so a correct source can win. */
+    evictChunk(index) {
+      if (!Number.isInteger(index) || index < 0 || index >= bitmap.chunkCount) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      if (bitmap.hashes[index] === null) return { ok: true, index, alreadyMissing: true };
+      bitmap.hashes[index] = null;
+      save();
+      return { ok: true, index, evicted: true };
+    },
     /** 远端 P2P 拉取尚未接线：显式失败，不回落 relay。 */
     async pullFrom(originPeer) {
       return { ok: false, code: 'P2P_UNAVAILABLE', detail: { originPeer, why: 'want-block transport is a later slice; relay fallback is forbidden' } };

package/src/agent/transfer/router.mjs

@@ -0,0 +1,80 @@
+/**
+ * P0-a: route `xfer.*` frames that arrive on a real P2PChannel.
+ *
+ * The router owns no transport: it is handed the frame and a channel, and it
+ * uses the existing chunk source/client primitives. Registering a source or a
+ * receiver is explicit, so an unregistered frame is dropped (never guessed).
+ * One listener per channel is the caller's job; this router never attaches one.
+ */
+import { createChunkSource, createWantClient } from './want-block.mjs';
+
+export function createXferFrameRouter() {
+  const sources = new Map();    // rootCid -> { chunked, filePath, transferId, source }
+  const receivers = new Map();  // transferId -> { receiver, client }
+
+  const parse = (payload) => {
+    if (Buffer.isBuffer(payload) || typeof payload === 'string') {
+      try { return JSON.parse(Buffer.from(payload).toString('utf8')); } catch { return null; }
+    }
+    return payload !== null && typeof payload === 'object' ? payload : null;
+  };
+
+  return {
+    registerSource(rootCid, { chunked, filePath, transferId = null } = {}) {
+      if (typeof rootCid !== 'string' || rootCid === '') return { ok: false, code: 'XFER_ROOT_INVALID' };
+      sources.set(rootCid, { chunked, filePath, transferId, source: null, sourceTransferId: null });
+      return { ok: true };
+    },
+    registerReceiver(transferId, receiver, rootCid) {
+      if (typeof transferId !== 'string' || transferId === '') return { ok: false, code: 'XFER_TRANSFER_INVALID' };
+      const client = createWantClient({ transferId, rootCid, receiver });
+      if (client.ok !== true) return client;
+      receivers.set(transferId, { receiver, client });
+      return { ok: true };
+    },
+    unregister(rootCid) { sources.delete(rootCid); },
+    has(rootCid) { return sources.has(rootCid); },
+    /** Send the next want window for a registered receiver over a channel. */
+    request(transferId, channel) {
+      const entry = receivers.get(transferId);
+      if (entry === undefined || typeof channel?.send !== 'function') return { ok: false, code: 'XFER_RECEIVER_UNKNOWN' };
+      const missing = entry.client.missing();
+      if (missing.length === 0) return { ok: true, requested: 0 };
+      const frames = entry.client.requestFrames(missing);
+      for (const frame of frames) channel.send(JSON.stringify(frame));
+      return { ok: true, requested: missing.length };
+    },
+    /**
+     * @returns {boolean} true when the frame belonged to this layer (handled or refused)
+     */
+    handle(payload, { channel } = {}) {
+      const frame = parse(payload);
+      if (frame === null || typeof frame.type !== 'string' || !frame.type.startsWith('xfer.')) return false;
+      if (typeof channel?.send !== 'function') return true;
+      if (frame.type === 'xfer.want') {
+        const entry = sources.get(frame.rootCid) ?? sources.get(frame.transferId);
+        if (entry === undefined) return true; // unknown source: drop, do not leak why
+        if (entry.source === null || entry.sourceTransferId !== frame.transferId) {
+          entry.source = createChunkSource({ chunked: entry.chunked, filePath: entry.filePath, transferId: frame.transferId });
+          entry.sourceTransferId = frame.transferId;
+        }
+        const served = entry.source.handle(frame);
+        if (served.ok !== true) { channel.send(JSON.stringify({ type: 'xfer.error', transferId: frame.transferId, code: served.code })); return true; }
+        for (const outgoing of served.frames) channel.send(JSON.stringify(outgoing));
+        return true;
+      }
+      if (frame.type === 'xfer.chunk') {
+        const entry = receivers.get(frame.transferId);
+        if (entry === undefined) return true;
+        entry.receiver.writeChunk(frame.index, Buffer.from(String(frame.data), 'base64'), frame.sha256);
+        return true;
+      }
+      if (frame.type === 'xfer.error') {
+        const entry = receivers.get(frame.transferId);
+        if (entry !== undefined) entry.lastError = frame.code ?? 'XFER_PEER_ERROR';
+        return true;
+      }
+      return true;
+    },
+  };
+}

package/src/agent/transfer/want-block.mjs

@@ -87,3 +87,49 @@ export function verifyChunkFrame(frame) {
   if (digest !== frame.sha256) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
   return { ok: true, data };
 }
+
+
+/**
+ * P0-a: run the chunk source over a MessageChannel (P2PChannel / iroh sidecar)
+ * instead of a bare dgram socket. Frames stay JSON for wire compatibility; the
+ * channel supplies encryption, ACK and fragmentation.
+ */
+export function attachChunkSource(channel, { chunked, filePath, transferId = null }) {
+  const source = createChunkSource({ chunked, filePath, transferId });
+  if (source.ok !== true) return source;
+  const handler = (payload) => {
+    let frame = null;
+    try { frame = JSON.parse(Buffer.from(payload).toString('utf8')); } catch { return; }
+    const served = source.handle(frame);
+    if (served.ok !== true) { channel.send(JSON.stringify({ type: ERROR, transferId: frame?.transferId ?? null, code: served.code })); return; }
+    for (const outgoing of served.frames) channel.send(JSON.stringify(outgoing));
+  };
+  channel.on('message', handler);
+  return { ok: true, close: () => channel.off?.('message', handler) };
+}
+
+/**
+ * P0-a: receiver side over a MessageChannel. request() sends the next window;
+ * inbound chunk frames are validated and written exactly as in the UDP path.
+ */
+export function attachWantClient(channel, { transferId, rootCid, receiver }) {
+  const client = createWantClient({ transferId, rootCid, receiver });
+  if (client.ok !== true) return client;
+  const handler = (payload) => {
+    let frame = null;
+    try { frame = JSON.parse(Buffer.from(payload).toString('utf8')); } catch { return; }
+    client.accept(frame);
+  };
+  channel.on('message', handler);
+  return {
+    ok: true,
+    client,
+    request() {
+      const missing = client.missing();
+      if (missing.length === 0) return 0;
+      channel.send(JSON.stringify(client.requestFrames(missing)[0]));
+      return missing.length;
+    },
+    close: () => channel.off?.('message', handler),
+  };
+}