@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/session-sync.js

@@ -7,31 +7,18 @@ import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-
 import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, msg } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
-/** 2c session-sync PUT /sync/blobs/:hash per-blob upload cap. A snapshot blob is ONE file's bytes, bounded by core's
- *  DEFAULT_SNAPSHOT_BOUNDS (the whole tree ≤ 64 MiB), so a single blob can never exceed the per-snapshot total — this
- *  cap (= 64 MiB, ≥ that bound) is the reject-not-OOM ceiling: the blob body is read with a running size guard that
- *  413s the instant it is exceeded (NEVER buffered unboundedly), the §5 "reject, not OOM" requirement. Larger than
- *  MAX_BODY (8 MiB, the JSON cap) on purpose — a blob is binary file content, not a JSON request. */
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
-/** 2c session-sync P1d-β: the per-LINE cap on the Phase-B NDJSON entry stream — ONE entry must fit in this (the §1.5
- *  ruling: a session_event row is ≤~20KB because core offloads >20K tool results, so a few MiB is a generous ceiling).
- *  A line exceeding it → 413 (reject, not OOM): a single oversized entry would otherwise force an unbounded line buffer. */
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
-/** 2c session-sync P1d-β: the Phase-B entry batch size — entries are fed to `appendBatch` in chunks of this many, so
- *  in-flight memory is O(batch), not O(session). 500 mirrors the PULL stream's keyset page size (one bounded txn). */
 const SYNC_IMPORT_BATCH = 500;
-// SHA256_HEX_RE = 64 lowercase-hex chars, a sha256 content-address (the blob hash + the GET :hash param shape).
 import { SHA256_HEX_RE } from "../../digest-form.js";
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
-    /** 租约续期 —— entries 上传腿每收一批就调,所以大会话的长上传不会被误判成陈旧。 */
     const touchImportLease = (sessionId) => {
         const cur = importLeases.get(sessionId);
         if (cur)
             importLeases.set(sessionId, { ...cur, at: Date.now() });
     };
-    /** Drop a finished/aborted staging from the in-process maps + release its per-session import lease. Idempotent. */
     const cleanupStaging = (stagingId) => {
         const p = pendingStagings.get(stagingId);
         if (p)
@@ -45,27 +32,13 @@ export async function handleSessionSync(req, res, url, ctx) {
     await handleSessionSyncBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */
 async function handleSessionSyncBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, readRawBody, safeDecode, sessionOwnerScopeForWrite, rateLimited } = ctx.helpers;
     const { pendingStagings, importLeases, touchImportLease, cleanupStaging } = ctx.local.sessionSync;
-    // ── 2c session-sync (P1d) — the cloud as a SYNC PEER (sema-internal server/docs/DESIGN-session-sync.md §15 + §5–§10) ──────────────
-    // The real 2c topology is TWO PROCESSES (the local shell's local backend + this cloud service); these routes let
-    // the local peer PULL a session's whole state out of the cloud or PUSH its own in. Both halves are STREAMING
-    // implementations that fan out across ALL four session subsystems (entries + fileSnapshot + sessionPolicy +
-    // resumeAnchor) IN-ROUTE (PULL = exportSessionManifest + keyset-paged NDJSON; PUSH = two-phase staging re-running
-    // the §8 fanout below) — they need the WHOLE backend (deps.backend), not the individual stores. The whole-bundle
-    // exportSession/importSession orchestrators are NOT called here (#51 死码判定,见 src/session-sync.ts 顶注). Every route is
-    // owner-gated like fork/delete (§9): a PULL 404s a non-owner (no exfiltration oracle); a PUSH re-stamps the
-    // imported owner to the AUTHENTICATED principal (the bundle's owner is ignored). 501 when no durable session
-    // store is wired (parity with fork: capability says yes ⟺ the route resolves).
     {
         const sm = /^\/v1\/sessions\/([^/]+)\/sync\/(manifest|entries|import|plan|blobs(?:\/([^/]+))?|snapshots\/([^/]+)\/blobs\/([^/]+)|import\/([^/]+)\/entries)$/.exec(url);
         if (sm) {
-            // Durable-store gate (501) FIRST is wrong for an auth oracle, so AUTH-FIRST below mirrors fork/delete; but the
-            // backend is needed even to know the owner, so we gate on it up front and rely on AUTH being checked before
-            // any store touch. ownerOf is the existence/authz primitive every branch uses.
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             if (!deps.backend || !ownerOf) {
                 sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
@@ -75,44 +48,32 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
-            } // auth-first
+            }
             const sessionId = safeDecode(sm[1]);
-            // uuid ANY version — a v4-keyed legacy shell session must be pushable (it was
-            // creatable via the lenient submit face); crafted-id classes (LIKE metachars, over-long) still shut out.
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
-            // Two owner gates, BOTH 404 a foreign session with no existence oracle:
-            //  • PULL (read the cloud's session): the session MUST exist (undefined⇒404) AND the caller must own it.
-            //  • PUSH/PLAN (write into / plan against the cloud): own-or-FRESH — `undefined` (no such session yet, the
-            //    caller is about to import it) OR the caller's own ⇒ allowed; a DIFFERENT owner ⇒ 404.
             const owner = await ownerOf(sessionId);
             const ownsOrFleet = (o) => scope.fleetWide || o === scope.gateOwner;
             const pullGateOk = () => {
                 if (owner === undefined) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                } // must exist to pull
+                }
                 if (!ownsOrFleet(owner)) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                } // no oracle
