@morlay/session-branch 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @morlay/session-branch
+
+分支式会话编辑的**契约层**：定义数据层分支原语 `SessionBranchProvider`
+（rewind / forkFrom / readBranchPrefix）、高层服务 `SessionBranch`
+（`ctx.sessionBranch`）与共享的版本树投影 `buildTimeline`。
+
+## 与上游 `SessionPersistence` 的关系
+
+| 面     | 上游 `PersistenceBackend`                     | 本包 `SessionBranchProvider`                           |
+| ------ | --------------------------------------------- | ------------------------------------------------------ |
+| 覆盖   | 持久读写 + 崩溃修复（append-only）            | 显式回退 + 闭合边界派生（分支面）                      |
+| 原语   | `loadStored` / `appendBatch` / `commitRepair` | `readBranchPrefix` / `forkFrom` / `rewind`             |
+| 实现方 | JSONL / RDB 等                                | RDB 等（`@morlay/session-rdb` 同时实现两者，形成闭环） |
+
+## Provider 抽象
+
+```ts
+interface SessionBranchProvider {
+  readBranchPrefix(id, atSeq?, mode?, signal?): Promise<BranchBoundary>;
+  forkFrom(sourceId, options?, signal?): Promise<SessionId>;
+  rewind(id, toBoundary, signal?): Promise<SessionPersistenceSnapshot>;
+}
+```
+
+- `readBranchPrefix`：定位 `atSeq` 锚定的闭合 `turn/end` 边界并返回前缀；
+  `mode: "after"`（包含目标轮，fork 语义）/ `"before"`（排除目标轮，编辑 /
+  重掷 / 重试语义）。
+- `forkFrom`：纯 append——新会话（`parentSession` / `seedLength`），seed =
+  边界前缀 + `seedSuffix`，不触碰源会话。
+- `rewind`：唯一改写事件 log 的操作，事务整体提交或回滚；**支持 live
+  会话**（内存 log 截断 + 派生缓存复位 + coordinator cursor 同步，见
+  `@morlay/session-rdb` 的 `SessionBranchRdbProvider`）。
+- `syncLiveCursor(sessionId)`：编排层把 ignorable 版本效果 push 进 live log
+  后（不发布、不进 write-behind 缓冲），用其对齐 coordinator cursor，避免
+  后续 append 的 seq 校验错位（默认空实现，rdb 覆写）。
+
+## 版本树
+
+`buildTimeline(snapshots, readOwnEvents, sessionId)` 从会话快照（header
+lineage）+ 每会话自有后缀（`seq >= seedLength` 的 `session-branch/version`
+事件）投影完整版本树。
+
+> 版本效果事件携带 `ignorable: true`（对核心可跳过、**不进 canonical log**），
+> live 会话从内存 log 读到效果，cold 会话 timeline 只有 lineage 骨架。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: session-branch
+      name: "@morlay/session-branch"

package/dist/index.d.mts

