@twinsearth/w2m-dsh-plugin 2.0.7 → 2.0.9

package/src/agent/transfer/manifest.mjs

@@ -0,0 +1,92 @@
+/**
+ * 文件分块清单（C1 的最小可信底座）。
+ *
+ * 纯函数，无 I/O：给定文件大小与块大小，产出一份可独立校验的 manifest。
+ * root = SHA256("w2m-xfer-root-v1" || size || chunkBytes || 逐块 SHA256)，域分离避免
+ * 叶哈希/根哈希/不同切法互相混淆；manifest 本身不再包含明文内容。
+ */
+import { createHash } from 'node:crypto';
+
+export const XFER_VERSION = 1;
+export const DEFAULT_CHUNK_BYTES = 256 * 1024;
+export const MIN_CHUNK_BYTES = 16 * 1024;
+export const MAX_CHUNK_BYTES = 2 * 1024 * 1024;
+export const MAX_CHUNKS = 65536;
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+export function chunkLengths(sizeBytes, chunkBytes = DEFAULT_CHUNK_BYTES) {
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 0) return { ok: false, code: 'XFER_SIZE_INVALID' };
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes < MIN_CHUNK_BYTES || chunkBytes > MAX_CHUNK_BYTES) return { ok: false, code: 'XFER_CHUNK_SIZE_INVALID' };
+  if (sizeBytes === 0) return { ok: true, count: 0, chunkBytes, lastChunkBytes: 0 };
+  const count = Math.ceil(sizeBytes / chunkBytes);
+  if (count > MAX_CHUNKS) return { ok: false, code: 'XFER_TOO_MANY_CHUNKS', detail: { count, max: MAX_CHUNKS } };
+  return { ok: true, count, chunkBytes, lastChunkBytes: sizeBytes % chunkBytes === 0 ? chunkBytes : sizeBytes % chunkBytes };
+}
+
+export function chunkSha256(bytes) {
+  return sha256(bytes);
+}
+
+/**
+ * @param {{sizeBytes:number, chunkBytes?:number, chunkHashes:string[], objectId:string, taskId?:string|null,
+ *          machineId?:string|null, kind?:string, sinkKind?:string, relPath:string, cipherBytes?:number}} input
+ */
+export function createManifest(input) {
+  const plan = chunkLengths(input.sizeBytes, input.chunkBytes ?? DEFAULT_CHUNK_BYTES);
+  if (plan.ok !== true) return plan;
+  const hashes = Array.isArray(input.chunkHashes) ? input.chunkHashes : [];
+  if (hashes.length !== plan.count) return { ok: false, code: 'XFER_CHUNK_COUNT_MISMATCH', detail: { expected: plan.count, got: hashes.length } };
+  for (const hash of hashes) if (typeof hash !== 'string' || !/^[0-9a-f]{64}$/.test(hash)) return { ok: false, code: 'XFER_CHUNK_HASH_INVALID' };
+  const root = createHash('sha256')
+    .update('w2m-xfer-root-v1\0')
+    .update(String(input.sizeBytes) + '\0' + String(plan.chunkBytes) + '\0')
+    .update(hashes.join('\0'))
+    .digest('hex');
+  return {
+    ok: true,
+    manifest: {
+      v: XFER_VERSION,
+      object_id: input.objectId,
+      task_id: input.taskId ?? null,
+      machine_id: input.machineId ?? null,
+      kind: typeof input.kind === 'string' ? input.kind : 'stdout',
+      sink: { kind: typeof input.sinkKind === 'string' ? input.sinkKind : 'cache', rel_path: input.relPath },
+      size_bytes: input.sizeBytes,
+      chunk_bytes: plan.chunkBytes,
+      chunks: plan.count,
+      last_chunk_bytes: plan.lastChunkBytes,
+      chunk_hashes: hashes.slice(),
+      root_sha256: root,
+    },
+  };
+}
+
+export function verifyManifest(manifest) {
+  if (manifest === null || typeof manifest !== 'object') return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  if (manifest.v !== XFER_VERSION) return { ok: false, code: 'XFER_MANIFEST_VERSION' };
+  if (typeof manifest.object_id !== 'string' || !/^[0-9a-f]{32,64}$/.test(manifest.object_id)) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+  if (!Number.isSafeInteger(manifest.size_bytes) || manifest.size_bytes < 0) return { ok: false, code: 'XFER_SIZE_INVALID' };
+  const rebuilt = createManifest({
+    sizeBytes: manifest.size_bytes,
+    chunkBytes: manifest.chunk_bytes,
+    chunkHashes: manifest.chunk_hashes,
+    objectId: manifest.object_id,
+    taskId: manifest.task_id,
+    machineId: manifest.machine_id,
+    kind: manifest.kind,
+    sinkKind: manifest.sink?.kind,
+    relPath: manifest.sink?.rel_path,
+  });
+  if (rebuilt.ok !== true) return rebuilt;
+  if (rebuilt.manifest.root_sha256 !== manifest.root_sha256) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+  return { ok: true };
+}
+
+/** 某一块在文件中的字节偏移与长度（最后一块较短）。 */
+export function chunkRange(manifest, index) {
+  if (!Number.isInteger(index) || index < 0 || index >= manifest.chunks) return null;
+  const offset = index * manifest.chunk_bytes;
+  const length = index === manifest.chunks - 1 ? manifest.last_chunk_bytes : manifest.chunk_bytes;
+  return { offset, length };
+}