+                }
                 return true;
             };
             const pushGateOk = () => {
                 if (owner !== undefined && !ownsOrFleet(owner)) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                } // foreign → no oracle
-                return true; // undefined (fresh, caller will import) OR own/fleet
+                }
+                return true;
             };
-            // GET …/sync/manifest — PULL: export the MANIFEST (entry IDS + per-snapshot relPath→blobHash + policy +
-            // anchors + leafId), NO entry payloads and NO blob bytes (P1d-α §1.5/§5/§15: bounded memory — the entries
-            // stream separately via …/sync/entries). The local peer diffs entryIds → classifySyncRelationshipByIds, then
-            // pulls the entries (NDJSON) + only the blobHashes it lacks. exportSessionManifest returns null ONLY for "no
-            // such session" (the owner gate above already proved existence+ownership, so a null here is a raced delete →
-            // 404).
             if (sm[2] === "manifest" && req.method === "GET") {
                 if (!pullGateOk())
                     return;
@@ -120,22 +81,13 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 if (out === null) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return;
-                } // raced delete after the gate
+                }
                 sendJson(res, 200, { manifest: out.manifest });
                 return;
             }
-            // GET …/sync/entries[?afterSeq=N] — PULL the entry PAYLOADS as an NDJSON stream (P1d-α §1.5/§5/§15). The store
-            // seam keyset-PAGES the durable log (one pooled query per batch → bounded server memory; a slow client can't
-            // pin a connection), and we apply HTTP backpressure (await drain on a full socket buffer) so a slow consumer
-            // can't OOM the server either. The frame: a {"__sync":"begin",…} header line, then one JSON entry per line,
-            // then a {"__sync":"end","count":N} TRAILER line — a MISSING trailer signals a truncated stream to the client.
             if (sm[2] === "entries" && req.method === "GET") {
                 if (!pullGateOk())
                     return;
-                // afterSeq (optional resume cursor): a non-negative integer; reject anything else as a 400 (never a NaN
-                // cursor). It is the BACKEND-NATIVE durable `seq` cursor (yield entries whose seq > afterSeq) — a resume is
-                // always against the SAME backend, so the seq base (durable `seq` column vs. local 0-based index) needn't be
-                // portable across backends.
                 const afterSeqRaw = new URL(req.url ?? "", "http://x").searchParams.get("afterSeq");
                 let afterSeq;
                 if (afterSeqRaw !== null) {
@@ -150,16 +102,13 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 if (!stream) {
                     sendError(res, 501, "capability.session_store_required", "session entry streaming requires a durable session store");
                     return;
-                } // method absent
+                }
                 const it = await stream(sessionId, afterSeq === undefined ? undefined : { afterSeq });
                 if (it === null) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return;
-                } // raced delete after the gate
-                // Headers committed — past this point we cannot change the status; a mid-stream error just ends the body
-                // WITHOUT the trailer, which the client reads as truncation.
+                }
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
-                // backpressure-aware write: if the socket buffer is full (write returns false), await 'drain' before the next.
                 const write = async (line) => { if (!res.write(line))
                     await once(res, "drain"); };
                 let count = 0;
@@ -169,21 +118,15 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         await write(`${JSON.stringify(entry)}\n`);
                         count++;
                     }
-                    await write(`${JSON.stringify({ __sync: "end", count })}\n`); // trailer — its ABSENCE = truncated stream
+                    await write(`${JSON.stringify({ __sync: "end", count })}\n`);
                     res.end();
                 }
                 catch (e) {
-                    // The iterable (or a write) threw mid-stream. Headers are already sent, so we can't 4xx/5xx — just END the
-                    // body. The MISSING trailer tells the client the stream was truncated. Log it for the operator.
                     deps.logger?.error?.("sync entries stream failed", { sessionId, count, error: msg(e) });
                     res.end();
                 }
                 return;
             }
-            // GET …/sync/snapshots/:key/blobs/:hash — PULL one content-addressed blob's RAW bytes. The SCOPE CHECK is the
-            // security boundary: a content-addressed blob is shared across sessions, so we must NOT let an owner fetch an
-            // arbitrary hash (another tenant's file content). We require the requested :hash to be a value in THIS
-            // session's snapshot `:key` manifest — a session owner may only fetch blobs ITS OWN snapshots reference.
             if (sm[4] !== undefined && req.method === "GET") {
                 if (!pullGateOk())
                     return;
@@ -199,8 +142,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 const fs = deps.fileSnapshotStore;
                 const manifest = await fs?.exportManifest?.(sessionId, key);
-                // null manifest (no such snapshot) OR the hash is not referenced by it ⇒ 404 (the scope boundary — never a
-                // blind content-addressed read of an unscoped hash).
                 if (!manifest || ![...manifest.values()].includes(hash)) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
@@ -214,16 +155,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 res.end(Buffer.from(bytes));
                 return;
             }
