@twinsearth/w2m-dsh-plugin 2.0.7 → 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

@@ -0,0 +1,206 @@
+/**
+ * Artifact Ferry v1（本地最小闭环）：chunkFile → ArtifactRef → sink 接收端。
+ *
+ * 不变式：
+ *   · 控制面只持引用（ref/rootCid/size/chunkCount），字节永远在本机或 sink；
+ *   · 发送端流式分块，内存与文件大小无关；每块 SHA-256；
+ *   · 接收端逐块校验、位图持久化、可断点续传；finalize 重算根才原子落盘；
+ *   · 路径只允许 sink 根下的相对路径（拒绝绝对路径/.. /盘符/UNC）。
+ * 本阶段不做远端 P2P 拉取：`pull` 明确返回 P2P_UNAVAILABLE，绝不回落 relay blob。
+ */
+import { createHash } from 'node:crypto';
+import {
+  closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readdirSync, readFileSync,
+  readSync, renameSync, statSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { createManifest, chunkLengths, chunkRange } from './manifest.mjs';
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const ROOT = /^sha256:[0-9a-f]{64}$/;
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+
+export function safeRelative(input) {
+  if (typeof input !== 'string' || input.trim() === '') return { ok: false, code: 'PATH_REQUIRED' };
+  const raw = input.replace(/\\/g, '/');
+  if (raw.includes('\0')) return { ok: false, code: 'PATH_NUL' };
+  if (isAbsolute(input) || /^[A-Za-z]:/.test(raw) || raw.startsWith('//')) return { ok: false, code: 'PATH_ABSOLUTE' };
+  const parts = raw.split('/').filter((part) => part !== '' && part !== '.');
+  if (parts.length === 0 || parts.some((part) => part === '..')) return { ok: false, code: 'PATH_TRAVERSAL' };
+  return { ok: true, relative: parts.join('/') };
+}
+
+/** 流式分块：只读一块、算一块的哈希；返回 rootCid 与块清单。 */
+export function chunkFile(filePath, { chunkBytes = 1024 * 1024 } = {}) {
+  const stat = statSync(filePath);
+  const plan = chunkLengths(stat.size, chunkBytes);
+  if (plan.ok !== true) return plan;
+  const fd = openSync(filePath, 'r');
+  const chunks = [];
+  try {
+    for (let index = 0; index < plan.count; index += 1) {
+      const length = index === plan.count - 1 ? plan.lastChunkBytes : plan.chunkBytes;
+      const buf = Buffer.alloc(length);
+      const read = readSync(fd, buf, 0, length, index * plan.chunkBytes);
+      if (read !== length) return { ok: false, code: 'XFER_READ_SHORT' };
+      const digest = sha256(buf);
+      chunks.push({ index, cid: 'sha256:' + digest, sha256: digest, size: length });
+    }
+  } finally {
+    closeSync(fd);
+  }
+  const built = createManifest({
+    sizeBytes: stat.size,
+    chunkBytes: plan.chunkBytes,
+    chunkHashes: chunks.map((chunk) => chunk.sha256),
+    objectId: sha256(`${stat.size}:${plan.chunkBytes}:${chunks.map((c) => c.sha256).join('')}`).slice(0, 32),
+    kind: 'file',
+    sinkKind: 'cache',
+    relPath: basename(filePath),
+  });
+  if (built.ok !== true) return built;
+  return {
+    ok: true,
+    rootCid: 'sha256:' + built.manifest.root_sha256,
+    rootHex: built.manifest.root_sha256,
+    size: stat.size,
+    chunkBytes: plan.chunkBytes,
+    chunkCount: plan.count,
+    chunks,
+  };
+}
+
+/** 控制面引用：只含元数据，不含字节、块清单或路径。 */
+export function createRefV2({ rootCid, size, chunkCount, chunkBytes, originPeer, sinkHint = 'workspace://artifacts', mediaType = 'application/octet-stream', refId = null }) {
+  if (typeof rootCid !== 'string' || !ROOT.test(rootCid)) return { ok: false, code: 'ARTIFACT_ROOT_INVALID' };
+  if (!Number.isSafeInteger(size) || size < 0) return { ok: false, code: 'ARTIFACT_SIZE_INVALID' };
+  if (!Number.isSafeInteger(chunkCount) || chunkCount < 0) return { ok: false, code: 'ARTIFACT_CHUNKS_INVALID' };
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) return { ok: false, code: 'ARTIFACT_CHUNK_SIZE_INVALID' };
+  if (typeof originPeer !== 'string' || originPeer === '') return { ok: false, code: 'ARTIFACT_ORIGIN_REQUIRED' };
+  return { ok: true, ref: { v: 2, ref: refId ?? rootCid, rootCid, size, chunkCount, chunkBytes, mediaType, originPeer, sinkHint } };
+}
+
+export function verifyRefV2(ref) {
+  if (ref === null || typeof ref !== 'object' || ref.v !== 2) return { ok: false, code: 'ARTIFACT_REF_INVALID' };
+  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 };
+}
+
+/** 本地引用索引（控制面的本机替身；relay 发布是下一阶段接线）。 */
+export function createRefIndex({ dir }) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const fileOf = (refId) => join(dir, sha256(String(refId)) + '.json');
+  return {
+    publish(ref) {
+      const checked = verifyRefV2(ref);
+      if (checked.ok !== true) return checked;
+      const file = fileOf(ref.ref);
+      writeFileSync(file, JSON.stringify(ref), { encoding: 'utf8', mode: 0o600 });
+      return { ok: true, ref, path: file };
+    },
+    get(refId) {
+      try {
+        const ref = readJson(fileOf(refId));
+        const checked = verifyRefV2(ref);
+        return checked.ok === true ? { ok: true, ref } : checked;
+      } catch { return { ok: false, code: 'ARTIFACT_REF_NOT_FOUND' }; }
+    },
+    list() {
+      return { ok: true, refs: readdirSync(dir).filter((n) => n.endsWith('.json')).map((n) => { try { return readJson(join(dir, n)); } catch { return null; } }).filter(Boolean) };
+    },
+  };
+}
+
+/**
+ * 接收端：位图持久化 + 逐块校验 + finalize 根校验后原子落盘。
+ * @param {{stateDir:string, sinkRoot:string, ref:object, destination:string, chunkBytes?:number}} input
+ */
+export function createReceiver({ stateDir, sinkRoot, ref, destination, chunkBytes = null }) {
+  const checked = verifyRefV2(ref);
+  if (checked.ok !== true) return checked;
+  const safe = safeRelative(destination);
+  if (safe.ok !== true) return safe;
+  const root = resolve(sinkRoot);
+  const target = resolve(root, safe.relative);
+  const rel = relative(root, target);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('..')) return { ok: false, code: 'PATH_TRAVERSAL' };
+  const transferId = sha256(ref.ref + '|' + ref.rootCid + '|' + ref.size).slice(0, 32);
+  const dir = join(stateDir, transferId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const bitmapPath = join(dir, 'bitmap.json');
+  const partPath = join(dir, 'data.part');
+  const chunk = Number.isInteger(chunkBytes) ? chunkBytes : ref.chunkBytes;
+  let bitmap = null;
+  if (existsSync(bitmapPath)) {
+    try { bitmap = readJson(bitmapPath); } catch { bitmap = null; }
+    if (bitmap !== null && (bitmap.rootCid !== ref.rootCid || bitmap.size !== ref.size || bitmap.chunkBytes !== chunk)) return { ok: false, code: 'XFER_SESSION_CONFLICT' };
+  }
+  if (bitmap === null) {
+    const fd = openSync(partPath, 'w+', 0o600);
+    try { ftruncateSync(fd, ref.size); } finally { closeSync(fd); }
+    bitmap = { v: 1, transferId, rootCid: ref.rootCid, size: ref.size, chunkBytes: chunk, chunkCount: ref.chunkCount, chunks: ref.chunkCount, chunk_bytes: chunk, last_chunk_bytes: ref.chunkCount === 0 ? 0 : ref.size - (ref.chunkCount - 1) * chunk, hashes: Array(ref.chunkCount).fill(null), destination: safe.relative, updatedAt: new Date().toISOString() };
+    writeFileSync(bitmapPath, JSON.stringify(bitmap), { encoding: 'utf8', mode: 0o600 });
+  }
+  const save = () => { bitmap.updatedAt = new Date().toISOString(); const tmp = bitmapPath + '.tmp-' + process.pid; writeFileSync(tmp, JSON.stringify(bitmap), { encoding: 'utf8', mode: 0o600 }); renameSync(tmp, bitmapPath); };
+  let finalized = false;
+  return {
+    ok: true,
+    transferId,
+    have() {
+      return new Set(bitmap.hashes.map((h, i) => (h === null ? null : i)).filter((i) => i !== null));
+    },
+    progress() {
+      const received = bitmap.hashes.map((h, i) => (h === null ? null : i)).filter((i) => i !== null);
+      return { total: bitmap.chunkCount, received: received.length, complete: received.length === bitmap.chunkCount, bytes: bitmap.hashes.reduce((sum, h, i) => sum + (h === null ? 0 : i === bitmap.chunkCount - 1 ? bitmap.size - i * chunk : chunk), 0) };
+    },
+    writeChunk(index, data, expectedSha256) {
+      if (finalized) return { ok: false, code: 'XFER_ALREADY_FINALIZED' };
+      const range = chunkRange(bitmap, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.isBuffer(data) ? data : Buffer.from(data ?? '');
+      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', 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); }
+      bitmap.hashes[index] = digest;
+      save();
+      return { ok: true, index, sha256: digest, writtenBytes: buf.length };
+    },
+    finalizeTransfer(rootCid = ref.rootCid) {
+      if (rootCid !== ref.rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      if (bitmap.hashes.some((h) => h === null)) return { ok: false, code: 'XFER_CHUNKS_MISSING', detail: { missing: bitmap.hashes.filter((h) => h === null).length } };
+      const built = createManifest({ sizeBytes: bitmap.size, chunkBytes: bitmap.chunkBytes, chunkHashes: bitmap.hashes, objectId: transferId, kind: 'file', sinkKind: 'cache', relPath: safe.relative });
+      if (built.ok !== true) return built;
+      if ('sha256:' + built.manifest.root_sha256 !== rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      mkdirSync(resolve(target, '..'), { recursive: true, mode: 0o700 });
+      const fd = openSync(partPath, 'r+');
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(partPath, target);
+      finalized = true;
+      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/index.mjs

@@ -0,0 +1,4 @@
+export * from './manifest.mjs';
+export * from './ferry.mjs';
+export * from './publish.mjs';
+export * from './want-block.mjs';