@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/session-sync.d.ts

@@ -1,3 +1,12 @@
+/**
+ * design/158 A9 域模块 —— 2c session-sync 面(docs/DESIGN-session-sync.md §15 + §5–§10)。
+ *
+ * 路由:`/v1/sessions/:id/sync/{manifest,entries,import,plan,blobs,snapshots/:k/blobs/:b,import/:staging/entries}`。
+ * 每条都像 fork/delete 一样 owner-gated;无持久 session store 时 501(能力面与路由解析同真值)。
+ *
+ * 单域独占状态(lens1 §C2 的 12 条里的 4 条)全在 `SessionSyncLocal`,每个 server 实例一份:
+ * `pendingStagings`(Phase A→B 的 staging 绑定)、`importLeases`(per-session 导入租约)与它的两个操作。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionRulesRecord } from "@sema-agent/core";
 import { type StagingHandle } from "../../session-sync.js";
@@ -18,10 +27,16 @@ export type PendingStaging = {
         entryId: string;
         owner: string | null;
     }>;
+    /** 对抗复查 A-3(HIGH):Phase A's DECLARED entry-id set — Phase B verifies the streamed NDJSON matches it
+     *  (a different tree under the same staging would otherwise commit while the parked snapshots/anchors
+     *  still reference the DECLARED one). */
     declaredEntryIds: string[];
+    /** The principal that opened this staging — a different caller may not drive it (404, no oracle). */
     openedBy: string | null;
+    /** Fleet-wide caller (ops on-behalf) — bypasses the openedBy identity check (like the route's owner gates). */
     openedFleetWide: boolean;
 };
+/** 单域独占状态 + 它的两个操作。每个 server 实例一份。 */
 export interface SessionSyncLocal {
     pendingStagings: Map<string, PendingStaging>;
     importLeases: Map<string, {