@morlay/session-rdb 0.1.9 → 0.1.10-alpha.2

package/src/{branch.ts → branch/index.ts}

@@ -17,77 +17,18 @@ import {
   type ForkFromOptions,
   type SessionBranchProvider,
 } from "@morlay/session-branch";
-import { randomUUID } from "node:crypto";
-import type { Backend } from "./backend.ts";
-import type { SessionPersistenceRdb } from "./index.ts";
-import { isLegacyVersion } from "./legacy.ts";
-import { rowToMeta } from "./log.ts";
-
-function assertRewindBoundary(
-  id: SessionId,
-  toBoundary: number,
-  boundaryType: string | undefined,
-  head: number,
-): void {
-  if (toBoundary === -1) return;
-  if (toBoundary > head) {
-    throw new SessionBranchError(
-      `rewind boundary ${toBoundary} is beyond the stored head ${head}`,
-      "INVALID_BOUNDARY",
-    );
-  }
-  if (boundaryType === undefined) {
-    throw new SessionBranchError(
-      `rewind boundary ${toBoundary} does not exist in session "${id}"`,
-      "INVALID_BOUNDARY",
-    );
-  }
-  if (boundaryType !== "turn/end" && boundaryType !== "user/message") {
-    throw new SessionBranchError(
-      `rewind boundary ${toBoundary} is not a turn/end or user/message (${boundaryType})`,
-      "INVALID_BOUNDARY",
-    );
-  }
-}
-
-export function locateTurnEnd(
-  events: readonly SessionEvent[],
-  atSeq?: number,
-  mode: BranchAnchorMode = "after",
-): number {
-  const ends = events.filter((event) => event.type === "turn/end").map((event) => event.seq);
-  if (atSeq === undefined) {
-    const last = ends.at(-1);
-    if (last === undefined) throw new SessionBranchError("session has no closed turn", "OPEN_TURN");
-    return last;
-  }
-  if (mode === "before") {
-    let boundary = -1;
-    for (const seq of ends) {
-      if (seq < atSeq) boundary = seq;
-      else break;
-    }
-    return boundary;
-  }
-  const firstAfter = ends.find((seq) => seq >= atSeq);
-  if (firstAfter !== undefined) return firstAfter;
+import { isLegacyVersion } from "../legacy.ts";
+import type { BranchPort } from "./port.ts";
+import { rowToEvent, rowToMeta } from "../log/rows.ts";
 
-  const lastStart = [...events].reverse().find((event) => event.type === "turn/start");
-  if (lastStart !== undefined && lastStart.seq <= atSeq) {
-    throw new SessionBranchError(`anchor ${atSeq} lies inside an open turn`, "OPEN_TURN");
-  }
-  const last = ends.at(-1);
-  if (last === undefined) throw new SessionBranchError("session has no closed turn", "OPEN_TURN");
-  return last;
-}
+import {
+  assertRewindBoundary,
+  locateTurnEnd,
+  mintSessionId,
+  renumber,
+} from "./semantics.ts";
 