-            // PUT …/sync/blobs/:hash — PUSH one content-addressed blob INTO the cloud's snapshot store, ahead of the bundle
-            // import (§5 streamed negotiation: the local peer GETs the manifest, then PUTs only the blobs the cloud lacks).
-            // own-or-FRESH gate. Verify sha256(body)===:hash (the content-address is the integrity guarantee; a transfer
-            // crosses the net) BEFORE storing. The body is read with a PER-BLOB cap (reject-not-OOM).
             if (sm[3] !== undefined && req.method === "PUT") {
-                // 缝合审 S7:限流对**字节写入**要对称。同族的 `POST /v1/attachments`(也是「客户端把任意字节
-                // 写进持久存储」)走 rateLimited;这条腿此前只有 own-or-fresh 门 —— 单个 blob 有 cap,但**次数
-                // 不封**,持合法 principal 的 caller 可全速灌存储/带宽。attachments 那段注释自己写着
-                // 「上限=server 权威…sync-blob 同姿」:尺寸口径同姿了,限流口径没跟上。
-                // 只加 rateLimited,**不加** quotaExceeded —— blob 上传不跑模型,与 runs.ts 的 detach/stop 同姿。
                 if (rateLimited(req, res))
                     return;
                 if (!pushGateOk())
@@ -238,12 +170,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable snapshot store");
                     return;
                 }
-                const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES); // 413s mid-stream if it exceeds the cap (no unbounded buffer)
-                // (a): SQL-default blob store cap — 413 typed, NOT the 502 the store's never-throw result would become
-                // (502 = "retry"; an over-cap blob can never land, so retrying it forever is the wrong contract).
+                const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES);
                 if (deps.snapshotBlobSqlCapBytes !== undefined && body.byteLength > deps.snapshotBlobSqlCapBytes) {
-                    // 复审 D-F1/B-F2:归一漏网(多行体,旧门正则扫不到)——A6 迁移到 sendError 后此站点由
-                    // errorCode 必填位置参数保结构(不再靠源级反射门兜底)。
                     sendError(res, 413, "blob_too_large_for_sql", `blob of ${body.byteLength} bytes exceeds this deployment's SQL snapshot-blob cap (${deps.snapshotBlobSqlCapBytes} bytes — TiDB's txn-entry-size-limit is the low wall at 6MiB by default; the mysql-protocol packet limit sits above it) — configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment lifted those limits`);
                     return;
                 }
@@ -251,29 +179,17 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.hash_mismatch", "blob hash mismatch");
                     return;
                 }
-                // core 1.142.0: putBlob is a fail-closed never-throw seam — a backend write error (e.g. a MinIO non-2xx PUT)
-                // is {ok:false}, NOT a thrown 500. Surface it as 502 so the local peer retries rather than treating the bundle
-                // blob as durably stored when it isn't.
                 const put = await fs.putBlob(hash, new Uint8Array(body));
                 if (!put.ok) {
                     sendError(res, 502, put.error.code, "blob store write failed");
                     return;
                 }
-                res.writeHead(204).end(); // no body
+                res.writeHead(204).end();
                 return;
             }