@@ -0,0 +1,121 @@
+import { Context, Service } from "@deepseek-ai/cordis";
+import { SessionEvent, SessionEventMap, SessionId } from "@deepseek-ai/dsh-session";
+import { SessionPersistenceSnapshot } from "@deepseek-ai/dsh-session-persistence";
+//#region src/types.d.ts
+type _BranchKeyCheck = "session-branch/version" extends keyof SessionEventMap ? true : false;
+declare const _branchKeyVisible: _BranchKeyCheck;
+declare const SESSION_BRANCH_VERSION_SCHEMA = 1;
+type CascadePolicy = "truncate" | "preserve";
+type VersionOperation = "edit" | "reroll" | "retry" | "fork" | "rewind";
+type EditableBlockKind = "user" | "assistant.reasoning" | "assistant.response";
+interface SessionBranchEffect {
+  id: string;
+  operation: VersionOperation;
+  cascade: CascadePolicy;
+  targetTurn: number;
+  targetEventSeq: number;
+  targetBlockIndex?: number;
+  blockKind?: EditableBlockKind;
+  before?: string;
+  after?: string;
+}
+interface SessionBranchInverse {
+  kind: "restore-version";
+  sessionId: SessionId;
+}
+interface SessionBranchVersionEvent {
+  schemaVersion: typeof SESSION_BRANCH_VERSION_SCHEMA;
+  effect: SessionBranchEffect;
+  inverse: SessionBranchInverse;
+}
+declare module "@deepseek-ai/dsh-session" {
+  interface SessionEventMap {
+    "session-branch/version": SessionBranchVersionEvent;
+  }
+}
+interface BranchBoundary {
+  seq: number;
+  events: readonly SessionEvent[];
+}
+interface BranchForkMeta {
+  cwd?: string;
+  createdAt?: number;
+  agentPreset?: string;
+  origin?: "subagent";
+  delegationDepth?: number;
+}
+interface ForkFromOptions {
+  atSeq?: number;
+  anchorMode?: BranchAnchorMode;
+  seedSuffix?: readonly SessionEvent[];
+  childSessionId?: SessionId;
+  meta?: BranchForkMeta;
+}
+interface BranchVersionNode {
+  sessionId: SessionId;
+  parentSessionId?: SessionId;
+  seedLength: number;
+  createdAt: number;
+  effect?: SessionBranchEffect;
+  inverseSessionId?: SessionId;
+}
+interface BranchTimeline {
+  root: BranchVersionNode;
+  nodes: BranchVersionNode[];
+}
+type SessionBranchErrorCode = "SESSION_NOT_FOUND" | "INVALID_BOUNDARY" | "OPEN_TURN" | "FORK_UNAVAILABLE" | "REWIND_CONFLICT";
+declare class SessionBranchError extends Error {
+  readonly code: SessionBranchErrorCode;
+  constructor(message: string, code: SessionBranchErrorCode);
+}
+interface SessionBranchVersionEventEnvelope {
+  type: "session-branch/version";
+  seq: number;
+  time: number;
+  ignorable?: true;
+  data: SessionBranchVersionEvent;
+}
+declare function isSessionBranchVersionEvent(event: SessionEvent | {
+  type: string;
+  data: unknown;
+}): event is SessionBranchVersionEventEnvelope;
+//#endregion
+//#region src/provider.d.ts
+type BranchAnchorMode = "after" | "before";
+interface SessionBranchProvider {
+  readonly name: string;
+  readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+}
+//#endregion
+//#region src/branch.d.ts
+declare abstract class SessionBranch extends Service {
+  constructor(ctx: import("@deepseek-ai/cordis").Context);
+  abstract readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  abstract forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  abstract rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
+  syncLiveCursor(_sessionId: SessionId): void;
+}
+//#endregion
+//#region src/timeline.d.ts
+type BranchSnapshot = SessionPersistenceSnapshot & {
+  inheritedEventCount: number;
+};
+type OwnEventsReader = (id: SessionId, fromSeq: number, signal?: AbortSignal) => Promise<readonly import("@deepseek-ai/dsh-session").SessionEvent[]>;
+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[];
+//#endregion
+//#region src/index.d.ts
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    sessionBranch: SessionBranch;
+  }
+}
+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 };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/provider.ts","../src/branch.ts","../src/timeline.ts","../src/balance.ts","../src/index.ts"],"mappings":";;;;KAMK,yDAAyD;cACjD,mBAAmB;cAEnB;KAED;KAEA;KAEA;UAEK;EACf;EACA,WAAW;EACX,SAAS;EAET;EAEA;EACA;EACA,YAAY;EAEZ;EAEA;;UAGe;EACf;EACA,WAAW;;UAGI;EACf,sBAAsB;EACtB,QAAQ;EACR,SAAS;;;YAIC;IACR,0BAA0B;;;UAIb;EACf;EAEA,iBAAiB;;UAGF;EACf;EACA;EACA;EACA;EACA;;UAGe;EACf;EAEA,aAHe;EAKf,sBAAsB;EAEtB,iBAAiB;EAEjB,OAAO;;UAGQ;EACf,WAAW;EACX,kBAAkB;EAElB;EACA;EAEA,SAAS;EAET,mBAAmB;;UAGJ;EACf,MAAM;EACN,OAAO;;KAGG;cAOC,2BAA2B;WAC7B,MAAM;EACf,YAAY,iBAAiB,MAAM;;UAOpB;EACf;EACA;EACA;EACA;EACA,MAAM;;iBAGQ,4BACd,OAAO;EAAiB;EAAc;IACrC,SAAS;;;KCnHA;UAEK;WACN;EAET,iBACE,IAAI,WACJ,gBACA,OAAO,kBACP,SAAS,cACR,QAAQ;EAEX,SACE,UAAU,WACV,UAAU,iBACV,SAAS,cACR,QAAQ;EAEX,OACE,IAAI,WACJ,oBACA,SAAS,cACR,QAAQ;;;;uBCrBS,sBAAsB;EAC1C,YAAY,mCAAmC;WAItC,iBACP,IAAI,WACJ,gBACA,OAFI,kBAGJ,SAAS,cACR,QAAQ;WAEF,SACP,UAAU,WACV,UAAU,iBACV,SAAS,cACR,QAAQ;WAEF,OACP,IAAI,WACJ,oBACA,SAAS,cACR,QAAQ;WAEF,SAAS,WAAW,WAAW,SAAS,cAAc,QAAQ;EAEvE,eAAe,YAAY;;;;KCrBjB,iBAAiB;EAC3B;;KAGU,mBACV,IAAI,WACJ,iBACA,SAAS,gBACN,oDAAoD;iBAEnC,cACpB,oBAAoB,kBACpB,eAAe,iBACf,WAAW,WACX,SAAS,cACR,QAAQ;;;iBCvBK,oBAAoB,iBAAiB,iBAAiB;;;;YCS1D;IACR,eAAe;;;iBAIH,MAAM,MAAM"}

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region src/branch.ts
+var SessionBranch = class extends Service {
+	constructor(ctx) {
+		super(ctx, "sessionBranch");
+	}
+	syncLiveCursor(_sessionId) {}
+};
+//#endregion
+//#region src/types.ts
+const _branchKeyVisible = true;
+const SESSION_BRANCH_VERSION_SCHEMA = 1;
+var SessionBranchError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "SessionBranchError";
+		this.code = code;
+	}
+};
+function isSessionBranchVersionEvent(event) {
+	return event.type === "session-branch/version" && event.data.schemaVersion === 1;
+}
+//#endregion
+//#region src/timeline.ts
+async function buildTimeline(snapshots, readOwnEvents, sessionId, signal) {
+	const byId = new Map(snapshots.map((snapshot) => [snapshot.header.id, snapshot]));
+	const ancestors = [];
+	let cursor = sessionId;
+	const seen = /* @__PURE__ */ new Set();
+	while (cursor !== void 0) {
+		if (seen.has(cursor)) throw new SessionBranchError("lineage contains a cycle", "INVALID_BOUNDARY");
+		seen.add(cursor);
+		ancestors.push(cursor);
+		cursor = byId.get(cursor)?.header.parentSession;
+	}
+	const rootId = ancestors.at(-1);
+	if (rootId === void 0) throw new SessionBranchError(`session "${sessionId}" is not persisted`, "SESSION_NOT_FOUND");
+	const ordered = [];
+	const queue = [rootId];
+	while (queue.length > 0) {
+		const id = queue.shift();
+		if (id === void 0) continue;
+		ordered.push(id);
+		const children = snapshots.filter((snapshot) => snapshot.header.parentSession === id).sort((left, right) => left.header.createdAt - right.header.createdAt || String(left.header.id).localeCompare(String(right.header.id))).map((snapshot) => snapshot.header.id);
+		queue.push(...children);
+	}
+	const nodes = [];
+	const effectIds = /* @__PURE__ */ new Set();
+	for (const id of ordered) {
+		const snapshot = byId.get(id);
+		if (snapshot === void 0) continue;
+		const header = snapshot.header;
+		const node = {
+			sessionId: header.id,
+			...header.parentSession === void 0 ? {} : { parentSessionId: header.parentSession },
+			seedLength: snapshot.inheritedEventCount ?? 0,
+			createdAt: header.createdAt
+		};
+		if (header.parentSession !== void 0) {
+			const events = await readOwnEvents(header.id, node.seedLength, signal);
+			let version;
+			for (const event of events) if (isSessionBranchVersionEvent(event)) {
+				if (version !== void 0) throw new SessionBranchError(`session ${header.id} carries multiple own version effects`, "INVALID_BOUNDARY");
+				version = event;
+			}
+			if (version !== void 0) {
+				const data = version.data;
+				if (data.inverse.kind !== "restore-version" || data.inverse.sessionId !== header.parentSession) throw new SessionBranchError(`session ${header.id} version inverse does not match its parent`, "INVALID_BOUNDARY");
+				if (effectIds.has(data.effect.id)) throw new SessionBranchError(`version effect ${data.effect.id} is duplicated`, "INVALID_BOUNDARY");
+				effectIds.add(data.effect.id);
+				node.effect = data.effect;
+				node.inverseSessionId = data.inverse.sessionId;
+			}
+		}
+		nodes.push(node);
+	}
+	const root = nodes.find((node) => node.parentSessionId === void 0);
+	if (root === void 0) throw new SessionBranchError(`session "${sessionId}" lineage has no root`, "SESSION_NOT_FOUND");
+	return {
+		root,
+		nodes
+	};
+}
+//#endregion
+//#region src/balance.ts
+function balanceRewindPrefix(events) {
+	let keep = events.length;
+	let openStepEnds = 0;
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const type = events[index]?.type;
+		if (type === "turn/end") break;
+		if (type === "step/end") {
+			openStepEnds += 1;
+			continue;
+		}
+		if (type === "step/start") {
+			if (openStepEnds > 0) openStepEnds -= 1;
+			else keep = index;
+		}
+	}
+	return events.slice(0, keep);
+}
+//#endregion
+//#region src/index.ts
+function apply(_ctx) {}
+//#endregion
+export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/branch.ts","../src/types.ts","../src/timeline.ts","../src/balance.ts","../src/index.ts"],"sourcesContent":["import { Service } from \"@deepseek-ai/cordis\";\nimport type { SessionId } from \"@deepseek-ai/dsh-session\";\nimport type { SessionPersistenceSnapshot } from \"@deepseek-ai/dsh-session-persistence\";\nimport type { BranchBoundary, BranchTimeline, ForkFromOptions } from \"./types.ts\";\n\nexport abstract class SessionBranch extends Service {\n  constructor(ctx: import(\"@deepseek-ai/cordis\").Context) {\n    super(ctx, \"sessionBranch\");\n  }\n\n  abstract readBranchPrefix(\n    id: SessionId,\n    atSeq?: number,\n    mode?: import(\"./provider.ts\").BranchAnchorMode,\n    signal?: AbortSignal,\n  ): Promise<BranchBoundary>;\n\n  abstract forkFrom(\n    sourceId: SessionId,\n    options?: ForkFromOptions,\n    signal?: AbortSignal,\n  ): Promise<SessionId>;\n\n  abstract rewind(\n    id: SessionId,\n    toBoundary: number,\n    signal?: AbortSignal,\n  ): Promise<SessionPersistenceSnapshot>;\n\n  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;\n\n  syncLiveCursor(_sessionId: SessionId): void {\n    // 默认无操作。\n  }\n}\n","import type { SessionEvent, SessionId } from \"@deepseek-ai/dsh-session\";\nimport type { SessionEventMap } from \"@deepseek-ai/dsh-session\";\n\n// 编译期诊断：module augmentation 后 `keyof SessionEventMap` 可见，但\n// dsh-session 内已解析的 `SessionEventType` 别名不会重求值——因此\n// `SessionEvent<\"session-branch/version\">` 泛型不可用，守卫/消费走结构化。\ntype _BranchKeyCheck = \"session-branch/version\" extends keyof SessionEventMap ? true : false;\nexport const _branchKeyVisible: _BranchKeyCheck = true as const;\n\nexport const SESSION_BRANCH_VERSION_SCHEMA = 1;\n\nexport type CascadePolicy = \"truncate\" | \"preserve\";\n\nexport type VersionOperation = \"edit\" | \"reroll\" | \"retry\" | \"fork\" | \"rewind\";\n\nexport type EditableBlockKind = \"user\" | \"assistant.reasoning\" | \"assistant.response\";\n\nexport interface SessionBranchEffect {\n  id: string;\n  operation: VersionOperation;\n  cascade: CascadePolicy;\n\n  targetTurn: number;\n\n  targetEventSeq: number;\n  targetBlockIndex?: number;\n  blockKind?: EditableBlockKind;\n\n  before?: string;\n\n  after?: string;\n}\n\nexport interface SessionBranchInverse {\n  kind: \"restore-version\";\n  sessionId: SessionId;\n}\n\nexport interface SessionBranchVersionEvent {\n  schemaVersion: typeof SESSION_BRANCH_VERSION_SCHEMA;\n  effect: SessionBranchEffect;\n  inverse: SessionBranchInverse;\n}\n\ndeclare module \"@deepseek-ai/dsh-session\" {\n  interface SessionEventMap {\n    \"session-branch/version\": SessionBranchVersionEvent;\n  }\n}\n\nexport interface BranchBoundary {\n  seq: number;\n\n  events: readonly SessionEvent[];\n}\n\nexport interface BranchForkMeta {\n  cwd?: string;\n  createdAt?: number;\n  agentPreset?: string;\n  origin?: \"subagent\";\n  delegationDepth?: number;\n}\n\nexport interface ForkFromOptions {\n  atSeq?: number;\n\n  anchorMode?: import(\"./provider.ts\").BranchAnchorMode;\n\n  seedSuffix?: readonly SessionEvent[];\n\n  childSessionId?: SessionId;\n\n  meta?: BranchForkMeta;\n}\n\nexport interface BranchVersionNode {\n  sessionId: SessionId;\n  parentSessionId?: SessionId;\n\n  seedLength: number;\n  createdAt: number;\n\n  effect?: SessionBranchEffect;\n\n  inverseSessionId?: SessionId;\n}\n\nexport interface BranchTimeline {\n  root: BranchVersionNode;\n  nodes: BranchVersionNode[];\n}\n\nexport type SessionBranchErrorCode =\n  | \"SESSION_NOT_FOUND\"\n  | \"INVALID_BOUNDARY\"\n  | \"OPEN_TURN\"\n  | \"FORK_UNAVAILABLE\"\n  | \"REWIND_CONFLICT\";\n\nexport class SessionBranchError extends Error {\n  readonly code: SessionBranchErrorCode;\n  constructor(message: string, code: SessionBranchErrorCode) {\n    super(message);\n    this.name = \"SessionBranchError\";\n    this.code = code;\n  }\n}\n\nexport interface SessionBranchVersionEventEnvelope {\n  type: \"session-branch/version\";\n  seq: number;\n  time: number;\n  ignorable?: true;\n  data: SessionBranchVersionEvent;\n}\n\nexport function isSessionBranchVersionEvent(\n  event: SessionEvent | { type: string; data: unknown },\n): event is SessionBranchVersionEventEnvelope {\n  return (\n    event.type === \"session-branch/version\" &&\n    (event.data as { schemaVersion?: unknown }).schemaVersion === SESSION_BRANCH_VERSION_SCHEMA\n  );\n}\n","import type { SessionId } from \"@deepseek-ai/dsh-session\";\nimport type { SessionPersistenceSnapshot } from \"@deepseek-ai/dsh-session-persistence\";\nimport {\n  SessionBranchError,\n  isSessionBranchVersionEvent,\n  type BranchTimeline,\n  type BranchVersionNode,\n  type SessionBranchVersionEventEnvelope,\n} from \"./types.ts\";\n\nexport type BranchSnapshot = SessionPersistenceSnapshot & {\n  inheritedEventCount: number;\n};\n\nexport type OwnEventsReader = (\n  id: SessionId,\n  fromSeq: number,\n  signal?: AbortSignal,\n) => Promise<readonly import(\"@deepseek-ai/dsh-session\").SessionEvent[]>;\n\nexport async function buildTimeline(\n  snapshots: readonly BranchSnapshot[],\n  readOwnEvents: OwnEventsReader,\n  sessionId: SessionId,\n  signal?: AbortSignal,\n): Promise<BranchTimeline> {\n  const byId = new Map(snapshots.map((snapshot) => [snapshot.header.id, snapshot] as const));\n\n  // 回溯到根（当前会话 → 祖先链）。\n  const ancestors: SessionId[] = [];\n  let cursor: SessionId | undefined = sessionId;\n  const seen = new Set<SessionId>();\n  while (cursor !== undefined) {\n    if (seen.has(cursor))\n      throw new SessionBranchError(\"lineage contains a cycle\", \"INVALID_BOUNDARY\");\n    seen.add(cursor);\n    ancestors.push(cursor);\n    const snapshot = byId.get(cursor);\n    cursor = snapshot?.header.parentSession;\n  }\n  const rootId = ancestors.at(-1);\n  if (rootId === undefined) {\n    throw new SessionBranchError(`session \"${sessionId}\" is not persisted`, \"SESSION_NOT_FOUND\");\n  }\n\n  // 根向下的完整后代（BFS；按 createdAt 稳定排序）。\n  const ordered: SessionId[] = [];\n  const queue: SessionId[] = [rootId];\n  while (queue.length > 0) {\n    const id = queue.shift();\n    if (id === undefined) continue;\n    ordered.push(id);\n    const children = snapshots\n      .filter((snapshot) => snapshot.header.parentSession === id)\n      .sort(\n        (left, right) =>\n          left.header.createdAt - right.header.createdAt ||\n          String(left.header.id).localeCompare(String(right.header.id)),\n      )\n      .map((snapshot) => snapshot.header.id);\n    queue.push(...children);\n  }\n\n  const nodes: BranchVersionNode[] = [];\n  const effectIds = new Set<string>();\n  for (const id of ordered) {\n    const snapshot = byId.get(id);\n    if (snapshot === undefined) continue;\n    const header = snapshot.header;\n    const node: BranchVersionNode = {\n      sessionId: header.id,\n      ...(header.parentSession === undefined ? {} : { parentSessionId: header.parentSession }),\n      seedLength: snapshot.inheritedEventCount ?? 0,\n      createdAt: header.createdAt,\n    };\n    // 根节点不可能带版本效果；其余节点读自有后缀。\n    if (header.parentSession !== undefined) {\n      const events = await readOwnEvents(header.id, node.seedLength, signal);\n      // 结构化守卫 + find（版本事件类型不在固化的 SessionEventType 中）。\n      let version: SessionBranchVersionEventEnvelope | undefined;\n      for (const event of events) {\n        if (isSessionBranchVersionEvent(event)) {\n          if (version !== undefined) {\n            throw new SessionBranchError(\n              `session ${header.id} carries multiple own version effects`,\n              \"INVALID_BOUNDARY\",\n            );\n          }\n          version = event;\n        }\n      }\n      if (version !== undefined) {\n        const data = version.data;\n        if (\n          data.inverse.kind !== \"restore-version\" ||\n          data.inverse.sessionId !== header.parentSession\n        ) {\n          throw new SessionBranchError(\n            `session ${header.id} version inverse does not match its parent`,\n            \"INVALID_BOUNDARY\",\n          );\n        }\n        if (effectIds.has(data.effect.id)) {\n          throw new SessionBranchError(\n            `version effect ${data.effect.id} is duplicated`,\n            \"INVALID_BOUNDARY\",\n          );\n        }\n        effectIds.add(data.effect.id);\n        node.effect = data.effect;\n        node.inverseSessionId = data.inverse.sessionId;\n      }\n    }\n    nodes.push(node);\n  }\n\n  const root = nodes.find((node) => node.parentSessionId === undefined);\n  if (root === undefined) {\n    throw new SessionBranchError(`session \"${sessionId}\" lineage has no root`, \"SESSION_NOT_FOUND\");\n  }\n  return { root, nodes };\n}\n","import type { SessionEvent } from \"@deepseek-ai/dsh-session\";\n\nexport function balanceRewindPrefix(events: readonly SessionEvent[]): SessionEvent[] {\n  let keep = events.length;\n  // 从尾部向前待配对的 step/end 数（每个配对它之前的 step/start）。\n  let openStepEnds = 0;\n  for (let index = events.length - 1; index >= 0; index -= 1) {\n    const type = events[index]?.type;\n    if (type === \"turn/end\") break; // 轮次闭合：之前的 step 全部配对。\n    if (type === \"step/end\") {\n      openStepEnds += 1;\n      continue;\n    }\n    if (type === \"step/start\") {\n      if (openStepEnds > 0) {\n        openStepEnds -= 1; // 配对成功。\n      } else {\n        keep = index; // 孤儿 step/start：剔除它及其后。\n      }\n    }\n  }\n  return events.slice(0, keep);\n}\n","import type { Context } from \"@deepseek-ai/cordis\";\nimport { SessionBranch } from \"./branch.ts\";\n\nexport { SessionBranch } from \"./branch.ts\";\nexport type { SessionBranchProvider, BranchAnchorMode } from \"./provider.ts\";\nexport { buildTimeline } from \"./timeline.ts\";\nexport type { OwnEventsReader } from \"./timeline.ts\";\nexport { balanceRewindPrefix } from \"./balance.ts\";\nexport * from \"./types.ts\";\n\ndeclare module \"@deepseek-ai/cordis\" {\n  interface Context {\n    sessionBranch: SessionBranch;\n  }\n}\n\nexport function apply(_ctx: Context): void {\n  // 契约层不发布服务：ctx.sessionBranch 由实现 provider 的后端插件注册。\n  // 保留 apply 仅为 cordis 插件装配兼容，不注入任何服务。\n}\n"],"mappings":"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"}

