@sema-agent/server 7.43.0 → 7.44.0

package/dist/session-sync-kernel.js

@@ -1,97 +1,40 @@
-/** The staging-id format: a real session id with a `#stg-${token}` suffix. The `#` is illegal in a uuidv7, so a
- *  staging id can never collide with a real session id (the orphan invariant) and is recognizable for the reaper. */
 export function stagingIdFor(realSessionId, token) {
     return `${realSessionId}#stg-${token}`;
 }
-/** The substring marker every staging id carries (the reaper's `LIKE '%#stg-%'` selector). */
 export const STAGING_ID_MARKER = "#stg-";
-/** Recover the real session id from a staging id (everything before the `#stg-` marker), or null if not a staging id. */
 export function realIdOfStaging(stagingId) {
     const i = stagingId.indexOf(STAGING_ID_MARKER);
     return i < 0 ? null : stagingId.slice(0, i);
 }
-/**
- * Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO `session_meta` (never
- * committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe).
- * Mirrors the file-snapshot store's `BLOB_GC_GRACE_MS` discipline (an in-flight import must never be reaped
- * mid-stream).
- *
- * 🔴 住在 kernel 里而不是任一个店里(2026-08-08,#176 二轮扫描 finding):TiDB 与 PG 两个孪生店原先**各
- * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
- * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
- * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
- * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
- */
 export const STAGING_GC_GRACE_MS = 3_600_000;