-            // POST …/sync/import — PHASE A (PUSH, P1d-β §15.2): a SMALL JSON body — `{entryIds, snapshots, policy, anchors,
-            // resolution?}` — NO entries (they stream in Phase B). Classify (§7), pre-check blob presence (§10), guard the
-            // §4 import-vs-import lease + the active-run window, then mint a stagingId, open a StagingHandle, and park the
-            // Phase-A metadata. Returns `200 {stagingId, relation}`. The entries-inline whole-bundle import is GONE (the
-            // §1.5 OOM offender) — Phase B streams the log into the shadow id so server memory is bounded by batch.
             if (sm[2] === "import" && req.method === "POST") {
                 if (!pushGateOk())
                     return;
-                // sessionMirror 观测面(裁定 (c),论证在 ServiceDeps.sessionMirrorRuling 注释):Phase A
-                // 到达 = 一次镜像 push 落到本 server 的时点信号。该 principal 若处 org 治理态(required=true),记
-                // audit 日志 + metric,把「治理生效」与「到达流」在运营面对上——这是 server 侧唯一诚实可观测的面
-                // (没到达的会话 server 看不见,真执法在壳)。fire-and-forget + 双层吞错:观测绝不拖慢/拖垮 sync。
                 if (deps.sessionMirrorRuling && !scope.fleetWide && scope.gateOwner !== null) {
                     const auditPrincipal = scope.gateOwner;
                     void deps.sessionMirrorRuling(auditPrincipal).then((mirror) => {
@@ -295,8 +211,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.invalid_json", "invalid JSON body");
                     return;
                 }
-                // Shape validation (§10): entryIds must be a string[]; snapshots an array of {key:string, manifest:array};
-                // policy/anchors arrays. A malformed shape → 400 (never a 500 from a downstream TypeError).
                 if (!Array.isArray(body.entryIds) || !body.entryIds.every((x) => typeof x === "string")) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
@@ -311,56 +225,19 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const resolution = body.resolution;
-                // 🔴 方案 B(黑板 [1701]→[1702]→[1707] 三端对齐):**可选** `logDigest` = 源端整条日志的内容摘要
-                // (core 1.414 `sessionLogDigest`)。老客户端不送 ⇒ 行为与此前逐字相同。坏形**不拒**,当作没送
-                // (core 口径:摘要不符/不可比永远不得变成 error / 409 / 拒绝同步 —— 它只意味着"多干一趟活")。
                 const srcLogDigest = typeof body.logDigest === "string" && body.logDigest.length > 0 ? body.logDigest : undefined;
                 const entryIds = body.entryIds;
                 const snapshots = body.snapshots;
                 const policy = body.policy;
                 const anchors = body.anchors;
-                // §7 classify (BEFORE issuing a stagingId): dst current ids → classifySyncRelationshipByIds. A fork/stale
-                // without overwrite-dst → 409 (no stream needed). `identical` → 200 {relation:"identical"} (no Phase B; the
-                // snapshot/policy/anchor replay is idempotent and not strictly needed — the dst already holds this log; the
-                // shell may re-push with no consequence). NB the AUTHORITATIVE re-classify is in commit() (the TOCTOU close).
                 const dstIds = (await deps.sessionStorage.listEntryIds?.(sessionId)) ?? null;
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
                 if ((relA.relation === "fork" || relA.relation === "stale") && resolution !== "overwrite-dst") {
                     sendError(res, 409, "conflict", "sync conflict", { relation: relA });
                     return;
                 }
-                // 🔴 内容判据(方案 B 的 Phase A 半场):`identical` 只说明 **id 集合**相等。源端内容在 Phase A 还没上传,
-                // 所以这里只能靠调用方送来的 `logDigest`;拿目的端自己的日志算一次摘要跟它比。
-                // ⚠️ 目的端全量读**只在这条路上做**(要短路、且调用方送了摘要)—— 成本只花在它能改变结论的地方。
-                // 三态:相等 ⇒ 可以短路;不等 ⇒ **不短路**(照常开 staging 走完整同步);判不可比(scheme 不同/
-                // 对端没送)⇒ 同样**不短路**,退回完整同步 = 安全方向。
                 let payloadVerified = false;
                 let digestSaysDiffer = false;
-                // ── 这条路依赖的那条**性质**,以及它为什么由依赖下限 + 一条行为测试守着(不是由版本名判断守着)──
-                // 本路要求:**同一份日志,内存形与 JSON 往返形必须同摘要**。因为它比的正是「客户端从**内存**算的
-                // `logDigest`」对「server 从**已持久化**(JSON 往返过)的日志算的摘要」。
-                // `sessionLogDigest` 的 **v1** 不满足它:v1 走引擎那个规范化序列化器,**刻意**区分 `{a: undefined}`
-                // 与 `{}`,而 core 自己成规模产 own-key=undefined 的 entry(清除标签、无 data 的 custom entry)
-                // ⇒ 两形必然不等 ⇒ **永不短路**,却看起来像在工作(症状只是「Phase B 总在跑」,查不出原因):
-                // 纯成本、零收益,还多一次目的端全量读。core 黑板 [1709] 明确「别接 v1」,1.415.0 改算法并升 scheme v1→v2。
-                //
-                // 🔴 我一开始写的是 `SESSION_LOG_DIGEST_SCHEME !== "sema-log-v1"` 这道**名字门**。升上 1.415 后
-                // `tsc` 直接判它恒真(core 把 scheme 收成了字面量类型)—— 而这提醒了一件更要紧的事:名字门本来就
-                // **守不住这条性质**。它只认识"v1 这个名字",对将来任何一个同样破坏往返稳定性的 v3 一样放行。
-                // ⇒ 改成两道**真守得住**的:
-                //   ① **依赖下限** `@sema-agent/core: ^1.416.0`。⚠️ package.json 是 JSON、写不了旁注,所以"这条下限是
-                //      承重的、不是随手升的"记在两处:**本注释** + `CHANGELOG.md` 1.277.0/1.277.1 两条。
-                //      降回更低的下限,tsc 不会有任何抱怨 —— 拦它的是 ② 那两道行为门。
-                //   ② **行为门**(都在 `test/sync-content-digest.test.ts`),两条**方向相反**、缺一不可:
-                //      · **往返稳定**:同一份含 own-key=undefined 的日志,内存形与 JSON 往返形必须同摘要。
-                //        它坏 ⇒ **永不短路**(纯成本,安全方向)。core 摘要 v1 不满足它(v1 刻意区分 `{a:undefined}`
-                //        与 `{}`,而 core 成规模产这种 entry),黑板 [1709] 明确「别接 v1」。
-                //      · 🔴 **防撞**:内容不同 ⇒ 摘要必须不同,**按深度枚举**(坏值与真实内容同级)。
-                //        它坏 ⇒ **错误短路** = 静默丢数据,方向与上面相反、后果严重得多。core 摘要 **v2** 不满足它
-                //        (逐键降级只做在 entry 顶层,而真实内容在深度 ≥2 ⇒ 一个 bigint 吃掉同级全部内容),
-                //        1.416.0 / v3 修复(黑板 [1714])。
-                //      两条钉的都是**性质**、不是版本名 —— 任何 scheme 再破坏其一都会红。
-                //      (教训同形于 core 的 RB-149:源码/名字级判据挡的是写法,不是行为。)
                 if (relA.relation === "identical" && srcLogDigest !== undefined) {
                     const dstEntries = await deps.sessionStorage.exportEntries?.(sessionId).catch(() => null) ?? null;
                     const dstDigest = dstEntries === null ? undefined : sessionLogDigest(dstEntries);
@@ -370,16 +247,10 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         else
                             digestSaysDiffer = true;
                     }
-                    // 不可比 ⇒ 两个标志都保持 false ⇒ 走下面「不短路」那一支(退回完整同步)
                     if (!payloadVerified)
                         digestSaysDiffer = true;
                 }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
-                    // 对抗复查 A-2(CRITICAL):identical 不能裸短路——若上一轮 commit 后 snapshot/policy/anchor 重放
-                    // 失败(422),entries 已落库,重试的 Phase A 就落在这里;裸 200 会把「对话已同步但文件树缺失」
-                    // 焊死成永久分裂(Phase B 的重放永远不再运行)。identical 时把附随物幂等重放(snapshot=
-                    // content-addressed importManifest,已存在=no-op;policy/anchor put=幂等),失败=同款 422,
-                    // 客户端 re-PUT blob 再重试——自愈闭环。
                     const importFaceIdentical = fileSnapshotImportFace(deps.fileSnapshotStore);
                     if (importFaceIdentical && deps.fileSnapshotStore?.getBlob && snapshots.length > 0) {
                         const getBlobA = (h) => deps.fileSnapshotStore.getBlob(h);
@@ -392,38 +263,19 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         }
                     }
                     const opOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals);