package/src/agent/transfer/object-store.mjs

@@ -0,0 +1,144 @@
+/**
+ * 分块落盘 / 读取端的最小实现（C1 + C3 共用）。
+ *
+ * 一个对象一个目录：data.part（稀疏、按 offset 写）、meta.json（原子更新）。
+ * 提交前必须：全部块到齐、逐块哈希匹配、根哈希重算一致 → fsync → rename 为 <object_id>.bin。
+ * 失败保留 data.part 以便续传；根哈希不符则隔离，不产生“半份成品”。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readFileSync, readSync,
+  renameSync, unlinkSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { createManifest, chunkLengths, chunkRange, XFER_VERSION } from './manifest.mjs';
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+
+export function createObjectStore({ root }) {
+  if (typeof root !== 'string' || root === '') throw new TypeError('XFER_STORE_ROOT_REQUIRED');
+  const dirOf = (objectId) => join(root, objectId);
+  const metaPath = (objectId) => join(dirOf(objectId), 'meta.json');
+  const partPath = (objectId) => join(dirOf(objectId), 'data.part');
+  const finalPath = (objectId) => join(root, objectId + '.bin');
+
+  const saveMeta = (meta) => {
+    const file = metaPath(meta.object_id);
+    const tmp = file + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex');
+    writeFileSync(tmp, JSON.stringify(meta), { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, file);
+  };
+
+  return {
+    root,
+
+    /** 开始/恢复一个入站对象。同一 objectId 且根一致 = 续传；否则拒绝。 */
+    begin({ objectId, totalBytes, chunkBytes, rootSha256, taskId = null, machineId = null, kind = 'stdout', sinkKind = 'cache', relPath = null }) {
+      if (typeof objectId !== 'string' || !/^[0-9a-f]{32,64}$/.test(objectId)) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+      if (typeof rootSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(rootSha256)) return { ok: false, code: 'XFER_ROOT_INVALID' };
+      const dir = dirOf(objectId);
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      // A completed object is immutable and needs no new session.
+      if (existsSync(finalPath(objectId))) return { ok: true, resumed: false, complete: true, objectId };
+      if (existsSync(metaPath(objectId))) {
+        const meta = readJson(metaPath(objectId));
+        if (meta.root_sha256 !== rootSha256 || meta.size_bytes !== totalBytes) return { ok: false, code: 'XFER_OBJECT_CONFLICT' };
+        meta.resumed = true;
+        saveMeta(meta);
+        return { ok: true, resumed: true, complete: meta.chunk_hashes.every((h) => h !== null), objectId };
+      }
+      const plan = chunkLengths(totalBytes, chunkBytes);
+      if (plan.ok !== true) return plan;
+      const fd = openSync(partPath(objectId), 'w+', 0o600);
+      try { ftruncateSync(fd, totalBytes); } finally { closeSync(fd); }
+      const emptyRoot = createManifest({ sizeBytes: 0, chunkBytes, chunkHashes: [], objectId, taskId, machineId, kind, sinkKind, relPath: relPath ?? objectId + '.bin' }).manifest.root_sha256;
+      const meta = {
+        v: XFER_VERSION,
+        object_id: objectId,
+        task_id: taskId,
+        machine_id: machineId,
+        kind,
+        sink: { kind: sinkKind, rel_path: relPath ?? objectId + '.bin' },
+        size_bytes: totalBytes,
+        chunk_bytes: plan.chunkBytes,
+        chunks: plan.count,
+        last_chunk_bytes: plan.lastChunkBytes,
+        root_sha256: totalBytes === 0 ? emptyRoot : rootSha256,
+        root_expected: rootSha256,
+        chunk_hashes: Array(plan.count).fill(null),
+        created_at: new Date().toISOString(),
+      };
+      // 空对象直接可提交：根必须与调用方声明的根一致。
+      if (totalBytes === 0 && rootSha256 !== emptyRoot) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      saveMeta(meta);
+      return { ok: true, resumed: false, complete: totalBytes === 0, objectId };
+    },
+
+    /** 写一块。乱序允许；同 index 同哈希幂等；冲突即终态错误。 */
+    writeChunk({ objectId, index, bytes, chunkSha256 = null }) {
+      const meta = readJson(metaPath(objectId));
+      const range = chunkRange(meta, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? '');
+      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 (chunkSha256 !== null && chunkSha256 !== digest) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
+      if (meta.chunk_hashes[index] !== null && meta.chunk_hashes[index] !== digest) return { ok: false, code: 'XFER_CHUNK_CONFLICT' };
+      if (meta.chunk_hashes[index] === digest) return { ok: true, duplicate: true, index, sha256: digest };
+      const fd = openSync(partPath(objectId), 'r+');
+      try { writeSync(fd, buf, 0, buf.length, range.offset); } finally { closeSync(fd); }
+      meta.chunk_hashes[index] = digest;
+      saveMeta(meta);
+      return { ok: true, duplicate: false, index, sha256: digest };
+    },
+
+    /** 已完成的块索引；续传握手用。 */
+    have(objectId) {
+      if (!existsSync(metaPath(objectId))) return { ok: false, code: 'XFER_SESSION_NOT_FOUND' };
+      const meta = readJson(metaPath(objectId));
+      const have = [];
+      meta.chunk_hashes.forEach((hash, index) => { if (hash !== null) have.push(index); });
+      return { ok: true, objectId, have, complete: meta.chunk_hashes.every((h) => h !== null), chunks: meta.chunks, root_sha256: meta.root_expected };
+    },
+
+    /** 全量校验 + 提交。根不符 → 移到 quarantine 并报错（不产生成品）。 */
+    commit(objectId) {
+      const meta = readJson(metaPath(objectId));
+      if (meta.chunk_hashes.some((hash) => hash === null)) return { ok: false, code: 'XFER_CHUNKS_MISSING', detail: { missing: meta.chunk_hashes.filter((h) => h === null).length } };
+      const rebuilt = createManifest({ sizeBytes: meta.size_bytes, chunkBytes: meta.chunk_bytes, chunkHashes: meta.chunk_hashes, objectId: meta.object_id, taskId: meta.task_id, machineId: meta.machine_id, kind: meta.kind, sinkKind: meta.sink.kind, relPath: meta.sink.rel_path });
+      if (rebuilt.ok !== true) return rebuilt;
+      if (rebuilt.manifest.root_sha256 !== meta.root_expected) return { ok: false, code: 'XFER_ROOT_MISMATCH', detail: { expected: meta.root_expected, actual: rebuilt.manifest.root_sha256 } };
+      const fd = openSync(partPath(objectId), 'r+');
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(partPath(objectId), finalPath(objectId));
+      const manifest = { ...rebuilt.manifest, committed_at: new Date().toISOString() };
+      const file = join(root, objectId + '.ref.json');
+      writeFileSync(file, JSON.stringify(manifest), { encoding: 'utf8', mode: 0o600 });
+      try { unlinkSync(metaPath(objectId)); } catch { /* already gone */ }
+      try { unlinkSync(dirOf(objectId)); } catch { /* directory removal is best effort */ }
+      return { ok: true, objectId, bytes: meta.size_bytes, sha256: rebuilt.manifest.root_sha256, path: finalPath(objectId), manifest };
+    },
+
+    /** 读一块并校验；损坏返回 XFER_CHUNK_HASH_MISMATCH，绝不返回坏字节。 */
+    readChunk({ objectId, index }) {
+      const manifestPath = join(root, objectId + '.ref.json');
+      if (!existsSync(manifestPath)) return { ok: false, code: 'XFER_OBJECT_NOT_FOUND' };
+      const manifest = readJson(manifestPath);
+      const range = chunkRange(manifest, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.alloc(range.length);
+      const fd = openSync(finalPath(objectId), 'r');
+      try { const read = readSync(fd, buf, 0, range.length, range.offset); if (read !== range.length) return { ok: false, code: 'XFER_READ_SHORT' }; } finally { closeSync(fd); }
+      if (sha256(buf) !== manifest.chunk_hashes[index]) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
+      return { ok: true, bytes: buf, index, sha256: manifest.chunk_hashes[index] };
+    },
+
+    has(objectId) {
+      if (existsSync(join(root, objectId + '.ref.json'))) return { ok: true, complete: true, bytes: readJson(join(root, objectId + '.ref.json')).size_bytes };
+      if (existsSync(metaPath(objectId))) { const have = this.have(objectId); return { ok: true, complete: false, received: have.have ?? [], chunks: have.chunks ?? null }; }
+      return { ok: false, code: 'XFER_OBJECT_NOT_FOUND' };
+    },
+  };
+}