package/dist/invariant.d.mts

@@ -0,0 +1,8 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/invariant.d.ts
+declare const name = "session-branch-invariant";
+declare const inject: string[];
+declare const apply: (ctx: Context) => Promise<() => void>;
+//#endregion
+export { apply, inject, name };
+//# sourceMappingURL=invariant.d.mts.map

package/dist/invariant.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.mts","names":[],"sources":["../src/invariant.ts"],"mappings":";;cAKa;cAEA;cAIA,QAAK,KAAS,YAAU"}

package/dist/invariant.mjs

@@ -0,0 +1,10 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "@morlay/session-branch";
+const name = "session-branch-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };
+
+//# sourceMappingURL=invariant.mjs.map

package/dist/invariant.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.mjs","names":[],"sources":["../src/invariant.ts"],"sourcesContent":["import type { Context } from \"@deepseek-ai/cordis\";\nimport type { InvariantInstaller } from \"@deepseek-ai/dsh-invariants\";\n\nconst PACKAGE_NAME = \"@morlay/session-branch\";\n\nexport const name = \"session-branch-invariant\";\n\nexport const inject = [\"invariants\"];\n\nconst install: InvariantInstaller = () => {};\n\nexport const apply = (ctx: Context): Promise<() => void> =>\n  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));\n"],"mappings":";AAGA,MAAM,eAAe;AAErB,MAAa,OAAO;AAEpB,MAAa,SAAS,CAAC,YAAY;AAEnC,MAAM,gBAAoC,CAAC;AAE3C,MAAa,SAAS,QACpB,QAAQ,QAAQ,IAAI,WAAW,SAAS,cAAc,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@morlay/session-branch",
+  "version": "0.0.2",
+  "description": "Provider abstraction + high-level service for rewind / retry / fork over DeepSeek Harness event-sourced sessions.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "fork",
+    "retry",
+    "rewind",
+    "session-branch"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/better-session.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "cordis.patch.yml",
+    "!**/__tests__"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./invariant": "./dist/invariant.mjs",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-rc.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown"
+  }
+}