-                    // #137 ①:等内容跳过(replayPolicyRecords)——这条腿在**每次** identical 重推上都跑,
-                    // 无条件 putRules 会把 rev(operator 乐观锁 CAS 令牌)按重推次数推着走。
                     if (deps.sessionPolicyStore)
                         await replayPolicyRecords(deps.sessionPolicyStore, sessionId, policy, opOk);
                     const importingP = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                     if (deps.resumeAnchorStore)
                         for (const a of anchors)
                             await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingP);
-                    // 🔴 措辞诚实化(2026-07-25,深挖第一轮 B2/B3/B4/G1):`identical` 的判据是 **entry id 集合相等**,
-                    // 分类器(`classifySyncRelationshipByIds`)**从不看载荷/父子结构** —— 而 entry id 是 uuidv7、
-                    // **不是内容寻址**,所以「同 id 异载荷」结构上完全可能。此时 entries 被**整段跳过**,客户端拿到 200,
-                    // 目的端却仍是它自己那份内容(探针用真 HTTP 复现过:本地改过内容再 push,云端保持原样、200)。
-                    // 现在把判据写进响应(`basis`)并显式声明**未验证载荷**,这样客户端不会把它读成"内容已同步"。
-                    // ✅ 状态更新(2026-08-05,[2557] 2-i 核账):上面说的「真修」——Phase A 拿内容摘要——**已经落了**
-                    // (`logDigest` 就在本函数上方,三态钉=fanout-characterization §H2/F3);commit 半场的载荷判据也齐
-                    // (identical=照常改写、fast_forward 分叉=409,见 session-sync-content.ts)。仍到不了这里的只剩
-                    // **不送 digest 的老客户端**(按设计永久保留的老路,现状钉=G1)——对它们 `basis:"entry-ids"` 的
-                    // 未验声明就是全部真相。
                     sendJson(res, 200, {
                         relation: "identical",
-                        // 判据如实:调用方送了可比摘要且相等 ⇒ 内容**真的**验过;否则仍只是 id 集合相等。
                         basis: payloadVerified ? "entry-ids+digest" : "entry-ids",
                         payloadVerified,
                     });
                     return;
                 }
-                // §4 active-run guard (don't drop a live append) + per-session import lease (don't let two staged imports race
-                // to commit the same session). Both 409.
-                // `runStore?.` 的可选链不是守卫豁免面(鲁棒性批5 #7 亲验定性,2026-08-06):runStore 仅在
-                // **backend 整体缺席**时才 undefined(tidb/pg/local 三形态的 backend.run() 全都在,main.ts:378),
-                // 而 backend 缺席时本路由的 Phase A 已在 `beginImportStaging` 探测处硬 501(capability.session_store_
-                // required)——「守卫被跳过而 sync 仍可达」的组合按构造不存在(能力面与路由解析同真值)。
                 const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeTaskId) {
                     sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId });
@@ -431,34 +283,22 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 const heldLease = importLeases.get(sessionId);
                 if (heldLease) {
-                    // 🔴 数值守卫而不是直接乘:任何**早于这个字段**的 config 对象(旧部署配置、精简的测试 harness)
-                    // 会让它是 `undefined` ⇒ `undefined * 1000 = NaN` ⇒ `NaN > 0` 为假 ⇒ **接管静默不发生**,
-                    // 自愈通道在不报错的情况下消失。实测撞到过(一份最小 config 的探针 harness)。缺省取与 config
-                    // 同一个默认值(600s),而不是 0 —— 0 的语义是"明确关掉",不该由"漏配"来选中它。
                     const staleSecRaw = deps.config.syncImportLeaseStaleSec;
                     const staleSec = typeof staleSecRaw === "number" && Number.isFinite(staleSecRaw) ? staleSecRaw : 600;
                     const staleMs = staleSec * 1000;
                     const ageMs = Date.now() - heldLease.at;
                     if (staleMs > 0 && ageMs >= staleMs) {
-                        // 接管:上一个持有者已经 staleMs 没有任何活动(既没上传 entries 也没 commit)⇒ 判它死了。
-                        // 先清掉它的 staging(否则那份 staged 行会留成孤儿),再让本次 Phase A 正常继续。
                         deps.logger?.warn?.("sync_import_lease_taken_over", { sessionId, ageMs, staleMs, stagingId: heldLease.stagingId });
                         cleanupStaging(heldLease.stagingId);
-                        importLeases.delete(sessionId); // cleanupStaging 只在 pendingStagings 里还有它时才删租约,这里兜底
+                        importLeases.delete(sessionId);
                     }
                     else {
-                        // 错误文案点明**会自愈**:此前的措辞让客户端以为是永久状态,而它其实等一会儿就能重试。
                         const retryAfterSec = staleMs > 0 ? Math.max(1, Math.ceil((staleMs - ageMs) / 1000)) : undefined;
                         sendError(res, 409, "import_in_flight", "an import is already in flight for this session"
                             + (retryAfterSec !== undefined ? ` (a stalled holder is taken over after ${staleSec}s of inactivity; retry in ~${retryAfterSec}s)` : ""), retryAfterSec !== undefined ? { retryAfterSec } : undefined);
                         return;
                     }
                 }
