@morlay/session-branch 0.0.10-alpha.3 → 0.0.10-alpha.5

package/README.md

@@ -1,8 +1,8 @@
 # @morlay/session-branch
 
 分支式会话编辑的**契约层**：定义数据层分支原语 `SessionBranchProvider`
-（rewind / forkFrom / readBranchPrefix）、高层服务 `SessionBranch`
-（`ctx.sessionBranch`）与共享的版本树投影 `buildTimeline`。
+（rewind / forkFrom / readBranchPrefix）与高层服务 `SessionBranch`
+（`ctx.sessionBranch`）。
 
 跨包术语见根 [`.agents/CONTEXT.md`](../../../.agents/CONTEXT.md)，本包的决策见 [`.agents/adrs/`](./.agents/adrs)。
 
@@ -38,11 +38,8 @@ interface SessionBranchProvider {
   （内存 log 截断 + 派生缓存复位 + handle cursor / 继承前缀对齐，详见
   `@morlay/session-rdb` 的 [分支能力](../session-rdb/.agents/designs/20260917-分支能力.md)）。
 
-## 版本树
+## 版本效果（历史形状）
 
-`buildTimeline(snapshots, readOwnEvents, sessionId)` 从会话快照（header
-lineage）+ 每会话自有后缀（`seq >= seedLength` 的 `session-branch/version`
-事件）投影完整版本树。
-
-版本效果事件携带 `ignorable: true` 并**原样落库**，因此 cold 会话也能恢复效果详情
-（见 [ADR-版本效果以ignorable事件原样落库](./.agents/adrs/20260917-版本效果以ignorable事件原样落库.md)）。
+`session-branch/version` 事件的类型定义仍在本包（`types.ts`），用于识别旧会话里
+已落库的历史事件；**写侧与读侧都已删除**（不再产出新事件、没有读者），理由见
+[ADR-删除版本树投影并停止写版本效果](./.agents/adrs/20260920-删除版本树投影并停止写版本效果.md)。

package/dist/index.d.mts

@@ -1,9 +1,7 @@
 import { Context, Service } from "@deepseek-ai/cordis";
-import { SessionEvent, SessionEventMap, SessionId } from "@deepseek-ai/dsh-session";
+import { SessionEvent, 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";
@@ -51,18 +49,6 @@ interface ForkFromOptions {
   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;
@@ -95,16 +81,8 @@ declare abstract class SessionBranch extends Service {
   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>;
 }
 //#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
 interface BalanceRewindPrefixOptions {
   keepOpenTail?: boolean;
@@ -120,4 +98,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, rewindKeepLength };
+export { type BranchAnchorMode, BranchBoundary, BranchForkMeta, CascadePolicy, EditableBlockKind, ForkFromOptions, SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchEffect, SessionBranchError, SessionBranchErrorCode, SessionBranchInverse, type SessionBranchProvider, SessionBranchVersionEvent, SessionBranchVersionEventEnvelope, VersionOperation, apply, balanceRewindPrefix, isSessionBranchVersionEvent, rewindKeepLength };

package/dist/index.mjs

@@ -6,82 +6,6 @@ var SessionBranch = class extends Service {
 	}
 };
 //#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, options = {}) {
 	let keep = events.length;
@@ -131,7 +55,21 @@ function rewindKeepLength(types, rawKeepLength) {
 	return Math.max(0, rawKeepLength - types.length + relativeKeep);
 }
 //#endregion
+//#region src/types.ts
+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/index.ts
 function apply(_ctx) {}
 //#endregion
-export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, _branchKeyVisible, apply, balanceRewindPrefix, buildTimeline, isSessionBranchVersionEvent, rewindKeepLength };
+export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, apply, balanceRewindPrefix, isSessionBranchVersionEvent, rewindKeepLength };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/session-branch",
-  "version": "0.0.10-alpha.3",
+  "version": "0.0.10-alpha.5",
   "description": "Provider abstraction + high-level service for rewind / retry / fork over DeepSeek Harness event-sourced sessions.",
   "keywords": [
     "dsh",

package/src/branch.ts

@@ -1,7 +1,7 @@
 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";
+import type { BranchBoundary, ForkFromOptions } from "./types.ts";
 
 export abstract class SessionBranch extends Service {
   constructor(ctx: import("@deepseek-ai/cordis").Context) {
@@ -26,6 +26,4 @@ export abstract class SessionBranch extends Service {
     toBoundary: number,
     signal?: AbortSignal,
   ): Promise<SessionPersistenceSnapshot>;
-
-  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
 }

package/src/index.ts

@@ -3,8 +3,6 @@ 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, rewindKeepLength } from "./balance.ts";
 export * from "./types.ts";
 

package/src/types.ts

@@ -1,9 +1,8 @@
 import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
-import type { SessionEventMap } from "@deepseek-ai/dsh-session";
-
-type _BranchKeyCheck = "session-branch/version" extends keyof SessionEventMap ? true : false;
-export const _branchKeyVisible: _BranchKeyCheck = true as const;
 
+// `session-branch/version` 的**历史形状**：写侧（就地编辑产出）与读侧（版本树投影）都已删除
+// （见 ADR 版本效果停止落库 / 版本树投影删除）。这里的定义只用于识别旧数据里已落库的
+// ignorable 事件，不再有新事件产生、也没有读者。
 export const SESSION_BRANCH_VERSION_SCHEMA = 1;
 
 export type CascadePolicy = "truncate" | "preserve";
@@ -71,23 +70,6 @@ export interface ForkFromOptions {
   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"

package/src/timeline.ts

@@ -1,120 +0,0 @@
-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");
-  }
-
-  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);
-
-      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 };
-}