-function renumber(events: readonly SessionEvent[], offset: number): SessionEvent[] {
-  return events.map((event, index) => ({ ...event, seq: offset + index }) as SessionEvent);
-}
-
-function mintSessionId(): SessionId {
-  return `session-${randomUUID()}` as SessionId;
-}
+export { locateTurnEnd } from "./semantics.ts";
 
 export interface LiveSessionHooks {
   getSession(id: SessionId): Session | undefined;
@@ -153,7 +94,19 @@ function resetSurfaceManager(surfaceManager: SurfaceManagerLike): void {
   surfaceManager._pendingPlan = undefined;
 }
 
-export function truncateLiveSession(session: Session, newLength: number): void {
+/**
+ * 会话**当前内存 log** 的快照（复制一份）。用于"需要完整序列"的操作（首次落库的 seed、rewind / fork 的历史），
+ * 不走已弃用的同步历史读 `snapshotEvents()`——那三个读口上游已声明「新调用禁止」，而这里要的是当前内存里
+ * 那份完整日志，不是按需分页的历史。
+ * @param session - 会话。
+ * @returns 事件副本（调用方可以自由遍历）。
+ */
+export function liveEventsOf(session: Session): readonly SessionEvent[] {
+  return [...(session as unknown as { log: readonly SessionEvent[] }).log];
+}
+
+/** @returns 截断后日志里最后一个 `turn/start` 的 turn 号（没有则 0）。 */
+export function truncateLiveSession(session: Session, newLength: number): number {
   const s = session as unknown as {
     log: SessionEvent[];
     eventsSnapshot?: unknown;
@@ -166,6 +119,10 @@ export function truncateLiveSession(session: Session, newLength: number): void {
     derivedGeneration: number;
     surfaceManager: SurfaceManagerLike;
   };
+  // 截断后 agent 的 turn 游标要跟着落在保留前缀的最后一个 turn 上：这里直接读**要保留的那段**（同一个数组，
+  // 不经过已弃用的同步历史读 `snapshotEvents`，也不依赖 agent 侧的投影）。
+  const lastTurn =
+    s.log.slice(0, newLength).findLast((event) => event.type === "turn/start")?.data.turn ?? 0;
   s.log.length = newLength;
   s.eventsSnapshot = undefined;
   s.headerFold = undefined;
@@ -176,6 +133,7 @@ export function truncateLiveSession(session: Session, newLength: number): void {
   s.derivedNodes = 0;
   s.derivedGeneration = 0;
   resetSurfaceManager(s.surfaceManager);
+  return lastTurn;
 }
 
 export function replaceLiveSessionLog(session: Session, events: readonly SessionEvent[]): void {
@@ -208,7 +166,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
   readonly name = "session-rdb";
 
   constructor(
-    private readonly persistence: SessionPersistenceRdb,
+    private readonly port: BranchPort,
 
     private readonly live: LiveSessionHooks = {
       getSession: () => undefined,
@@ -232,7 +190,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     id: SessionId,
     signal?: AbortSignal,
   ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }> {
-    const stored = await this.persistence.readLog(id, {}, signal);
+    const stored = await this.port.readLog(id, {}, signal);
     if (stored === undefined)
       throw new SessionBranchError(`session "${id}" not found`, "SESSION_NOT_FOUND");
     return { meta: stored.meta, events: stored.events };
@@ -245,7 +203,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
   ): Promise<SessionId> {
     signal?.throwIfAborted();
     const { atSeq, anchorMode = "after", seedSuffix = [], childSessionId, meta = {} } = options;
-    const source = await this.persistence.readLog(sourceId, {}, signal);
+    const source = await this.port.readLog(sourceId, {}, signal);
     if (source === undefined)
       throw new SessionBranchError(`session "${sourceId}" not found`, "SESSION_NOT_FOUND");
     const boundary = locateTurnEnd(source.events, atSeq, anchorMode);
@@ -277,14 +235,14 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     };
     const seed = [...renumber(prefix, 0), ...renumber(seedSuffix, prefix.length)];
 
-    const internals = this.persistence.internals();
+    await this.port.ready;
     // 复用父会话的事件行有个前提：**读取视图的 seq 与存储行的 f_sequence 一一对应**。legacy 会话的读视图
     // 由迁移链重建（可能重新编号、增删事件），按 seq 复用会把桥接行挂到语义不符的行上——读取时按 `f_data`
     // 解析，子会话前缀读到的内容就会和它自己的 seed 事件对不上。那种情况下复制事件行（多几行存储，正确优先）。
     const reusable = !source.migrated && source.events.length === source.storedCount;
     const reuse = new Map<number, string>();
     if (reusable) {
-      const sourceRows = await internals.backend.getEventRows(sourceId);
+      const sourceRows = await this.port.eventRows(sourceId);
       const sourceEventIds = new Map(sourceRows.map((row) => [row.fSequence, row.fEventId]));
       for (const event of prefix) {
         const eventId = sourceEventIds.get(event.seq);
@@ -295,9 +253,9 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
         `session-rdb: fork "${sourceId}" copies event rows instead of reusing them — its read view comes from a migration, so stored seqs need not line up`,
       );
     }
-    internals.registerReuseEventIds(childId, reuse);
+    this.port.registerReuseEventIds(childId, reuse);
     try {
-      const handle = await this.persistence.create(childMeta, {
+      const handle = await this.port.create(childMeta, {
         inheritedEventCount: SessionLogOffset(prefix.length),
       });
       try {
@@ -308,7 +266,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     } catch (error) {
       // fork 没成（id 已存在、append 失败等）：别把复用映射留在进程里——同一个 childId 之后的落写会按它
       // 去复用父会话的事件行，而那条会话可能完全无关。
-      internals.dropReuseEventIds(childId);
+      this.port.dropReuseEventIds(childId);
       throw error;
     }
     // fork 不动统计：继承前缀的消耗是父会话真实发生的那一次，子会话只记自己新产生的
@@ -332,11 +290,11 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
 
     if (live !== undefined) await this.live.flush(live);
 
-    const internals = this.persistence.internals();
+    await this.port.ready;
 
     // SessionBranch 是「先停止、再操作」的排他面（ADR-rewind绕过handle模型直接截断）：rewind 直连 DB 做最小工作，
     // 不走持久化抽象的全量读路径（readLog 会拉全部事件 + legacy 转换 + 读视图修复）。
-    const row = await internals.backend.getSession(id);
+    const row = await this.port.sessionRow(id);
     if (row === undefined) {
       throw new SessionBranchError(`session "${id}" not found`, "SESSION_NOT_FOUND");
     }
@@ -346,7 +304,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     let kept: readonly SessionEvent[] | undefined;
     if (isLegacyVersion(row.fVersion)) {
       // 旧格式的持久化坐标与当前视图 seq 不一致：只有这条路径需要读日志（含格式转换与读视图修复）
-      const log = await this.persistence.readLog(id, {}, signal);
+      const log = await this.port.readLog(id, {}, signal);
       if (log === undefined) {
         throw new SessionBranchError(`session "${id}" not found`, "SESSION_NOT_FOUND");
       }
@@ -357,14 +315,14 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       kept = balanceRewindPrefix(log.events.slice(0, rawKeepLength));
     } else {
       const boundaryType =
-        toBoundary === -1 ? undefined : await internals.backend.getEventTypeAt(id, toBoundary);
+        toBoundary === -1 ? undefined : await this.port.eventTypeAt(id, toBoundary);
       assertRewindBoundary(id, toBoundary, boundaryType, row.fHeadSequence);
       rawKeepLength =
         toBoundary === -1 ? 0 : boundaryType === "turn/end" ? toBoundary + 1 : toBoundary;
     }
     const keepLength =
       kept === undefined
-        ? await this.rewindKeepLength(id, rawKeepLength, internals.backend)
+        ? await this.rewindKeepLength(id, rawKeepLength)
         : kept.length;
     if (keepLength < rawKeepLength) {
       this.live.warn?.(
@@ -373,7 +331,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     }
 
     const denseBoundary = keepLength - 1;
-    const newSeedLength = await internals.backend.transaction(async (tx) => {
+    const newSeedLength = await this.port.transaction(async (tx) => {
       signal?.throwIfAborted();
       const head = await tx.getHead(id);
       if (denseBoundary > head.fHeadSequence) {
@@ -382,14 +340,14 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
           "INVALID_BOUNDARY",
         );
       }
+      let nextHead: { fEventId: string; fSequence: number } | undefined;
       if (denseBoundary < head.fHeadSequence) {
         await tx.deleteBridgeTail(id, denseBoundary + 1);
         const prev = denseBoundary === -1 ? undefined : await tx.getPrevBridge(id, denseBoundary);
-        if (prev === undefined) {
-          await tx.updateHead(id, "", -1);
-        } else {
-          await tx.updateHead(id, prev.fEventId, prev.fSequence);
-        }
+        nextHead =
+          prev === undefined
+            ? { fEventId: "", fSequence: -1 }
+            : { fEventId: prev.fEventId, fSequence: prev.fSequence };
       }
 
       const storedSeedLength = await tx.getSeedLength(id);
@@ -400,14 +358,36 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       }
 
       await tx.refreshTitle(id);
-      await tx.bumpRevision(id);
+      if (nextHead === undefined) {
+        await tx.bumpRevision(id);
+      } else {
+        // head 回退与 revision bump 是同一次行写：分成两条 UPDATE 就是两次行版本。
+        await tx.updateHeadAndRevision(id, nextHead.fEventId, nextHead.fSequence);
+      }
       return shrunk;
     });
 
-    internals.writeGuard.confirmHead(id, denseBoundary);
+    this.port.confirmHead(id, denseBoundary);
 
     if (live !== undefined) {
-      truncateLiveSession(live, keepLength);
+      // 内存 log 与存储同源的判据：上游 `Session.append` 用 `log.length` 当 seq，所以「内存条目数 - 1」
+      // 就是存储 head。内存**落后**于存储时（导入 / 取消与截断的竞态），不能拿内存做长度运算——
+      // `log.length = n` 会在尾部补出空洞，之后每次 append 的 seq 都与存储错位，撤回边界就会点到
+      // 存储里不存在的位置。落后就按存储前缀**整体重建**；`replaceLiveSessionLog` 顺手把 folds /
+      // derived / surface 这些派生缓存一并清掉。
+      const liveLength = (live as unknown as { log: readonly SessionEvent[] }).log.length;
+      let lastTurn: number;
+      if (liveLength < keepLength) {
+        const prefix =
+          kept ??
+          (await this.port.eventRows(id))
+            .map(rowToEvent)
+            .filter((event) => event.seq <= denseBoundary);
+        replaceLiveSessionLog(live, prefix);
+        lastTurn = prefix.findLast((event) => event.type === "turn/start")?.data.turn ?? 0;
+      } else {
+        lastTurn = truncateLiveSession(live, keepLength);
+      }
 
       this.live.resetProjections?.(live);
 
@@ -416,22 +396,36 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       if (agent !== undefined) {
         agent.requestHeaderLogged = false;
 
-        const lastTurn =
-          live.snapshotEvents().findLast((e) => e.type === "turn/start")?.data.turn ?? 0;
         const phase = (agent as unknown as { phase?: { lastTurn?: number } }).phase;
         if (phase !== undefined) phase.lastTurn = lastTurn;
       }
 
-      const handle = this.persistence.tracker.writerOf(id);
-      if (handle !== undefined) {
-        handle.resetAfterRewind(keepLength, newSeedLength === null ? undefined : newSeedLength);
-      }
+      this.port.resetWriterAfterRewind(
+        id,
+        keepLength,
+        newSeedLength === null ? undefined : newSeedLength,
+      );
 
       agent?.inbox?.clear();
 
-      await this.live.flush(live);
+      // flush 是「把 live 缓冲尽力落库」：失败不该让撤回失败，也不该阻断下面的缓存刷新——
+      // 撤回的正确性由库里的截断保证，缓存必须跟着新水位走，否则页面会一直显示撤回前的数据。
+      try {
+        await this.live.flush(live);
+      } catch (error: unknown) {
+        this.live.warn?.(
+          `session-rdb: flush after rewind for "${id}" failed (the stored log is already truncated; live buffers may lag): ${describeError(error)}`,
+        );
+      }
 
-      await this.refreshProjectionCache(live);
+      // 带上新水位：`write` 失败时缓存按这个水位截断兜底，而不是把撤回前的旧快照留在读路径上。
+      await this.refreshProjectionCache({
+        id: live.id,
+        header: live.header,
+        inheritedEventCount: live.inheritedEventCount,
+        headSeq: keepLength - 1,
+        snapshotEvents: () => live.snapshotEvents(),
+      });
     } else {
       // rewind 不读日志：缓存行按新水位截断（保留下来的投影单元仍在截断前缀内）
       await this.refreshProjectionCache({
@@ -444,20 +438,16 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     }
 
     // 撤回不改统计：请求已发起就已经消耗过（见 ADR-撤回不回退统计）。
-    return { header: rowToMeta(row), revision: (await internals.readStoredRevision(id))! };
+    return { header: rowToMeta(row), revision: (await this.port.readStoredRevision(id))! };
   }
 
   // 保留长度只依赖尾部窗口：从 rawKeepLength 往回读类型（有界），窗口没覆盖到最近一个 turn/end
   // 就翻倍重读，直到覆盖或到达前缀开头。
-  private async rewindKeepLength(
-    id: SessionId,
-    rawKeepLength: number,
-    backend: Backend,
-  ): Promise<number> {
+  private async rewindKeepLength(id: SessionId, rawKeepLength: number): Promise<number> {
     if (rawKeepLength === 0) return 0;
     let limit = 64;
     for (;;) {
-      const rows = await backend.getEventTypesBefore(id, rawKeepLength, limit);
+      const rows = await this.port.eventTypesBefore(id, rawKeepLength, limit);
       const types = [...rows].reverse().map((row) => row.fType);
       const windowStart = rawKeepLength - types.length;
       if (types.includes("turn/end") || windowStart === 0 || types.length >= rawKeepLength) {
@@ -542,7 +532,7 @@ export class SessionBranchRdb extends SessionBranch {
   }
 
   private readonly provider = new SessionBranchRdbProvider(
-    this.ctx.sessionPersistence as SessionPersistenceRdb,
+    (this.ctx.sessionPersistence as unknown as { branchPort(): BranchPort }).branchPort(),
     {
       getSession: (id) => this.ctx.sessions.get(id),
       getAgent: (id) => {
@@ -569,15 +559,34 @@ export class SessionBranchRdb extends SessionBranch {
             }
           | undefined;
         if (cache === undefined) return;
-        try {
-          if (session.headSeq !== undefined && cache.truncateTo !== undefined) {
+        const cold = session.snapshotEvents().length === 0;
+        if (cold && session.headSeq !== undefined && cache.truncateTo !== undefined) {
+          // 没有 live 会话：不 fold 日志，按新水位截断即可。
+          try {
             await cache.truncateTo(session.header, session.inheritedEventCount, session.headSeq);
-            return;
+          } catch (error: unknown) {
+            this.ctx.logger.warn(
+              `session-rdb: projection cache truncate after rewind for "${session.id}" failed: ${describeError(error)}`,
+            );
           }
+          return;
+        }
+        try {
           await cache.write(session);
         } catch (error: unknown) {
+          // 写回失败（例如带报错信息的日志让上游 fold 抛错、或 flush 失败）：退到「按新水位截断镜像」，
+          // 至少读路径与服务端的截断结果一致；否则要等实例重启才会从库里重新加载。
+          if (session.headSeq !== undefined && cache.truncateTo !== undefined) {
+            try {
+              await cache.truncateTo(session.header, session.inheritedEventCount, session.headSeq);
+            } catch (fallbackError: unknown) {
+              this.ctx.logger.warn(
+                `session-rdb: projection cache truncate fallback after rewind for "${session.id}" failed: ${describeError(fallbackError)}`,
+              );
+            }
+          }
           this.ctx.logger.warn(
-            `session-rdb: projection cache refresh after rewind for "${session.id}" failed (cache stays stale): ${String(error)}`,
+            `session-rdb: projection cache rebuild after rewind for "${session.id}" failed (fell back to truncating the cache at the new head): ${describeError(error)}\n${error instanceof Error ? (error.stack ?? "") : ""}`,
           );
         }
       },
@@ -618,3 +627,7 @@ export class SessionBranchRdb extends SessionBranch {
 }
 
 export default SessionBranchRdb;
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : "unknown error";
+}

package/src/branch/port.ts

@@ -0,0 +1,62 @@
+import type { SessionEvent, SessionHeader, SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionHandle, SessionPersistenceRevision } from "@deepseek-ai/dsh-session-persistence";
+import type { SessionLogOffset } from "@deepseek-ai/dsh-session";
+import type { BackendTx, EventRow, SessionRow } from "../backend.ts";
+
+/** 一份读出来的日志（分支只看这些字段）。 */
+export interface BranchLog {
+  meta: SessionHeader;
+  inheritedEventCount: number;
+  events: SessionEvent[];
+  tornFrom?: number;
+  incarnation: string;
+  revision: number;
+  storedCount: number;
+  migrated: boolean;
+}
+
+/**
+ * 分支能力需要的持久化面（端口）。
+ *
+ * 为什么不是整个 `SessionPersistenceRdb`：分支只需要「读日志前缀、写截断、认领复用映射」这几件事，
+ * 端口里的每个动词都有真实调用方（不是把服务的方法表转抄一遍）。rewind 走直连快路径，
+ * 所以这里保留了行级的 `eventRows` / `sessionRow` / `transaction`，而不是只给一个 `readLog`。
+ */
+export interface BranchPort {
+  readonly ready: Promise<void>;
+
+  readLog(
+    id: SessionId,
+    options?: { fromSeq?: number },
+    signal?: AbortSignal,
+  ): Promise<BranchLog | undefined>;
+
+  create(meta: SessionHeader, options?: { inheritedEventCount?: SessionLogOffset }): Promise<SessionHandle>;
+
+  eventRows(id: SessionId, fromSequence?: number): Promise<EventRow[]>;
+
+  eventTypesBefore(
+    id: SessionId,
+    beforeSequence: number,
+    limit: number,
+  ): Promise<Array<Pick<EventRow, "fSequence" | "fType">>>;
+
+  sessionRow(id: SessionId): Promise<SessionRow | undefined>;
+
+  eventTypeAt(id: SessionId, sequence: number): Promise<string | undefined>;
+
+  transaction<T>(fn: (tx: BackendTx) => Promise<T>): Promise<T>;
+
+  /** head 回退与 revision bump 是同一次行写，确认位点后写路径才允许继续 append。 */
+  confirmHead(id: SessionId, sequence: number): void;
+
+  readStoredRevision(id: SessionId): Promise<SessionPersistenceRevision | undefined>;
+
+  /** fork 复用父会话的事件行：子会话落写时按 seq 取回父行 id。 */
+  registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
+
+  dropReuseEventIds(childId: SessionId): void;
+
+  /** rewind 截断后把活跃写句柄的游标与 seed 长度挪到新水位。 */
+  resetWriterAfterRewind(id: SessionId, cursor: number, inheritedEventCount?: number): void;
+}

package/src/branch/semantics.ts

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import { SessionBranchError, type BranchAnchorMode } from "@morlay/session-branch";
+import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
+
+export function assertRewindBoundary(
+  id: SessionId,
+  toBoundary: number,
+  boundaryType: string | undefined,
+  head: number,
+): void {
+  if (toBoundary === -1) return;
+  if (toBoundary > head) {
+    throw new SessionBranchError(
+      `rewind boundary ${toBoundary} is beyond the stored head ${head}`,
+      "INVALID_BOUNDARY",
+    );
+  }
+  if (boundaryType === undefined) {
+    throw new SessionBranchError(
+      `rewind boundary ${toBoundary} does not exist in session "${id}"`,
+      "INVALID_BOUNDARY",
+    );
+  }
+  if (boundaryType !== "turn/end" && boundaryType !== "user/message") {
+    throw new SessionBranchError(
+      `rewind boundary ${toBoundary} is not a turn/end or user/message (${boundaryType})`,
+      "INVALID_BOUNDARY",
+    );
+  }
+}
+
+export function locateTurnEnd(
+  events: readonly SessionEvent[],
+  atSeq?: number,
+  mode: BranchAnchorMode = "after",
+): number {
+  const ends = events.filter((event) => event.type === "turn/end").map((event) => event.seq);
+  if (atSeq === undefined) {
+    const last = ends.at(-1);
+    if (last === undefined) throw new SessionBranchError("session has no closed turn", "OPEN_TURN");
+    return last;
+  }
+  if (mode === "before") {
+    let boundary = -1;
+    for (const seq of ends) {
+      if (seq < atSeq) boundary = seq;
+      else break;
+    }
+    return boundary;
+  }
+  const firstAfter = ends.find((seq) => seq >= atSeq);
+  if (firstAfter !== undefined) return firstAfter;
+
+  const lastStart = [...events].reverse().find((event) => event.type === "turn/start");
+  if (lastStart !== undefined && lastStart.seq <= atSeq) {
+    throw new SessionBranchError(`anchor ${atSeq} lies inside an open turn`, "OPEN_TURN");
+  }
+  const last = ends.at(-1);
+  if (last === undefined) throw new SessionBranchError("session has no closed turn", "OPEN_TURN");
+  return last;
+}
+
+export function renumber(events: readonly SessionEvent[], offset: number): SessionEvent[] {
+  return events.map((event, index) => ({ ...event, seq: offset + index }) as SessionEvent);
+}
+
+export function mintSessionId(): SessionId {
+  return `session-${randomUUID()}` as SessionId;
+}