-                // §10 blob-presence pre-check (BEFORE staging): every referenced blobHash must be present in the cloud's OWN
-                // snapshot store (blobs were pre-PUT). A missing one → 422 (PUT it, then retry) — fail FAST so we never open a
-                // staging that can only fail at commit. Uses the store's hasBlobs (a single SQL INDEX probe — finding 12) NOT
-                // a full getBlob GET-per-hash (under MinIO that would download + re-hash every ≤64 MiB object just to test
-                // presence). Feature-detect hasBlobs; if a store lacks it, fall back to getBlob (parity for older stores).
                 const fss = deps.fileSnapshotStore;
                 const canImportSnapshots = fileSnapshotImportFace(fss) !== undefined;
                 if (canImportSnapshots) {
@@ -484,15 +324,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         }
                     }
                 }
-                // importingPrincipal (§9) + operatorOk (E6 tighten-only) — mirror the v1 fixes; applied at commit (policy replay).
                 const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                 const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals);
-                // Mint the stagingId TOKEN (the route supplies it, NOT the store) + open the handle + take the lease + park
-                // the metadata. Phase B drives it; abandoned ones are reaped (durable rows) / dropped on restart. The token is
-                // a SHORT random hex (8 bytes = 16 chars), NOT a full uuidv7: the staging id is `${sessionId}#stg-${token}` and
-                // session_event.session_id is VARCHAR(64) — a 36-char uuidv7 session id + "#stg-" (5) leaves 23 chars, so a
-                // 16-char token fits (and is collision-resistant for the few in-flight stagings of ONE session — the lease
-                // already serializes them per session). randomBytes is unguessable (it rides the URL the client gets back).
                 const token = randomBytes(8).toString("hex");
                 const handle = deps.sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
@@ -504,11 +337,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
             }