package/src/agent/transfer/publish.mjs

@@ -0,0 +1,76 @@
+/**
+ * C2：ArtifactRef 的控制面发布（复用 relay 现有项目决策通道，不新增存储、不传字节）。
+ *
+ * 发布体 = { title:"artifact.available", kind:"artifact_available", text: JSON(ref) }；
+ * relay 只记录这条元数据，字节永远在本机对象库/sink。读取端按 title 过滤并校验 ref。
+ * 该通道在 relay 2.0.5 已存在（POST/GET /v1/projects/:id/decisions），无需新路由即可先跑通。
+ */
+import { verifyRefV2 } from './ferry.mjs';
+
+const TITLE = 'artifact.available';
+const KIND = 'artifact_available';
+
+function baseOf(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  return url.trim().replace(/\/+$/, '');
+}
+
+/**
+ * @param {{relayUrl:string, token:string, projectId?:string, ref:object, fetchImpl?:Function, signal?:AbortSignal}} input
+ */
+export async function publishRef(input) {
+  const base = baseOf(input?.relayUrl);
+  if (base === null) return { ok: false, code: 'RELAY_URL_REQUIRED' };
+  if (typeof input?.token !== 'string' || input.token === '') return { ok: false, code: 'OPERATOR_TOKEN_REQUIRED' };
+  const checked = verifyRefV2(input?.ref);
+  if (checked.ok !== true) return checked;
+  const projectId = typeof input.projectId === 'string' && input.projectId !== '' ? input.projectId : 'default';
+  const fetchImpl = typeof input.fetchImpl === 'function' ? input.fetchImpl : globalThis.fetch;
+  const body = { title: TITLE, kind: KIND, text: JSON.stringify(checked.ok ? input.ref : null), refs: { rootCid: input.ref.rootCid, originPeer: input.ref.originPeer } };
+  let response = null;
+  try {
+    response = await fetchImpl(base + '/v1/projects/' + encodeURIComponent(projectId) + '/decisions', {
+      method: 'POST',
+      headers: { authorization: 'Bearer ' + input.token, 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: input.signal,
+    });
+  } catch {
+    return { ok: false, code: 'RELAY_UNREACHABLE' };
+  }
+  let json = null;
+  try { json = await response.json(); } catch { json = null; }
+  if (response.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status, error: json?.error?.code ?? null } };
+  if (json?.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status } };
+  return { ok: true, decision: json.decision ?? null, ref: input.ref };
+}
+
+/**
+ * @param {{relayUrl:string, token:string, projectId?:string, fetchImpl?:Function, signal?:AbortSignal}} input
+ */
+export async function listPublishedRefs(input) {
+  const base = baseOf(input?.relayUrl);
+  if (base === null) return { ok: false, code: 'RELAY_URL_REQUIRED' };
+  if (typeof input?.token !== 'string' || input.token === '') return { ok: false, code: 'DEVICE_TOKEN_REQUIRED' };
+  const projectId = typeof input.projectId === 'string' && input.projectId !== '' ? input.projectId : 'default';
+  const fetchImpl = typeof input.fetchImpl === 'function' ? input.fetchImpl : globalThis.fetch;
+  let response = null;
+  try {
+    response = await fetchImpl(base + '/v1/projects/' + encodeURIComponent(projectId) + '/decisions', { headers: { authorization: 'Bearer ' + input.token, accept: 'application/json' }, signal: input.signal });
+  } catch {
+    return { ok: false, code: 'RELAY_UNREACHABLE' };
+  }
+  let json = null;
+  try { json = await response.json(); } catch { json = null; }
+  if (response.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status } };
+  const decisions = Array.isArray(json?.decisions) ? json.decisions : [];
+  const refs = [];
+  for (const decision of decisions) {
+    if (decision?.title !== TITLE || decision?.kind !== KIND) continue;
+    let ref = null;
+    try { ref = JSON.parse(String(decision.text ?? '')); } catch { continue; }
+    if (verifyRefV2(ref).ok !== true) continue;
+    refs.push(ref);
+  }
+  return { ok: true, refs };
+}