package/src/balance.ts

@@ -0,0 +1,23 @@
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+
+export function balanceRewindPrefix(events: readonly SessionEvent[]): SessionEvent[] {
+  let keep = events.length;
+  // 从尾部向前待配对的 step/end 数（每个配对它之前的 step/start）。
+  let openStepEnds = 0;
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const type = events[index]?.type;
+    if (type === "turn/end") break; // 轮次闭合：之前的 step 全部配对。
+    if (type === "step/end") {
+      openStepEnds += 1;
+      continue;
+    }
+    if (type === "step/start") {
+      if (openStepEnds > 0) {
+        openStepEnds -= 1; // 配对成功。
+      } else {
+        keep = index; // 孤儿 step/start：剔除它及其后。
+      }
+    }
+  }
+  return events.slice(0, keep);
+}

package/src/branch.ts

@@ -0,0 +1,35 @@
+import { Service } from "@deepseek-ai/cordis";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionPersistenceSnapshot } from "@deepseek-ai/dsh-session-persistence";
+import type { BranchBoundary, BranchTimeline, ForkFromOptions } from "./types.ts";
+
+export abstract class SessionBranch extends Service {
+  constructor(ctx: import("@deepseek-ai/cordis").Context) {
+    super(ctx, "sessionBranch");
+  }
+
+  abstract readBranchPrefix(
+    id: SessionId,
+    atSeq?: number,
+    mode?: import("./provider.ts").BranchAnchorMode,
+    signal?: AbortSignal,
+  ): Promise<BranchBoundary>;
+
+  abstract forkFrom(
+    sourceId: SessionId,
+    options?: ForkFromOptions,
+    signal?: AbortSignal,
+  ): Promise<SessionId>;
+
+  abstract rewind(
+    id: SessionId,
+    toBoundary: number,
+    signal?: AbortSignal,
+  ): Promise<SessionPersistenceSnapshot>;
+
+  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
+
+  syncLiveCursor(_sessionId: SessionId): void {
+    // 默认无操作。
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { SessionBranch } from "./branch.ts";
+
+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 * from "./types.ts";
+
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    sessionBranch: SessionBranch;
+  }
+}
+
+export function apply(_ctx: Context): void {
+  // 契约层不发布服务：ctx.sessionBranch 由实现 provider 的后端插件注册。
+  // 保留 apply 仅为 cordis 插件装配兼容，不注入任何服务。
+}