-            // POST …/sync/import/:stagingId/entries — PHASE B (PUSH, P1d-β §15.3): stream the entry log as an NDJSON request
-            // body into the staged shadow id (bounded memory — line buffer + batch), driving core's STREAMING import gate
-            // ({@link StreamingImportValidator}) ONE entry per line, then `finish()` at stream end (exactly-one-root +
-            // leaf-resolvable) → commit (the atomic swap) → replay snapshots/policy/anchors. Re-POSTing the same stagingId is
-            // idempotent (appendBatch dedups; the commit re-runs). sm[6] = the stagingId.
             if (sm[6] !== undefined && req.method === "POST") {
                 const stagingId = safeDecode(sm[6]);
                 if (stagingId === null) {
@@ -516,8 +344,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const pending = pendingStagings.get(stagingId);
-                // A wrong/foreign/already-finished stagingId → 404 (no oracle). It must also belong to THIS url's session and
-                // to the caller (the principal that opened it), unless the caller is fleet-wide (ops on-behalf).
                 if (!pending || pending.realSessionId !== sessionId) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
@@ -526,24 +352,15 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                const getBlob = (h) => deps.fileSnapshotStore.getBlob(h); // cloud's OWN store
+                const getBlob = (h) => deps.fileSnapshotStore.getBlob(h);
                 const importFaceB = fileSnapshotImportFace(deps.fileSnapshotStore);
-                // ── Stream the NDJSON request body → core's StreamingImportValidator per line → batched appendBatch (bounded
-                //    memory: line buffer + batch). The streaming validator IS the single invariant gate (unique ids /
-                //    parent-before-child / structural refs / one-root / leaf-resolvable) — core 1.143.0 — so the service
-                //    no longer re-states ANY of those rules (no ad-hoc Tier-1 pre-check, no Tier-2 read-back-and-re-validate;
-                //    the invariant gate belongs to core and the service does not duplicate it). `step()` throws SessionError("invalid_session") on a per-entry violation;
-                //    `finish()` throws on the end-of-stream invariants. The route keeps ONLY the TRANSPORT-level guards (the
-                //    per-line byte cap → 413, JSON parse → 400, and the object/string-id shape so a `null`/non-object line maps
-                //    to a typed 422 instead of an unmapped TypeError); these are NOT session-tree invariants. ──
                 const validator = new StreamingImportValidator();
-                let lineBuf = ""; // the partial-line accumulator (bytes counted against the per-line cap)
+                let lineBuf = "";
                 let pendingBatch = [];
                 const flush = async () => { if (pendingBatch.length) {
                     await pending.handle.appendBatch(pendingBatch);
                     pendingBatch = [];
                 } };
-                // Map a transport-level violation to a typed 4xx WITHOUT committing (the handle's staged rows are abandoned → reaped).
                 class PrecheckError extends Error {
                     status;
                     constructor(status, msg) {
@@ -551,21 +368,16 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         this.status = status;
                     }
                 }
-                const streamedIds = new Set(); // A-3: bind the actual stream to Phase A's declaration
+                const streamedIds = new Set();
                 const onEntry = (e) => {
                     if (!e || typeof e !== "object" || typeof e.id !== "string")
                         throw new PrecheckError(422, "malformed entry (missing id)");
                     streamedIds.add(e.id);
-                    validator.step(e); // core's invariant gate, one entry at a time (oldest-first) — throws SessionError on a tree violation
+                    validator.step(e);
                 };
-                // 对抗复查 A-7(HIGH):per-chunk Buffer.toString("utf8") mangles a MULTI-BYTE character that
-                // straddles a network chunk boundary (each half decodes to U+FFFD; the JSON often stays valid →
-                // the payload is SILENTLY rewritten — CJK content is the common casualty). StringDecoder holds the
-                // partial sequence across chunks — the standard Node fix.
                 const utf8 = new StringDecoder("utf8");
                 try {
                     for await (const chunk of req) {
-                        // 租约续期(见 importLeases 旁注):上传本身就是活性证据 —— 大会话的长上传不该被判成"持有者死了"。
                         touchImportLease(pending.realSessionId);
                         lineBuf += utf8.write(chunk);
                         if (Buffer.byteLength(lineBuf, "utf8") > SYNC_NDJSON_LINE_MAX_BYTES)
@@ -575,7 +387,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                             const line = lineBuf.slice(0, nl).trim();
                             lineBuf = lineBuf.slice(nl + 1);
                             if (line.length === 0)
-                                continue; // tolerate blank lines / a trailing newline
+                                continue;
                             let e;
                             try {
                                 e = JSON.parse(line);
@@ -589,8 +401,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                                 await flush();
                         }
                     }
-                    // any trailing partial line (no final newline) is still a complete entry to honor.
-                    lineBuf += utf8.end(); // flush a dangling partial sequence (A-7)
+                    lineBuf += utf8.end();
                     const tail = lineBuf.trim();
                     if (tail.length > 0) {
                         let e;
@@ -604,21 +415,12 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         pendingBatch.push(e);
                     }
                     await flush();
-                    // End-of-stream invariants (exactly-one-root + leaf-resolvable) — finish() throws SessionError on violation.
                     validator.finish();
-                    // 对抗复查 A-3(HIGH):the streamed tree must BE the Phase-A-declared one — same count, same id set.
-                    // Without this, a caller could open a staging with ids=A (snapshots/anchors parked against A) and
-                    // stream a different-but-valid tree B to commit; the classification and parked artifacts would
-                    // silently reference the wrong log. Set equality (order is core-validated separately).
                     if (streamedIds.size !== pending.declaredEntryIds.length || !pending.declaredEntryIds.every((id) => streamedIds.has(id))) {
                         throw new PrecheckError(422, "streamed entries do not match the Phase-A declared entryIds");
                     }
                 }
                 catch (e) {
-                    // A transport-level PrecheckError carries its own status; a core SessionError("invalid_session") (a step()
-                    // or finish() invariant violation) maps to 422. Either way: drop the staged rows + the lease/map entry up
-                    // front (a malformed stream won't be retried under THIS stagingId; the client re-opens Phase A). The reaper
-                    // is the backstop if the abort itself fails. Anything else re-throws to the outer handler.
                     if (e instanceof PrecheckError) {
                         await pending.handle.abort().catch(() => undefined);
                         cleanupStaging(stagingId);
@@ -631,20 +433,10 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         sendError(res, 422, "invalid_entries", "staged session log failed validation");
                         return;
                     }
-                    // 对抗复查 A-4(HIGH):a NON-validation exception (storage blip, dropped connection) used to re-throw
-                    // with the lease + pendingStagings entry INTACT — the outer handler 500s, and every later Phase A for
-                    // this session 409s `import_in_flight` until the process restarts (the DB reaper can't clear the
-                    // in-memory Set). Clean up here too: abort the staged rows (best-effort; reaper backstops) + release
-                    // the lease, so the client's retry re-opens Phase A instead of wedging. Then re-throw for the 500.
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
                     throw e;
                 }
-                // 对抗复查 A-6(HIGH,route 半件):re-check the ACTIVE-RUN guard right before commit — Phase A's check
-                // can be minutes stale by the time the stream finishes, and an overwrite-dst commit would purge a log a
-                // LIVE run is appending to. (The owner half lives in the store commit's in-txn re-classify + FOR UPDATE;
-                // a residual sub-second TOCTOU between this check and the txn remains — documented, not load-bearing for
-                // correctness since the commit txn serializes against appends via FOR UPDATE.)
                 const activeAtCommit = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeAtCommit) {
                     await pending.handle.abort().catch(() => undefined);
@@ -652,33 +444,17 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 409, "session_active", "session started an active run while the import streamed; sync after it settles", { activeTaskId: activeAtCommit });
                     return;
                 }
-                // #137 ② 能力预检(fail-loud,[2195] 判据:保护型能力缺席=fail-closed):consent 了 overwrite
-                // 而 policy 店无 purge seam ⇒ 在 commit **之前**干净中止(此刻零写入落地),绝不静默留混合态。
-                // 只看 resolution 不看 relation(commit 的 in-txn re-classify 还没跑):保守方向——你要求了
-                // overwrite 而这套部署擦不动,哪怕最终 re-classify 判 fresh 也先拒,拒因里给了无损重跑姿势。
                 if (pending.resolution !== undefined && overwriteWipeIncapable(deps.sessionPolicyStore)) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
                     sendError(res, 501, "capability.policy_purge_required", "overwrite-dst cannot proceed: this deployment's session-policy store has no deleteBySession purge seam, so the destination's stale policy rows cannot be wiped and the import would land a MIXED state (the source's conversation plus the destination's leftover policy rows, which keep gating). Upgrade the policy store (every in-tree store carries deleteBySession since core 1.423), or re-run without resolution overwrite-dst");
                     return;
                 }