-/**
- * §7 — classify how importing `srcEntries` into a destination holding `dstEntries` would relate the two logs. PURE
- * (no I/O); the §7 fork detector. The comparison is over the ENTRY-ID SETS, not leaf_id:
- *
- * Entry ids are copied VERBATIM across backends (fork/import re-seq only `seq`; id/parentId/payload are byte-identical
- * — see tidb-session-store fork/importEntries), so a set comparison of ids is the SOUND divergence test §7 demands. It
- * fixes v1's leaf_id-only check, which was unsound BOTH ways:
- *   - FALSE NEGATIVE (the dangerous one): a cross-end rewind moves `LeafEntry.targetId` back onto a shared OLD entry id,
- *     so two genuinely-forked logs report the SAME leaf_id → v1 would silently overwrite = data loss (exactly the 2c
- *     use case). Set comparison sees each side's exclusive ids and reports `fork`.
- *   - FALSE POSITIVE: a clean fast-forward ends on a NEW leaf id ≠ the dst's leaf → v1 flags a (non-)conflict. Set
- *     comparison sees dst ⊊ src and reports `fast_forward` (safe).
- *
- * `commonAncestor` for a fork = the entry id present in BOTH logs that appears LAST in `srcEntries` oldest-first order
- * (the deepest shared appended entry = the divergence point), or `null` if the logs share no entry at all.
- */
 export function classifySyncRelationship(srcEntries, dstEntries) {
-    // Map entries → their ids (the only thing the comparison reads) and delegate to the id-set classifier — ONE source
-    // of the §7 relation logic. (P1d's HTTP plan route, where one peer is REMOTE and sends only an entry-id LIST, calls
-    // classifySyncRelationshipByIds DIRECTLY; this entries-typed entry point is the same logic with a nicer call shape.)
     return classifySyncRelationshipByIds(srcEntries.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
 }
-/**
- * §7 — the SAME relation classifier as {@link classifySyncRelationship}, over entry-id LISTS (oldest-first) instead of
- * full entries. This is the canonical implementation the entries-typed wrapper delegates to. It exists in its own right
- * for the P1d HTTP `/sync/plan` route: the two peers are different PROCESSES (the local shell + the cloud), so the
- * planning peer holds only the OTHER end's entry-id list (not its `SessionTreeEntry[]`) — the relation is decidable from
- * the ids alone (ids are copied VERBATIM across backends, so a set comparison of ids is the sound divergence test §7
- * demands; see the wrapper's doc-comment for why leaf_id was unsound). `srcIds`/`dstIds` are OLDEST-FIRST so the
- * fork `commonAncestor` (the deepest shared id) and the ordered exclusive/new lists are derived correctly.
- */
 export function classifySyncRelationshipByIds(srcIds, dstIds) {
-    // dst absent OR empty ⇒ nothing at the destination to relate to / lose → an unconditional fresh import.
     if (dstIds === null || dstIds.length === 0)
         return { relation: "fresh" };
     const srcSet = new Set(srcIds);
     const dstSet = new Set(dstIds);
-    // identical: same cardinality AND every src id is in dst (⟹ the sets are equal) → already present & equal (no-op).
     if (srcSet.size === dstSet.size && [...srcSet].every((id) => dstSet.has(id)))
         return { relation: "identical" };
-    const allDstInSrc = [...dstSet].every((id) => srcSet.has(id)); // dst ⊆ src
-    const allSrcInDst = [...srcSet].every((id) => dstSet.has(id)); // src ⊆ dst
-    // fast_forward: dst ⊊ src (src strictly ahead — a clean append) → safe to apply. newEntryIds = the src ids the dst
-    // lacks, in SRC oldest-first order (the appended tail), so the caller can surface "what would be added".
+    const allDstInSrc = [...dstSet].every((id) => srcSet.has(id));
+    const allSrcInDst = [...srcSet].every((id) => dstSet.has(id));
     if (allDstInSrc && !allSrcInDst) {
         const newEntryIds = srcIds.filter((id) => !dstSet.has(id));
         return { relation: "fast_forward", newEntryIds };
     }
-    // stale: src ⊊ dst (src strictly behind) → applying would DROP the dst entries src never saw = data loss. dstAheadBy
-    // = the dst ids src lacks (dst order). Refused as a conflict unless the caller explicitly resolves overwrite-dst.
     if (allSrcInDst && !allDstInSrc) {
         const dstAheadBy = dstIds.filter((id) => !srcSet.has(id));
         return { relation: "stale", dstAheadBy };
     }
-    // fork: neither set contains the other ⇒ each side has ≥1 exclusive entry (true divergence). The common ancestor is
-    // the deepest shared entry = the LAST id in src oldest-first order that the dst also holds (null if no shared id).
     const srcExclusive = srcIds.filter((id) => !dstSet.has(id));
     const dstExclusive = dstIds.filter((id) => !srcSet.has(id));
     let commonAncestor = null;
     for (const id of srcIds)
         if (dstSet.has(id))
-            commonAncestor = id; // last shared id in src oldest-first order
+            commonAncestor = id;
     return { relation: "fork", commonAncestor, srcExclusive, dstExclusive };
 }
-/**
- * §7 — a typed conflict the route maps to HTTP 409: an import that WOULD lose destination history (a `fork` or a
- * `stale` source) and the caller did NOT pass an explicit `{ resolution: "overwrite-dst" }`. Carries the classified
- * relation so the route/shell can surface the exclusive entry sets to the user for a keep-local / keep-cloud decision.
- */
 export class SyncConflictError extends Error {
     sessionId;
     relation;

package/dist/session-sync.js

@@ -1,56 +1,32 @@
 import { classifySyncRelationship } from "./session-sync-kernel.js";
 import { normalizeRules, stripRev } from "@sema-agent/core";
-/** Single-point capability probe (design/158 R7): does `fs` carry the optional `importManifest` snapshot-import
- *  seam? Returns the bound method (never a naked function reference — `this` inside `importManifest` must resolve
- *  to `fs`, exactly like `asServiceDeps`'s other capability-probe-then-bind authorities) or `undefined` when the
- *  seam is absent (an older/in-memory dev store). Callers gate on the RETURN VALUE, not a separate `typeof` check,
- *  so there is exactly one place that knows the shape of the probe. */
 export function fileSnapshotImportFace(fs) {
     const candidate = fs?.importManifest;
     if (typeof candidate !== "function")
         return undefined;
     return { importManifest: candidate.bind(fs) };
 }
-/** Narrow `backend.session()` to the optional ownership/export seam (the concrete TiDB/PG/Local stores carry it;
- *  the bare in-memory dev store doesn't → the methods are optional, exactly like the fork route narrows). */
 function ownerAware(backend) {
     return backend.session();
 }
-/**
- * P1d-α (PULL streaming, §15) — EXPORT a session's portable state as a {@link SessionManifest} (entries LIFTED OFF
- * the wire), so it does NOT load entry payloads: it reads the
- * IDS-only projection via `listEntryIds` (`null` ⇒ no such session ⇒ this returns `null`), counts them, reads the
- * current `leafId`, and builds snapshots/policy/anchors. The paired NDJSON
- * `GET /sync/entries` route streams the entry payloads separately (keyset-paged → bounded memory), so a 1M-entry
- * session's manifest stays small (ids + counts + the snapshot/policy/anchor metadata).
- *
- * The OWNER is NOT exported (import re-stamps it, §9). The owner-scope GATE is the CALLER's (route P1d): this returns
- * `null` ONLY for "session does not exist". (Named exportSessionManifest, NOT exportManifest, to avoid the collision
- * with `FileSnapshotStore.exportManifest`.)
- */
 export async function exportSessionManifest(sessionId, srcBackend) {
     const session = ownerAware(srcBackend);
-    // entry IDS FIRST — null ⇒ no such session ⇒ no manifest (the route maps this to 404). A backend whose session store
-    // lacks the seam can't be a sync source (older/in-memory dev store) → treat as nothing to export.
     const listEntryIds = session.listEntryIds?.bind(session);
     if (!listEntryIds)
         return null;
     const entryIds = await listEntryIds(sessionId);
     if (entryIds === null)
-        return null; // session does not exist
-    // leafId — the session's current leaf (cache-bypassing single read). Absent seam / no leaf ⇒ null.
+        return null;
     const getLeafId = session.getLeafId?.bind(session);
     const leafId = getLeafId ? await getLeafId(sessionId) : null;
-    // snapshots / policy / anchors — no entry payloads loaded anywhere here.
     const fs = srcBackend.fileSnapshot();
     const snapshots = [];
-    // [2373]B-5b:core 接口 listKeys 必填(恒真半支删);exportManifest? 可选——探测只留真可选的那半。
     if (typeof fs.exportManifest === "function") {
         const keys = await fs.listKeys(sessionId);
         for (const key of keys) {
             const manifest = await fs.exportManifest(sessionId, key);
             if (manifest === null)
-                continue; // raced reap between listKeys and exportManifest — skip (never an empty snapshot)
+                continue;
             snapshots.push({ key, manifest: [...manifest] });
         }
     }
@@ -59,10 +35,7 @@ export async function exportSessionManifest(sessionId, srcBackend) {
         ? await policyStore.listBySession(sessionId)
         : [];
     const anchorStore = srcBackend.resumeAnchor();
-    // [2373]B-5a:ResumeAnchorStore 是三实现的闭合联合、listBySession 全必填——feature-detect 恒真,
-    // `: []` 臂不可达([2195] deleteBySession 同判据,那轮漏了这对双胞胎)。直调。
     const anchors = await anchorStore.listBySession(sessionId);
-    // getBlob — bound to the SOURCE snapshot store (content-addressed, lazy).
     const getBlobFn = fs.getBlob?.bind(fs);
     const getBlob = getBlobFn ? (hash) => getBlobFn(hash) : async () => undefined;
     return {
@@ -70,37 +43,19 @@ export async function exportSessionManifest(sessionId, srcBackend) {
         getBlob,
     };
 }
-/**
- * §7 DRY-RUN — classify what importing `sessionId` from `srcBackend` into `dstBackend` WOULD do, WITHOUT writing
- * anything (the shell can present a keep-local / keep-cloud / fork-new choice up front).
- *
- * Returns `null` when the SOURCE session does not exist (no bundle to plan); otherwise the {@link SyncRelation}
- * between the source's full durable log and the destination's current log (a `null` dst log ⇒ `fresh`). No writes.
- */
 export async function planSync(sessionId, srcBackend, dstBackend) {
     const srcEntries = (await ownerAware(srcBackend).exportEntries?.(sessionId)) ?? null;
     if (srcEntries === null)
-        return null; // no such source session — nothing to plan (the route maps this to 404)
+        return null;
     const dstEntries = (await ownerAware(dstBackend).exportEntries?.(sessionId)) ?? null;
     return classifySyncRelationship(srcEntries, dstEntries);
 }
-// ═══ #137 —— 死码 importSession 独有保护的活路由移植(910c524 顶注 TOMBSTONE 两缺口的修复面)═══
-// 本段是「测红复现(fanout-characterization #137 L1/L2)→ 修绿」的绿半场;顶注 TOMBSTONE 的
-// 「NO live-route equivalent」声明随本批作废(保留原文供考古,状态以本段+路由接线为准)。
-/** #137 ①(死码 A6 修的移植):同内容判据 —— 比较「归一化、去 rev」后的字节形。putRules 每次
- *  无条件写都 rev+1,而 rev 是 operator 乐观锁的 CAS 令牌(`PutRulesOptions.expectedRev`),
- *  幂等重试/无害重复同步不该把在途 CAS 打失败。归一化用 core 的 `normalizeRules`(store 落盘
- *  前走同一函数 ⇒ 两侧同坐标);`stripRev` 去掉记录内嵌的 rev(`listBySession` 的 rules 含 rev,
- *  它不是内容)。 */
 export function sameRulesContent(stored, incoming) {
     if (stored === null)
         return false;
     const norm = (r) => JSON.stringify(normalizeRules(stripRev(r)));
     return norm(stored) === norm(incoming);
 }
-/** #137 ① 的重放腿共享实现:PUSH 路由的两条 policy 重放腿(Phase A identical 短路支 / Phase B
- *  commit 后支)都从这里走 —— 等内容跳过(rev 零漂移),真变更照常落地(E6 tighten-only 门在
- *  putRules 内部,此处不重述)。 */
 export async function replayPolicyRecords(store, sessionId, records, operatorOk) {
     for (const rec of records) {
         const cur = await store.getRules(sessionId, rec.principal);
@@ -109,27 +64,9 @@ export async function replayPolicyRecords(store, sessionId, records, operatorOk)
         await store.putRules(sessionId, rec.principal, rec.rules, { operator: operatorOk });
     }
 }
-/** #137 ② 能力预检(fail-loud 方向,[2195] 判据:保护型能力缺席=fail-closed):consented
- *  overwrite-dst 需要 policy 店的 `deleteBySession` purge seam 才能不留混合态;缺席=true,路由在
- *  commit **之前**用它干净中止(此时零写入落地),wire 拒因字面量归路由所有(api-error-text-freeze
- *  锚字面站点)。anchor 店的 deleteBySession 是类型必填、快照店有 core 必填的 `reap` 兜底,都不构成
- *  缺席面;唯一可缺的就是 policy 这条(core 接口上是可选方法)。 */
 export function overwriteWipeIncapable(policyStore) {
     return policyStore !== undefined && typeof policyStore.deleteBySession !== "function";
 }
-/** #137 ②(死码 ⓪ 擦除步的移植):consented overwrite-dst = keep-source,结果必须是**源端那
- *  一份**,不得混成「源端对话 + 目的端遗留 policy/anchor/快照」(混合态比丢历史更危险:悬空
- *  anchor 指向已 purge 的 entry、被放弃分支的 policy 行继续 gating、共享 key 快照因
- *  importManifest create-once 永远留着目的端字节)。调用时点=commit(原子 swap)成功**之后**、
- *  附随物重放**之前**:死码在任何写入前擦(其 entries 写本身非原子);活路由有真 commit point,
- *  擦在 commit 前会在「commit 失败」时留下反向混合态(目的端对话完好、附随物已毁)——方向更坏。
- *  诚实残余:进程在 commit 与本函数之间崩溃时,重试落 Phase A identical 支(无 wipe)⇒ 遗留行
- *  可存活;该窗口窄于修前世界(修前=遗留行**恒**存活),与 §8「快照重放失败 ⇒ 422 重试自愈」
- *  同款接受,记录于此不装没有。
- *  各店姿势(死码 verbatim 语义):快照=deleteBySession(SQL 孪生:manifest 即删、blob 走异步
- *  孤儿 GC)缺席则 core 必填 `reap(scope, [])`(内容寻址,他 scope 仍引用的 blob 存活);
- *  anchor=直调(类型必填);policy=deleteBySession(路由已用 {@link overwriteWipeIncapable}
- *  预检过,此处缺席=类型外的 JS 层残缺实现,直调抛 TypeError 即 fail-loud)。 */
 export async function wipeSessionAttendants(stores, sessionId) {
     const fs = stores.fileSnapshotStore;
     if (fs !== undefined) {

package/dist/session-titler.js

@@ -1,30 +1,10 @@
-/**
- * Auto-generated session titles.
- *
- * SHAPE: fire-and-forget at FIRST task submit for a session (the objective is known then — no need to wait
- * for the run to finish, and the web Recents gets the title sooner). Write-once (`setTitleIfNull`, store-side
- * `WHERE title IS NULL`) — the USER-facing rename lives BFF-side as a label overlay (user label wins
- * over engine title, two layers never fight). Generation = one cheap-model one-liner via the deployment's
- * hookLlm face (summarize role → MODEL_CHEAP_ID when configured, else the main model; bounded + timed out).
- *
- * FAILURE POSTURE: everything is best-effort — a generation/store failure logs and leaves title null (the
- * list falls back to objectivePreview). An in-process pending set dedupes concurrent submits on the same
- * session; the store's IS NULL guard closes the cross-replica race (double generation costs one extra cheap
- * call at worst, and exactly one title lands).
- */
-export const TITLE_MAX_CHARS = 80; // display budget (column holds 120; leave headroom for future prefixing)
-const OBJECTIVE_SNIPPET_CHARS = 600; // prompt input bound — a title needs the gist, not the whole objective
+export const TITLE_MAX_CHARS = 80;
+const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
-const NO_ROW_RETRY_MS = 20_000; // session_meta register lag grace (MED3) — one in-process retry before releasing
-/** 失败日志 per-cause 去重的归一窗口:取 error 文案前 N 字符当 cause 键(错误文案尾部常带
- *  会话/请求级变量,前缀足以区分「凭据缺失」vs「超时」这类配置性差异)。 */
+const NO_ROW_RETRY_MS = 20_000;
 const FAIL_CAUSE_KEY_CHARS = 80;
-/** cause 键集合上限——错误文案前缀本身含变量时防无界;满了整体清空,代价只是偶发多一条 warn。 */
 const FAIL_CAUSE_CAP = 100;
-/** Sessions already handled (titled, failed, or in flight) this process — one attempt per session per process.
- *  Bounded: evict-oldest past the cap (a worker sees a bounded set of NEW sessions between restarts anyway). */
 const SEEN_CAP = 10_000;
-/** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */
 export function sanitizeTitle(raw) {
     const oneLine = raw.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").trim();
     const unquoted = oneLine.replace(/^["'「『]+/, "").replace(/["'」』]+$/, "").trim();
@@ -32,10 +12,6 @@ export function sanitizeTitle(raw) {
 }
 export function buildTitlePrompt(objective) {
     const snippet = objective.length > OBJECTIVE_SNIPPET_CHARS ? `${objective.slice(0, OBJECTIVE_SNIPPET_CHARS)}…` : objective;
-    // The task text is DATA here, not instructions — fence it (with the closing tag DEFUSED inside the data so
-    // the objective cannot terminate the fence early) and pin the output contract. A prompt-injection attempt
-    // can at worst produce a weird title, which the sanitizer bounds to one line; titles are display-only and
-    // never re-enter any model context.
     const fenced = snippet.replace(/<(\/?)request>/gi, "<\u200b$1request>");
     return ("Write a short title (at most 8 words) summarizing the user request below. " +
         "Reply with ONLY the title on a single line — no quotes, no preamble. " +
@@ -45,12 +21,6 @@ export function buildTitlePrompt(objective) {
 }
 export function createSessionTitler(deps) {
     const seen = new Set();
-    // [854]⑤ 失败日志锐化:titler 失败本是 fail-soft(标题留空、列表回退 objectivePreview,零用户面),
-    // 但同一部署级配置性失败(凭据缺失/模型面不可达)会随每次 trial/每个新会话反复触发——per-session
-    // warn 在评测跑批时是纯噪音。取舍=「首条 warn + 后续同 cause 全 debug」:完全静默会让运维发现不了
-    // 配置问题(违背 fail-loud),每条都 warn 又淹日志;同 cause 每进程恰好 warn 一次是两全。观测面不靠
-    // 日志靠 metrics(session_title_total outcome 族照常逐次记账)。cause=error 文案前缀归一(见常量注释);
-    // 集合挂在 titler 实例上,部署里每进程恰建一只 titler ⇒ 等价 per-process。
     const warnedCauses = new Set();
     const logFailure = (sessionId, error) => {
         const cause = error.slice(0, FAIL_CAUSE_KEY_CHARS);
@@ -69,7 +39,7 @@ export function createSessionTitler(deps) {
             if (!sessionId || !objective.trim())
                 return;
             if (seen.has(sessionId))
-                return; // one attempt per session per process (resubmits/turns don't re-fire)
+                return;
             if (seen.size >= SEEN_CAP) {
                 const oldest = seen.values().next().value;
                 if (oldest !== undefined)
@@ -77,14 +47,12 @@ export function createSessionTitler(deps) {
             }
             seen.add(sessionId);
             void (async () => {
-                // pre-LLM probe: a point-read is orders cheaper than an LLM call (MED2 — restarts/evicted seen/other
-                // replicas must not re-pay), and it detects the register-lag "no row yet" window (MED3).
-                let state = await deps.probeTitle(sessionId).catch(() => "untitled"); // probe error ⇒ optimistic (IS NULL still guards)
+                let state = await deps.probeTitle(sessionId).catch(() => "untitled");
                 if (state === "none") {
                     await new Promise((r) => setTimeout(r, NO_ROW_RETRY_MS));
                     state = await deps.probeTitle(sessionId).catch(() => "untitled");
                     if (state === "none") {
-                        seen.delete(sessionId); // release: the NEXT submit on this session retries (no permanent miss)
+                        seen.delete(sessionId);
                         deps.metrics?.inc("session_title_total", { outcome: "row_not_yet" });
                         return;
                     }
@@ -106,8 +74,6 @@ export function createSessionTitler(deps) {
                 }
                 const landed = await deps.setTitleIfNull(sessionId, title);
                 if (!landed) {
-                    // distinguish "another writer titled it" (fine) from "row STILL absent" (UPDATE-0 on a missing row —
-                    // release the seen slot so a later submit retries; never leave the session permanently untitled).
                     const after = await deps.probeTitle(sessionId).catch(() => "titled");
                     if (after === "none")
                         seen.delete(sessionId);
@@ -115,7 +81,7 @@ export function createSessionTitler(deps) {
                     return;
                 }
                 deps.metrics?.inc("session_title_total", { outcome: "set" });
-                deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length }); // content stays OUT of logs (R10 posture) — it's user-derived data
+                deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length });
             })().catch((e) => {
                 deps.metrics?.inc("session_title_total", { outcome: "error" });
                 logFailure(sessionId, String(e));

package/dist/session-watch.js

@@ -1,28 +1,3 @@
-/**
- * Session-watch registry — the server half of the session-level SSE subscription
- * (design: sema-internal `server/docs/SESSION-SSE-DESIGN.md`, 黑板 [1164]①/[1196]).
- *
- * One entry per watched session; N subscribers SHARE one probe loop (this is the whole point:
- * it converts web-side per-client polling into one per-replica probe). Two change channels:
- *  - fast path: `notifyLocal(sessionId, leafId)` — an append that lands on THIS replica fans out
- *    synchronously (zero latency on single-replica deployments, the common TOC/local shape);
- *  - slow path: the probe loop reads leafId through the SAME storage face the /head probe uses.
- *
- * codex 复审(1.230 一轮)后的三条硬语义:
- *  - **revision 守卫**:notifyLocal 每次推进 bump `rev`;探针起读前抓拍 rev,读回后 rev 变=结果作废
- *    (陈旧慢读不得把 B 倒退回 A——latest-wins 的机制保证,不靠时序运气)。
- *  - **replay-on-subscribe**:已有条目携带 `last` 时,新订阅者同步补发一帧(「join 与基线原子化」的
- *    registry 半场;连接层再配 lastSent 去重,乱序/重复帧对下游不可见)。
- *  - **冷启动 warm**:新条目 lastChangeAt=0(没观测到变化就不算热)——首拍一次 hotMs 快确认后即落
- *    warm 拍距,直到真观测到跳变才进热窗(codex:重连风暴下 256 会话×200ms=对存储的自造尖峰)。
- *
- * Deliberately backend-agnostic (tidb|pg|local all go through getLeafId — the seamless-local-cloud
- * invariant): no PG LISTEN/NOTIFY specialization, no shared bus. Latest-wins semantics: subscribers
- * converge on the newest leafId; intermediate hops may be dropped (content still comes from tail faces).
- */
-/** [1196] 二轮复审:SSE 资源旋钮的 env 解析——有界正整数,坏形(NaN/0/负/超界)一律回缺省并可观测
- *  (坏 `SESSION_EVENTS_MAX_PROBES=foo` 若直进 Number() 会把帽谓词变恒假=无帽,拍距 NaN 进 setTimeout
- *  =0ms 紧循环打爆存储)。 */
 export function posIntEnv(raw, fallback, max = 3_600_000) {
     if (raw === undefined || raw === "")
         return fallback;
@@ -36,33 +11,19 @@ export class SessionWatchRegistry {
     warmMs;
     hotWindowMs;
     maxWatched;
-    constructor(
-    /** 五轮复审:owner 与 leaf **同拍原子读**——探针每拍先核 owner(被删=undefined/换主=≠条目 owner
-     *  ⇒ dropSession 断全部订阅者),匹配才应用 leaf。跨副本 reclaim 的披露窗从 25s 心跳收紧到
-     *  ≤一个探针拍(hot 200ms/warm 2s),且旧流在新主推进**之前**先死(owner 检查先于 leaf 应用)。 */
-    getHead, opts) {
+    constructor(getHead, opts) {
         this.getHead = getHead;
         this.hotMs = opts?.hotMs ?? 200;
         this.warmMs = opts?.warmMs ?? 2000;
         this.hotWindowMs = opts?.hotWindowMs ?? 60_000;
         this.maxWatched = opts?.maxWatchedSessions ?? 512;
     }
-    /** Number of sessions currently probed (observability + the cap predicate). */
     watchedCount() {
         return this.entries.size;
     }
-    /**
-     * Subscribe to head changes. Returns undefined when the per-replica probe cap is reached
-     * (caller answers 503 + Retry-After — the client falls back to /head polling).
-     * If the shared entry already knows a head (`last`), it is REPLAYED synchronously into
-     * `onHead` before returning — a subscriber joining an advanced entry can never miss the
-     * newest value (connection-level dedupe absorbs any overlap with the caller's own read).
-     */
     subscribe(sessionId, owner, onHead, onEnd) {
         let e = this.entries.get(sessionId);
         if (e && e.owner !== owner) {
-            // 四轮复审跨副本围栏:同键不同 owner=本副本条目属被删/被 reclaim 的旧世代——整体作废
-            // (旧订阅者 onEnd 断流),新 owner 拿全新条目,旧租户缓存 head 绝不 replay。
             this.dropSession(sessionId);
             e = undefined;
         }
@@ -71,7 +32,7 @@ export class SessionWatchRegistry {
                 return undefined;
             e = { subs: new Set(), ends: new Map(), owner, last: undefined, rev: 0, lastChangeAt: 0, probing: false };
             this.entries.set(sessionId, e);
-            this.arm(sessionId, e, this.hotMs); // one fast confirmation tick, then warm until a REAL change
+            this.arm(sessionId, e, this.hotMs);
         }
         e.subs.add(onHead);
         e.ends.set(onHead, onEnd);
@@ -80,24 +41,21 @@ export class SessionWatchRegistry {
                 onHead(e.last);
             }
             catch {
-                /* subscriber callback must not break subscribe */
             }
         }
         return () => {
             const cur = this.entries.get(sessionId);
             if (cur !== e)
-                return; // entry already replaced/removed
+                return;
             e.subs.delete(onHead);
             e.ends.delete(onHead);
             if (e.subs.size === 0) {
                 if (e.timer)
                     clearTimeout(e.timer);
-                this.entries.delete(sessionId); // cold: last subscriber gone → probe stops, entry dies
+                this.entries.delete(sessionId);
             }
         };
     }
-    /** [1196] 三轮复审(租户轮转围栏,同副本半场):session 删除即终结条目——通知全部订阅者(onEnd,
-     *  路由据此断流)+ 停探针 + 弃缓存 head(新租户同键重订阅=全新世代,旧 replay 不可能渗入)。 */
     dropSession(sessionId) {
         const e = this.entries.get(sessionId);
         if (!e)
@@ -110,27 +68,17 @@ export class SessionWatchRegistry {
                 end?.();
             }
             catch {
-                /* 单个订阅者收尾失败不挡其余 */
             }
         }
     }
-    /** S2 fast path: an append that landed on THIS replica. Safe to call for unwatched sessions (no-op).
-     *  `owner` 给了就 owner-限定(五轮复审):不符=条目属旧世代 ⇒ drop(断旧流),值不投——S2 接线时
-     *  append 落点必然知道 session owner,应当传。 */
     notifyLocal(sessionId, leafId, owner, leafSeq) {
         const e = this.entries.get(sessionId);
         if (!e)
             return;
         if (owner !== undefined && owner !== e.owner) {
-            // codex-4(S2 批):owner 不符的帧**绝不凭帧行刑**——leaf_seq 随行删建归零,跨世代序不可比:
-            // 迟到的旧租户高序帧会假装「新于」新租户的 seq 1(凭帧 drop=误杀新流);反向新租户低序真帧也
-            // 会被旧条目的高水位吞掉。裁决交给**立即权威探针**(owner 原子 getHead,本就是围栏权威):
-            // 真 reclaim=探针 dropSession(零等待,不再候 warm 拍),误报=条目安然。值不投。
             this.probeNow(sessionId, e);
             return;
         }
-        // codex-3:同 owner 内的乱序守卫——post-commit continuation 不保序,迟到低序=忽略不倒退。
-        // (同 owner 的 delete/recreate 归零序被高水位吞=良性新鲜度问题,探针自纠——条目头注既有口径。)
         if (leafSeq !== undefined && e.lastLocalSeq !== undefined && leafSeq <= e.lastLocalSeq)
             return;
         if (leafSeq !== undefined)
@@ -139,12 +87,8 @@ export class SessionWatchRegistry {
             return;
         this.applyAdvance(e, leafId);
     }
-    /** 立即压缩下一拍到 0ms(owner 疑云的权威核验)。探针自身 probing 串行 + 世代守卫照旧;urgent 旗
-     *  保证「疑云到达时已有读在飞(其快照摄于 reclaim 前=陈旧)」也必有一次**疑云后开始**的权威读。 */
     probeNow(sessionId, e) {
         e.urgent = true;
-        // codex-6:读在飞时**只置旗不排拍**——0ms 拍撞 probing 会跳读后又按旗补 0ms=事件环忙转直到慢读落定
-        // (存储降级时整副本被搅)。在飞读的拍尾独占排拍权,旗在那里兑现。
         if (e.probing)
             return;
         if (e.timer)
@@ -157,47 +101,40 @@ export class SessionWatchRegistry {
     }
     async probe(sessionId, e) {
         if (this.entries.get(sessionId) !== e)
-            return; // entry died while the timer was pending
+            return;
         if (e.probing)
-            return; // 撞上在飞读:不读不排拍(其拍尾独占排拍权,urgent 旗在那兑现——codex-6)
+            return;
         {
             e.probing = true;
-            e.urgent = false; // 本读始于旗后=消费旗(读期间新疑云会重新置旗)
+            e.urgent = false;
             const revAtStart = e.rev;
             try {
                 const head = await this.getHead(sessionId);
-                // 世代守卫(二轮复审):读期间末订阅者退出+重连=同键**新条目**——陈旧读绝不许经按键查找
-                // 渗入新世代;只对抓拍的旧条目本体应用(旧条目已无订阅者=自然无害)。
                 if (this.entries.get(sessionId) !== e)
                     return;
-                // 五轮复审跨副本围栏(探针拍级):session 被删(owner undefined)或被 reclaim(owner 变)
-                // ⇒ 条目作废+订阅者断流,leaf **不应用不 fan-out**——新租户的 leafId 绝不流向旧 owner 的流。
                 if (head.owner === undefined || head.owner !== e.owner) {
                     this.dropSession(sessionId);
                     return;
                 }
                 const leafId = head.leafId ?? null;
-                // revision 守卫:读期间 notifyLocal 推进过(rev 变)=本读陈旧,丢弃——绝不把新值倒退回旧值。
                 if (e.rev === revAtStart && leafId !== e.last)
                     this.applyAdvance(e, leafId);
             }
             catch {
-                /* transient storage error: keep probing — the SSE stream stays up */
             }
             finally {
                 e.probing = false;
             }
         }
         if (this.entries.get(sessionId) !== e)
-            return; // last subscriber left during the read
+            return;
         if (e.urgent) {
-            this.arm(sessionId, e, 0); // codex-5:in-flight 吞掉的急拍在拍尾补上——欠的权威读绝不滑到 warm 拍
+            this.arm(sessionId, e, 0);
             return;
         }
         const hot = e.lastChangeAt !== 0 && Date.now() - e.lastChangeAt < this.hotWindowMs;
         this.arm(sessionId, e, hot ? this.hotMs : this.warmMs);
     }
-    /** 对**给定世代**应用一次推进(fan-out 恒按 rev 单调序)。 */
     applyAdvance(e, leafId) {
         const wasKnown = e.last !== undefined;
         e.last = leafId;
@@ -209,7 +146,6 @@ export class SessionWatchRegistry {
                 fn(leafId);
             }
             catch {
-                /* one broken subscriber must not break the fan-out */
             }
         }
     }

package/dist/shared-memory-scope-authorizer.js

@@ -1,25 +1,7 @@
-/**
- * 活对象(闭包持有目录与取值口)⇒ `create*`(CLAUDE.md 工厂命名律)。
- *
- * **代价与它的边界**(codex 对抗复审 R1-[medium] 的一半采纳,一半具名保留):取值口按调用现算,
- * 意味着每次 `resolve` 都要扫一遍 `config.projects`(O(项目数 × 每项 scope 数)的纯 CPU)。
- *  · **已采纳**:principal 缺席那支不再二次建 Set —— 生产取值口(`collectDeploymentOrgScopes`)本来就用
- *    Set 建、交回来已去重,这里再包一层是纯浪费。**去重责任因此上移到取值口**(契约见下面那个字段的注),
- *    principal 在场那支的合并 Set 保留(它要与目录 scope 求并,那一次是真需要的)。
- *  · **具名保留**(不做 generation 缓存):`config.projects` 由 `mutateInPlace` **就地**改,对象身份恒定,
- *    没有可用的失效信号;而 config-center 的 `appliedGeneration` 是那个模块的私有 WeakMap,不在公面上。
- *    要缓存就得先给 config-center 开一只「已提交世代」读口 —— 那是别人模块的接缝件,且**缓存失效写错
- *    一次,就恰好把本条 finding 刚关掉的那个陈旧窗原样放回来**(还多一层代码)。规模面亦不支持先做:
- *    projects 是运维手写的登记簿(量级十几~百),而这条腿的**同一次**调用里,principal 在场那支还要
- *    `await directory.lookup()`(网络/缓存),扫表在它旁边不构成瓶颈。⇒ 若哪天登记簿真长到会阻塞事件循环,
- *    正解是**先给 projects/defaultScopes 定尺**(发布期拒收超尺,与本仓其它 wire 上限同族),再谈缓存。
- */
 export function createSharedMemoryScopeAuthorizer(opts) {
     const deploymentScopesNow = () => opts.deploymentScopes?.() ?? [];
     return {
         async resolve(principal) {
-            // principal 缺席 = 单用户部署(多租户下 core 与 HTTP 门都先要求身份)。此时唯一的授权事实就是
-            // operator 自证的那一组;目录无从查起,但这不是「不可用」——它是一个**已知的**答案。
             if (principal === undefined)
                 return { kind: "granted", scopes: deploymentScopesNow() };
             const lookup = await opts.directory.lookup(principal);

package/dist/sighup-idle.js

@@ -1,24 +1,15 @@
-/** Returns the SIGHUP handler. Call it on every SIGHUP; it arms the idle watch on the first signal and
- *  escalates on the second. The interval is deliberately NOT unref'd — in the orphan case it IS the
- *  shutdown driver (same posture as the drain tick). */
 export function createSighupIdleHandler(deps) {
     const tickMs = deps.tickMs ?? 1_000;
-    const now = deps.now ?? (() => performance.now()); // 单调时钟(修3)——绝不用 Date.now()
+    const now = deps.now ?? (() => performance.now());
     let watch;
     let idleSince = null;
     let armedAt = 0;
     return () => {
         if (deps.isStopped()) {
-            // A drain/shutdown owner is already active. Do NOT escalate: escalating during a graceful SIGTERM
-            // drain would hard-kill every in-flight leg because one terminal window closed — the exact harm B3
-            // exists to prevent. The operator's hard ladder stays SIGTERM×2 / SIGINT (复审 M5b).
             deps.log("sighup_ignored_shutdown_in_progress", {});
             return;
         }
         if (watch !== undefined) {
-            // Debounce (复审 M5a): a window close can deliver SIGHUP twice within milliseconds (kernel pty hangup
-            // + shell forwarding) — treating the echo as the operator's deliberate second signal would flip
-            // draining and 503 the peers B3 protects. A human double-press is comfortably > 1s.
             if (now() - armedAt < 1_000) {
                 deps.log("sighup_duplicate_ignored", {});
                 return;
@@ -48,8 +39,6 @@ export function createSighupIdleHandler(deps) {
                 idleSince = now();
                 return;
             }
-            // Activity clock: a request between ticks (or one still in its pre-registration phase) resets the
-            // window even though inflight sampled 0 — both clocks must be quiet for a full grace period.
             const lastActivity = deps.lastActivityAt?.() ?? 0;
             if (now() - lastActivity < deps.idleGraceMs)
                 return;