package/src/agent/transfer/reference.mjs

@@ -0,0 +1,97 @@
+/**
+ * ArtifactRef v2 + 本地引用登记（C2 的基础形状）与解析阶梯（C3 的本地分支）。
+ *
+ * 控制面只承载元数据：object_id / task / machine / kind / sink / 大小 / 块数 / 根哈希 / TTL。
+ * 字节永远在本机对象库或用户 sink 里。resolver 不回落 relay：本地没有就明确
+ * TRANSFER_UNREACHABLE（远端 P2P 拉取是下一阶段接线）。
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const OBJECT = /^[0-9a-f]{32,64}$/;
+
+export function createRef(manifest, { ttlMs = 24 * 3600 * 1000, now = Date.now } = {}) {
+  if (manifest === null || typeof manifest !== 'object') return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  if (!OBJECT.test(String(manifest.object_id ?? ''))) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+  if (!HEX64.test(String(manifest.root_sha256 ?? ''))) return { ok: false, code: 'XFER_ROOT_INVALID' };
+  if (!Number.isSafeInteger(manifest.size_bytes) || !Number.isSafeInteger(manifest.chunks)) return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  return {
+    ok: true,
+    ref: {
+      v: 2,
+      object_id: manifest.object_id,
+      task_id: manifest.task_id ?? null,
+      machine_id: manifest.machine_id ?? null,
+      kind: manifest.kind ?? 'stdout',
+      sink: { kind: manifest.sink?.kind ?? 'cache', rel_path: manifest.sink?.rel_path ?? manifest.object_id + '.bin' },
+      size_bytes: manifest.size_bytes,
+      chunk_bytes: manifest.chunk_bytes,
+      chunks: manifest.chunks,
+      root_sha256: manifest.root_sha256,
+      created_at: new Date(now()).toISOString(),
+      expires_at: new Date(now() + ttlMs).toISOString(),
+    },
+  };
+}
+
+export function verifyRef(ref, { now = Date.now } = {}) {
+  const nowMs = typeof now === 'function' ? now() : now;
+  if (ref === null || typeof ref !== 'object' || ref.v !== 2) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!OBJECT.test(String(ref.object_id ?? ''))) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!HEX64.test(String(ref.root_sha256 ?? ''))) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (!Number.isSafeInteger(ref.size_bytes) || !Number.isSafeInteger(ref.chunks) || ref.chunks < 0) return { ok: false, code: 'DELIVERY_REF_INVALID' };
+  if (typeof ref.expires_at === 'string' && Date.parse(ref.expires_at) <= nowMs) return { ok: false, code: 'DELIVERY_STALE' };
+  return { ok: true };
+}
+
+export function createRefRegistry({ root }) {
+  if (typeof root !== 'string' || root === '') throw new TypeError('XFER_REF_ROOT_REQUIRED');
+  const dir = join(root, 'refs');
+  const fileOf = (objectId) => join(dir, objectId + '.json');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return {
+    publish(ref) {
+      const checked = verifyRef(ref);
+      if (checked.ok !== true) return checked;
+      const file = fileOf(ref.object_id);
+      writeFileSync(file, JSON.stringify(ref), { encoding: 'utf8', mode: 0o600 });
+      return { ok: true, ref, path: file };
+    },
+    get(objectId) {
+      try {
+        const ref = JSON.parse(readFileSync(fileOf(objectId), 'utf8').replace(/^\uFEFF/, ''));
+        const checked = verifyRef(ref);
+        return checked.ok === true ? { ok: true, ref } : checked;
+      } catch {
+        return { ok: false, code: 'DELIVERY_REF_NOT_FOUND' };
+      }
+    },
+    list() {
+      const refs = [];
+      let names = [];
+      try { names = readdirSync(dir); } catch { return { ok: true, refs }; }
+      for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        try { const ref = JSON.parse(readFileSync(join(dir, name), 'utf8')); if (verifyRef(ref).ok === true) refs.push(ref); } catch { /* skip corrupt */ }
+      }
+      return { ok: true, refs };
+    },
+  };
+}
+
+/**
+ * 本地解析：对象已完整且根哈希匹配 → 返回路径；否则显式失败（不回落 relay）。
+ * 远端 P2P 拉取（C3 的 xfer 分支）在下一阶段接入，这里保留明确的失败语义。
+ */
+export function resolveLocal(ref, { store }) {
+  const checked = verifyRef(ref);
+  if (checked.ok !== true) return checked;
+  const local = store.has(ref.object_id);
+  if (local.ok !== true) return { ok: false, code: 'TRANSFER_UNREACHABLE', detail: { object_id: ref.object_id, reason: 'not in local object store; remote P2P fetch not wired yet' } };
+  if (local.complete !== true) return { ok: false, code: 'TRANSFER_INCOMPLETE', detail: { object_id: ref.object_id } };
+  const manifestPath = join(store.root, ref.object_id + '.ref.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8').replace(/^\uFEFF/, ''));
+  if (manifest.root_sha256 !== ref.root_sha256) return { ok: false, code: 'DELIVERY_ROOT_MISMATCH' };
+  return { ok: true, path: join(store.root, ref.object_id + '.bin'), bytes: manifest.size_bytes, object_id: ref.object_id };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * P2P want-block 协议（传输无关的最小实现）。
+ *
+ * 帧只在两台机器之间流动，绝不经过 relay：
+ *   xfer.want   { transferId, rootCid, indices }
+ *   xfer.chunk  { transferId, index, sha256, size, data(base64) }
+ *   xfer.error  { transferId, code, index? }
+ * 接收端把 chunk 交给 createReceiver().writeChunk；全部到齐后 finalize。
+ * 传输由调用方注入（P2PChannel / 测试用 duplex），本模块不发起 HTTP。
+ */
+import { createHash } from 'node:crypto';
+import { readSync, openSync, closeSync } from 'node:fs';
+
+export const WANT = 'xfer.want';
+export const CHUNK = 'xfer.chunk';
+export const ERROR = 'xfer.error';
+export const MAX_WINDOW = 8;
+export const MAX_CHUNK_B64 = 3 * 1024 * 1024;
+
+const isHex64 = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+
+/** 发送端：按请求读取文件块并编码为帧。 */
+export function createChunkSource({ chunked, filePath, transferId = null }) {
+  if (chunked === null || typeof chunked !== 'object' || !Array.isArray(chunked.chunks)) return { ok: false, code: 'XFER_SOURCE_INVALID' };
+  const tid = transferId ?? chunked.rootCid;
+  return {
+    ok: true,
+    handle(frame) {
+      if (frame?.type !== WANT) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+      if (frame.transferId !== tid) return { ok: false, code: 'XFER_TRANSFER_MISMATCH' };
+      if (frame.rootCid !== chunked.rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      const indices = Array.isArray(frame.indices) ? frame.indices : [];
+      if (indices.length === 0 || indices.length > MAX_WINDOW) return { ok: false, code: 'XFER_WINDOW_INVALID' };
+      const out = [];
+      const fd = openSync(filePath, 'r');
+      try {
+        for (const index of indices) {
+          const chunk = chunked.chunks[index];
+          if (!Number.isInteger(index) || chunk === undefined) { out.push({ type: ERROR, transferId: tid, code: 'XFER_CHUNK_INDEX_INVALID', index }); continue; }
+          const buf = Buffer.alloc(chunk.size);
+          const read = readSync(fd, buf, 0, chunk.size, index * chunked.chunkBytes);
+          if (read !== chunk.size) { out.push({ type: ERROR, transferId: tid, code: 'XFER_READ_SHORT', index }); continue; }
+          out.push({ type: CHUNK, transferId: tid, index, sha256: chunk.sha256, size: chunk.size, data: buf.toString('base64') });
+        }
+      } finally { closeSync(fd); }
+      return { ok: true, frames: out };
+    },
+  };
+}
+
+/** 接收端：把帧写入 createReceiver；缺失块由 receiver 的位图反推。 */
+export function createWantClient({ transferId, rootCid, receiver }) {
+  if (typeof transferId !== 'string' || !isHex64(rootCid?.replace(/^sha256:/, ''))) return { ok: false, code: 'XFER_ROOT_INVALID' };
+  return {
+    ok: true,
+    missing() {
+      const have = receiver.have();
+      const total = receiver.progress().total;
+      const out = [];
+      for (let index = 0; index < total; index += 1) if (!have.has(index)) out.push(index);
+      return out;
+    },
+    requestFrames(indices) {
+      return [{ type: WANT, transferId, rootCid, indices: indices.slice(0, MAX_WINDOW) }];
+    },
+    accept(frame) {
+      if (frame?.type === ERROR) return { ok: false, code: frame.code ?? 'XFER_PEER_ERROR', index: frame.index ?? null };
+      if (frame?.type !== CHUNK) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+      if (frame.transferId !== transferId) return { ok: false, code: 'XFER_TRANSFER_MISMATCH' };
+      if (String(frame.data ?? '').length > MAX_CHUNK_B64) return { ok: false, code: 'XFER_CHUNK_TOO_LARGE' };
+      const data = Buffer.from(String(frame.data), 'base64');
+      const written = receiver.writeChunk(frame.index, data, frame.sha256);
+      if (written.ok !== true) return written;
+      return { ok: true, index: frame.index, complete: receiver.progress().complete };
+    },
+  };
+}
+
+/** 两帧之间的纯函数检查：块哈希与大小必须与声明一致（不依赖 receiver）。 */
+export function verifyChunkFrame(frame) {
+  if (frame?.type !== CHUNK) return { ok: false, code: 'XFER_FRAME_UNEXPECTED' };
+  if (!Number.isInteger(frame.index) || frame.index < 0) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+  if (!isHex64(frame.sha256)) return { ok: false, code: 'XFER_CHUNK_HASH_INVALID' };
+  const data = Buffer.from(String(frame.data ?? ''), 'base64');
+  if (data.length !== frame.size) return { ok: false, code: 'XFER_CHUNK_LENGTH_INVALID' };
+  const digest = createHash('sha256').update(data).digest('hex');
+  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),
+  };
+}