-                // ── commit (the atomic swap) → wipe (overwrite-dst) → replay snapshots/policy/anchors → cache evict → release lease ──
                 try {
                     const committed = await pending.handle.commit(pending.owner, pending.resolution ? { resolution: pending.resolution } : undefined);
-                    // #137 ②(死码 ⓪ 擦除步的活路由移植,判据钉=fanout-characterization L2):consented
-                    // overwrite-dst = keep-source ⇒ 在重放**之前**擦掉目的端遗留的 policy/anchor/快照行,否则
-                    // 悬空 anchor 指向已 purge 的 entry、被放弃分支的 policy 行继续 gating、共享 key 快照因
-                    // importManifest create-once 永远留着目的端字节。条件按 commit 权威 relation 收窄:fresh 不擦
-                    // (B5 钉:注册过但零 entry 的目的端,原有附随物原地留存)、fast_forward 不擦(同支延长,无
-                    // 被放弃分支)。崩溃残余(commit 与 wipe 之间死进程 ⇒ 重试落 identical 支无 wipe)在
-                    // wipeSessionAttendants 的 doc 注如实记录——窗口窄于修前(修前=遗留行恒存活)。
                     if (pending.resolution === "overwrite-dst" && (committed.relation === "fork" || committed.relation === "stale")) {
                         await wipeSessionAttendants({ fileSnapshotStore: deps.fileSnapshotStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
                     }
-                    // ① snapshots — content-addressed import (idempotent). importManifest never throws → a {ok:false} is a
-                    //    fail-closed 422 (a blob the Phase-A presence check couldn't catch — corrupted in transit). Note: the
-                    //    ENTRIES are already committed (the swap), so a snapshot failure here means the conversation synced but a
-                    //    file tree did not — we surface 422 so the client re-PUTs the blob and re-POSTs (idempotent).
                     if (importFaceB) {
                         const importManifest = importFaceB.importManifest;
                         for (const snap of pending.snapshots) {
@@ -690,33 +466,24 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                             }
                         }
                     }
-                    // ② policy — replay each record; the E6 tighten-only gate applies unless the importer is a verified operator.
-                    //    #137 ①:等内容跳过(replayPolicyRecords)——crash-retry 会整段重跑本重放,无条件 put 让
-                    //    每次重试都推 rev(operator 乐观锁 CAS 令牌)。
                     const policyStore = deps.sessionPolicyStore;
                     if (policyStore)
                         await replayPolicyRecords(policyStore, sessionId, pending.policy, pending.operatorOk);
-                    // ③ anchors — owner RE-KEYED to the importing principal (§9).
                     const anchorStore = deps.resumeAnchorStore;
                     if (anchorStore)
                         for (const a of pending.anchors)
                             await anchorStore.put(sessionId, a.eventId, a.entryId, pending.owner);
-                    // The commit wrote durable state via the RAW store, bypassing the CachingSessionStore wrapper → evict the warm handle.
                     deps.sessionStorage.evict?.(sessionId);
                     cleanupStaging(stagingId);
                     sendJson(res, 200, { relation: committed.relation });
                 }
                 catch (e) {
-                    // A commit-time conflict (the in-txn re-classify flipped to fork/stale, TOCTOU close) rolled the swap back →
-                    // the staging rows still exist → abort them; the client must restart from Phase A with a fresh resolution.
                     if (e instanceof SyncConflictError) {
                         await pending.handle.abort().catch(() => undefined);
                         cleanupStaging(stagingId);
                         sendError(res, 409, "conflict", "sync conflict", { relation: e.relation });
                         return;
                     }
-                    // A SessionPolicyError happens AFTER the swap committed (the policy replay is post-commit) → the conversation
-                    // synced, only the loosen is refused (fail-closed). The staging rows were already renamed away (abort no-op).
                     if (e instanceof SessionPolicyError) {
                         cleanupStaging(stagingId);
                         sendError(res, e.code === "loosen_forbidden" ? 403 : 409, e.code, e.message);
@@ -727,11 +494,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 return;
             }
-            // POST …/sync/plan — DRY-RUN: classify what a PUSH of the LOCAL peer's log (body.entryIds, the OTHER process's
-            // entry-id list) WOULD do against the cloud's current log, WITHOUT writing. The same-process planSync(both
-            // backends) doesn't map the HTTP topology (one peer is remote) → the route classifies by ids: the client ids
-            // are the SOURCE (oldest-first), the cloud's current entries are the DST. own-or-FRESH gate (a fresh cloud
-            // session ⇒ the relation is `fresh`).
             if (sm[2] === "plan" && req.method === "POST") {
                 if (!pushGateOk())
                     return;
@@ -747,12 +509,11 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
-                const dst = await deps.sessionStorage?.exportEntries?.(sessionId); // the cloud's current log (null if fresh)
+                const dst = await deps.sessionStorage?.exportEntries?.(sessionId);
                 const relation = classifySyncRelationshipByIds(body.entryIds, dst ? dst.map((e) => e.id) : null);
                 sendJson(res, 200, relation);
                 return;
             }
-            // A matched sync path but a wrong METHOD (e.g. POST /manifest) → 404 (no method-specific 405 elsewhere).
             sendError(res, 404, "not_found.route", "not found");
             return;
         }