package/src/invariant.ts

@@ -0,0 +1,13 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { InvariantInstaller } from "@deepseek-ai/dsh-invariants";
+
+const PACKAGE_NAME = "@morlay/session-branch";
+
+export const name = "session-branch-invariant";
+
+export const inject = ["invariants"];
+
+const install: InvariantInstaller = () => {};
+
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/src/provider.ts

@@ -0,0 +1,28 @@
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionPersistenceSnapshot } from "@deepseek-ai/dsh-session-persistence";
+import type { BranchBoundary, ForkFromOptions } from "./types.ts";
+
+export type BranchAnchorMode = "after" | "before";
+
+export interface SessionBranchProvider {
+  readonly name: string;
+
+  readBranchPrefix(
+    id: SessionId,
+    atSeq?: number,
+    mode?: BranchAnchorMode,
+    signal?: AbortSignal,
+  ): Promise<BranchBoundary>;
+
+  forkFrom(
+    sourceId: SessionId,
+    options?: ForkFromOptions,
+    signal?: AbortSignal,
+  ): Promise<SessionId>;
+
+  rewind(
+    id: SessionId,
+    toBoundary: number,
+    signal?: AbortSignal,
+  ): Promise<SessionPersistenceSnapshot>;
+}

package/src/timeline.ts

