@morlay/session-branch 0.0.7 → 0.0.9-alpha.0

package/README.md

@@ -4,6 +4,8 @@
 （rewind / forkFrom / readBranchPrefix）、高层服务 `SessionBranch`
 （`ctx.sessionBranch`）与共享的版本树投影 `buildTimeline`。
 
+跨包术语见根 [`.agents/CONTEXT.md`](../../../.agents/CONTEXT.md)，本包的决策见 [`.agents/adrs/`](./.agents/adrs)。
+
 ## 与上游 `SessionHandle` 的关系
 
 上游持久化模型是 `SessionHandle`（append-only：`create` / `open` / `append` /
@@ -34,7 +36,7 @@ interface SessionBranchProvider {
   边界前缀 + `seedSuffix`，不触碰源会话。
 - `rewind`：唯一的显式回退原语，事务整体提交或回滚；**支持 live 会话**
   （内存 log 截断 + 派生缓存复位 + handle cursor / 继承前缀对齐，详见
-  `@morlay/session-rdb` 的 [docs/branch.md](../session-rdb/docs/branch.md)）。
+  `@morlay/session-rdb` 的 [分支能力](../session-rdb/.agents/designs/20260917-分支能力.md)）。
 
 ## 版本树
 
@@ -42,6 +44,5 @@ interface SessionBranchProvider {
 lineage）+ 每会话自有后缀（`seq >= seedLength` 的 `session-branch/version`
 事件）投影完整版本树。
 
-> 版本效果事件携带 `ignorable: true`：非 branch 读者凭信封安全跳过，事件
-> 本身原样落库——live 会话从内存 log 读到效果，cold 会话经读路径恢复效果
-> 详情（见 [ADR 0003](./docs/adr/0003-版本效果以ignorable事件原样落库.md)）。
+版本效果事件携带 `ignorable: true` 并**原样落库**，因此 cold 会话也能恢复效果详情
+（见 [ADR-版本效果以ignorable事件原样落库](./.agents/adrs/20260917-版本效果以ignorable事件原样落库.md)）。

package/dist/index.d.mts

@@ -106,7 +106,11 @@ type OwnEventsReader = (id: SessionId, fromSeq: number, signal?: AbortSignal) =>
 declare function buildTimeline(snapshots: readonly BranchSnapshot[], readOwnEvents: OwnEventsReader, sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
 //#endregion
 //#region src/balance.d.ts
-declare function balanceRewindPrefix(events: readonly SessionEvent[]): SessionEvent[];
+interface BalanceRewindPrefixOptions {
+  keepOpenTail?: boolean;
+}
+declare function balanceRewindPrefix(events: readonly SessionEvent[], options?: BalanceRewindPrefixOptions): SessionEvent[];
+declare function rewindKeepLength(types: readonly string[], rawKeepLength: number): number;
 //#endregion
 //#region src/index.d.ts
 declare module "@deepseek-ai/cordis" {
@@ -116,4 +120,4 @@ declare module "@deepseek-ai/cordis" {
 }
 declare function apply(_ctx: Context): void;
 //#endregion
-export { type BranchAnchorMode, BranchBoundary, BranchForkMeta, BranchTimeline, BranchVersionNode, CascadePolicy, EditableBlockKind, ForkFromOptions, type OwnEventsReader, SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchEffect, SessionBranchError, SessionBranchErrorCode, SessionBranchInverse, type SessionBranchProvider, SessionBranchVersionEvent, SessionBranchVersionEventEnvelope, VersionOperation, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent };
+export { type BranchAnchorMode, BranchBoundary, BranchForkMeta, BranchTimeline, BranchVersionNode, CascadePolicy, EditableBlockKind, ForkFromOptions, type OwnEventsReader, SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchEffect, SessionBranchError, SessionBranchErrorCode, SessionBranchInverse, type SessionBranchProvider, SessionBranchVersionEvent, SessionBranchVersionEventEnvelope, VersionOperation, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent, rewindKeepLength };

package/dist/index.mjs

@@ -83,11 +83,41 @@ async function buildTimeline(snapshots, readOwnEvents, sessionId, signal) {
 }
 //#endregion
 //#region src/balance.ts
-function balanceRewindPrefix(events) {
+function balanceRewindPrefix(events, options = {}) {
 	let keep = events.length;
+	let openIndex = -1;
+	let open;
+	for (let index = 0; index < events.length; index += 1) {
+		const event = events[index];
+		if (event.type === "step/start") {
+			if (open !== void 0) {
+				keep = index;
+				break;
+			}
+			open = {
+				turn: event.data.turn,
+				step: event.data.step
+			};
+			openIndex = index;
+			continue;
+		}
+		if (event.type === "step/end") {
+			if (open === void 0 || open.turn !== event.data.turn || open.step !== event.data.step) {
+				keep = index;
+				break;
+			}
+			open = void 0;
+			openIndex = -1;
+		}
+	}
+	if (options.keepOpenTail !== true && open !== void 0) keep = Math.min(keep, openIndex);
+	return events.slice(0, keep);
+}
+function rewindKeepLength(types, rawKeepLength) {
+	let relativeKeep = types.length;
 	let openStepEnds = 0;
-	for (let index = events.length - 1; index >= 0; index -= 1) {
-		const type = events[index]?.type;
+	for (let index = types.length - 1; index >= 0; index -= 1) {
+		const type = types[index];
 		if (type === "turn/end") break;
 		if (type === "step/end") {
 			openStepEnds += 1;
@@ -95,13 +125,13 @@ function balanceRewindPrefix(events) {
 		}
 		if (type === "step/start") {
 			if (openStepEnds > 0) openStepEnds -= 1;
-			else keep = index;
+			else relativeKeep = index;
 		}
 	}
-	return events.slice(0, keep);
+	return Math.max(0, rawKeepLength - types.length + relativeKeep);
 }
 //#endregion
 //#region src/index.ts
 function apply(_ctx) {}
 //#endregion
-export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent };
+export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent, rewindKeepLength };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/session-branch",
-  "version": "0.0.7",
+  "version": "0.0.9-alpha.0",
   "description": "Provider abstraction + high-level service for rewind / retry / fork over DeepSeek Harness event-sourced sessions.",
   "keywords": [
     "dsh",
@@ -13,7 +13,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/morlay/better-session.git"
+    "url": "https://github.com/morlay/dsh-plugin.git"
   },
   "files": [
     "dist",
@@ -30,9 +30,9 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.2"
   },
   "dsh": {
     "bundle": {

package/src/balance.ts

@@ -1,23 +1,64 @@
 import type { SessionEvent } from "@deepseek-ai/dsh-session";
 
-export function balanceRewindPrefix(events: readonly SessionEvent[]): SessionEvent[] {
+export interface BalanceRewindPrefixOptions {
+  // 导出 / 导入的是整段日志：尾部未闭合的 step/start 是中断运行的正常形状，交给上游 resume 补 closers；
+  // rewind / fork 之后会紧接着追加新的 step/start，悬空的旧 step/start 会让它报错，必须一并丢弃。
+  keepOpenTail?: boolean;
+}
+
+// 保留前缀配平：每个 step/start 必须与同 turn/step 的 step/end 成对。日志已不平衡（step/end 无配对、
+// step/start 撞未闭合）时从配平点起丢弃尾部（自愈），否则下游 token-meter 折叠会报 step/end 无配对。
+export function balanceRewindPrefix(
+  events: readonly SessionEvent[],
+  options: BalanceRewindPrefixOptions = {},
+): SessionEvent[] {
   let keep = events.length;
-  // 从尾部向前待配对的 step/end 数（每个配对它之前的 step/start）。
+  let openIndex = -1;
+  let open: { turn: number; step: number } | undefined;
+
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index]!;
+    if (event.type === "step/start") {
+      if (open !== undefined) {
+        keep = index;
+        break;
+      }
+      open = { turn: event.data.turn, step: event.data.step };
+      openIndex = index;
+      continue;
+    }
+    if (event.type === "step/end") {
+      if (open === undefined || open.turn !== event.data.turn || open.step !== event.data.step) {
+        keep = index;
+        break;
+      }
+      open = undefined;
+      openIndex = -1;
+    }
+  }
+
+  if (options.keepOpenTail !== true && open !== undefined) keep = Math.min(keep, openIndex);
+  return events.slice(0, keep);
+}
+
+// rewind 只按 seq 读尾部窗口（`types` 是窗口内升序的事件类型），在窗口上做同样的配对修剪：
+// 从尾部往回扫，遇到 turn/end 即停（它之前的内容与保留前缀的尾部无关）；尾部未闭合的
+// step/start 一并丢弃，避免它之后的追加（重放的新 step）撞上未闭合的旧 step。
+// 调用方必须保证窗口覆盖到「最近一个 turn/end」或前缀开头，否则结果不完整。
+export function rewindKeepLength(types: readonly string[], rawKeepLength: number): number {
+  let relativeKeep = types.length;
   let openStepEnds = 0;
-  for (let index = events.length - 1; index >= 0; index -= 1) {
-    const type = events[index]?.type;
-    if (type === "turn/end") break; // 轮次闭合：之前的 step 全部配对。
+  for (let index = types.length - 1; index >= 0; index -= 1) {
+    const type = types[index];
+    if (type === "turn/end") break;
     if (type === "step/end") {
       openStepEnds += 1;
       continue;
     }
     if (type === "step/start") {
-      if (openStepEnds > 0) {
-        openStepEnds -= 1; // 配对成功。
-      } else {
-        keep = index; // 孤儿 step/start：剔除它及其后。
-      }
+      if (openStepEnds > 0) openStepEnds -= 1;
+      else relativeKeep = index;
     }
   }
-  return events.slice(0, keep);
+  return Math.max(0, rawKeepLength - types.length + relativeKeep);
 }

package/src/index.ts

@@ -5,7 +5,7 @@ export { SessionBranch } from "./branch.ts";
 export type { SessionBranchProvider, BranchAnchorMode } from "./provider.ts";
 export { buildTimeline } from "./timeline.ts";
 export type { OwnEventsReader } from "./timeline.ts";
-export { balanceRewindPrefix } from "./balance.ts";
+export { balanceRewindPrefix, rewindKeepLength } from "./balance.ts";
 export * from "./types.ts";
 
 declare module "@deepseek-ai/cordis" {
@@ -14,7 +14,4 @@ declare module "@deepseek-ai/cordis" {
   }
 }
 
-export function apply(_ctx: Context): void {
-  // 契约层不发布服务：ctx.sessionBranch 由实现 provider 的后端插件注册。
-  // 保留 apply 仅为 cordis 插件装配兼容，不注入任何服务。
-}
+export function apply(_ctx: Context): void {}

package/src/timeline.ts

@@ -26,7 +26,6 @@ export async function buildTimeline(
 ): Promise<BranchTimeline> {
   const byId = new Map(snapshots.map((snapshot) => [snapshot.header.id, snapshot] as const));
 
-  // 回溯到根（当前会话 → 祖先链）。
   const ancestors: SessionId[] = [];
   let cursor: SessionId | undefined = sessionId;
   const seen = new Set<SessionId>();
@@ -43,7 +42,6 @@ export async function buildTimeline(
     throw new SessionBranchError(`session "${sessionId}" is not persisted`, "SESSION_NOT_FOUND");
   }
 
-  // 根向下的完整后代（BFS；按 createdAt 稳定排序）。
   const ordered: SessionId[] = [];
   const queue: SessionId[] = [rootId];
   while (queue.length > 0) {
@@ -73,10 +71,10 @@ export async function buildTimeline(
       seedLength: snapshot.inheritedEventCount ?? 0,
       createdAt: header.createdAt,
     };
-    // 根节点不可能带版本效果；其余节点读自有后缀。
+
     if (header.parentSession !== undefined) {
       const events = await readOwnEvents(header.id, node.seedLength, signal);
-      // 结构化守卫 + find（版本事件类型不在固化的 SessionEventType 中）。
+
       let version: SessionBranchVersionEventEnvelope | undefined;
       for (const event of events) {
         if (isSessionBranchVersionEvent(event)) {

package/src/types.ts

@@ -1,9 +1,6 @@
 import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 import type { SessionEventMap } from "@deepseek-ai/dsh-session";
 
-// 编译期诊断：module augmentation 后 `keyof SessionEventMap` 可见，但
-// dsh-session 内已解析的 `SessionEventType` 别名不会重求值——因此
-// `SessionEvent<"session-branch/version">` 泛型不可用，守卫/消费走结构化。
 type _BranchKeyCheck = "session-branch/version" extends keyof SessionEventMap ? true : false;
 export const _branchKeyVisible: _BranchKeyCheck = true as const;