@@ -0,0 +1,122 @@
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionPersistenceSnapshot } from "@deepseek-ai/dsh-session-persistence";
+import {
+  SessionBranchError,
+  isSessionBranchVersionEvent,
+  type BranchTimeline,
+  type BranchVersionNode,
+  type SessionBranchVersionEventEnvelope,
+} from "./types.ts";
+
+export type BranchSnapshot = SessionPersistenceSnapshot & {
+  inheritedEventCount: number;
+};
+
+export type OwnEventsReader = (
+  id: SessionId,
+  fromSeq: number,
+  signal?: AbortSignal,
+) => Promise<readonly import("@deepseek-ai/dsh-session").SessionEvent[]>;
+
+export async function buildTimeline(
+  snapshots: readonly BranchSnapshot[],
+  readOwnEvents: OwnEventsReader,
+  sessionId: SessionId,
+  signal?: AbortSignal,
+): 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>();
+  while (cursor !== undefined) {
+    if (seen.has(cursor))
+      throw new SessionBranchError("lineage contains a cycle", "INVALID_BOUNDARY");
+    seen.add(cursor);
+    ancestors.push(cursor);
+    const snapshot = byId.get(cursor);
+    cursor = snapshot?.header.parentSession;
+  }
+  const rootId = ancestors.at(-1);
+  if (rootId === undefined) {
+    throw new SessionBranchError(`session "${sessionId}" is not persisted`, "SESSION_NOT_FOUND");
+  }
+
+  // 根向下的完整后代（BFS；按 createdAt 稳定排序）。
+  const ordered: SessionId[] = [];
+  const queue: SessionId[] = [rootId];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (id === undefined) continue;
+    ordered.push(id);
+    const children = snapshots
+      .filter((snapshot) => snapshot.header.parentSession === id)
+      .sort(
+        (left, right) =>
+          left.header.createdAt - right.header.createdAt ||
+          String(left.header.id).localeCompare(String(right.header.id)),
+      )
+      .map((snapshot) => snapshot.header.id);
+    queue.push(...children);
+  }
+
+  const nodes: BranchVersionNode[] = [];
+  const effectIds = new Set<string>();
+  for (const id of ordered) {
+    const snapshot = byId.get(id);
+    if (snapshot === undefined) continue;
+    const header = snapshot.header;
+    const node: BranchVersionNode = {
+      sessionId: header.id,
+      ...(header.parentSession === undefined ? {} : { parentSessionId: header.parentSession }),
+      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)) {
+          if (version !== undefined) {
+            throw new SessionBranchError(
+              `session ${header.id} carries multiple own version effects`,
+              "INVALID_BOUNDARY",
+            );
+          }
+          version = event;
+        }
+      }
+      if (version !== undefined) {
+        const data = version.data;
+        if (
+          data.inverse.kind !== "restore-version" ||
+          data.inverse.sessionId !== header.parentSession
+        ) {
+          throw new SessionBranchError(
+            `session ${header.id} version inverse does not match its parent`,
+            "INVALID_BOUNDARY",
+          );
+        }
+        if (effectIds.has(data.effect.id)) {
+          throw new SessionBranchError(
+            `version effect ${data.effect.id} is duplicated`,
+            "INVALID_BOUNDARY",
+          );
+        }
+        effectIds.add(data.effect.id);
+        node.effect = data.effect;
+        node.inverseSessionId = data.inverse.sessionId;
+      }
+    }
+    nodes.push(node);
+  }
+
+  const root = nodes.find((node) => node.parentSessionId === undefined);
+  if (root === undefined) {
+    throw new SessionBranchError(`session "${sessionId}" lineage has no root`, "SESSION_NOT_FOUND");
+  }
+  return { root, nodes };
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+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;
+
+export const SESSION_BRANCH_VERSION_SCHEMA = 1;
+
+export type CascadePolicy = "truncate" | "preserve";
+
+export type VersionOperation = "edit" | "reroll" | "retry" | "fork" | "rewind";
+
+export type EditableBlockKind = "user" | "assistant.reasoning" | "assistant.response";
+
+export interface SessionBranchEffect {
+  id: string;
+  operation: VersionOperation;
+  cascade: CascadePolicy;
+
+  targetTurn: number;
+
+  targetEventSeq: number;
+  targetBlockIndex?: number;
+  blockKind?: EditableBlockKind;
+
+  before?: string;
+
+  after?: string;
+}
+
+export interface SessionBranchInverse {
+  kind: "restore-version";
+  sessionId: SessionId;
+}
+
+export interface SessionBranchVersionEvent {
+  schemaVersion: typeof SESSION_BRANCH_VERSION_SCHEMA;
+  effect: SessionBranchEffect;
+  inverse: SessionBranchInverse;
+}
+
+declare module "@deepseek-ai/dsh-session" {
+  interface SessionEventMap {
+    "session-branch/version": SessionBranchVersionEvent;
+  }
+}
+
+export interface BranchBoundary {
+  seq: number;
+
+  events: readonly SessionEvent[];
+}
+
+export interface BranchForkMeta {
+  cwd?: string;
+  createdAt?: number;
+  agentPreset?: string;
+  origin?: "subagent";
+  delegationDepth?: number;
+}
+
+export interface ForkFromOptions {
+  atSeq?: number;
+
+  anchorMode?: import("./provider.ts").BranchAnchorMode;
+
+  seedSuffix?: readonly SessionEvent[];
+
+  childSessionId?: SessionId;
+
+  meta?: BranchForkMeta;
+}
+
+export interface BranchVersionNode {
+  sessionId: SessionId;
+  parentSessionId?: SessionId;
+
+  seedLength: number;
+  createdAt: number;
+
+  effect?: SessionBranchEffect;
+
+  inverseSessionId?: SessionId;
+}
+
+export interface BranchTimeline {
+  root: BranchVersionNode;
+  nodes: BranchVersionNode[];
+}
+
+export type SessionBranchErrorCode =
+  | "SESSION_NOT_FOUND"
+  | "INVALID_BOUNDARY"
+  | "OPEN_TURN"
+  | "FORK_UNAVAILABLE"
+  | "REWIND_CONFLICT";
+
+export class SessionBranchError extends Error {
+  readonly code: SessionBranchErrorCode;
+  constructor(message: string, code: SessionBranchErrorCode) {
+    super(message);
+    this.name = "SessionBranchError";
+    this.code = code;
+  }
+}
+
+export interface SessionBranchVersionEventEnvelope {
+  type: "session-branch/version";
+  seq: number;
+  time: number;
+  ignorable?: true;
+  data: SessionBranchVersionEvent;
+}
+
+export function isSessionBranchVersionEvent(
+  event: SessionEvent | { type: string; data: unknown },
+): event is SessionBranchVersionEventEnvelope {
+  return (
+    event.type === "session-branch/version" &&
+    (event.data as { schemaVersion?: unknown }).schemaVersion === SESSION_BRANCH_VERSION_SCHEMA
+  );
+}