@morlay/session-branch 0.1.1 → 0.1.3

package/README.md

@@ -1,50 +1,27 @@
 # @morlay/session-branch
 
-分支式会话编辑的**契约层**：定义数据层分支原语 `SessionBranchProvider`
-（rewind / forkFrom / readBranchPrefix）与高层服务 `SessionBranch`
-（`ctx.sessionBranch`）。
+分支式会话编辑的**契约层**：数据层分支原语 `SessionBranchProvider`（`readBranchPrefix` / `forkFrom` /
+`rewind`）与高层服务 `SessionBranch`（`ctx.sessionBranch`），接口形状见
+[`src/provider.ts`](./src/provider.ts)。
 
-跨包术语见根 [`.agents/CONTEXT.md`](../../../.agents/CONTEXT.md)，本包的决策见 [`.agents/adrs/`](./.agents/adrs)。
+## 用法
 
-## 装配
-
-本包没有自己的 bundle patch（不作为独立 bundle 安装）：装配入口是聚合层
-[`@morlay/better-session`](../../bundles/better-session/README.md)，`session-branch` 行由它的 patch 插入。
-
-## 与上游 `SessionHandle` 的关系
-
-上游持久化模型是 `SessionHandle`（append-only：`create` / `open` / `append` /
-`flush` / `stat` / `list`），没有显式回退原语；本包在其旁边定义**分支面**
-provider，负责显式回退与闭合边界派生：
-
-| 面     | 上游 `SessionHandle`                   | 本包 `SessionBranchProvider`                           |
-| ------ | -------------------------------------- | ------------------------------------------------------ |
-| 覆盖   | 持久读写（append-only）                | 显式回退 + 闭合边界派生（分支面）                      |
-| 原语   | `create` / `open` / `append` / `flush` | `readBranchPrefix` / `forkFrom` / `rewind`             |
-| 实现方 | JSONL / RDB 等                         | RDB 等（`@morlay/session-rdb` 同时实现两者，形成闭环） |
-
-## Provider 抽象
+装配入口是聚合层 [`@morlay/better-session`](../../bundles/better-session/README.md)——本包没有自己的 bundle
+patch，`session-branch` 行由它的 patch 插入；实现方是 [`@morlay/session-rdb`](../session-rdb/README.md)
+（同一个后端也实现上游 `SessionHandle`）。
 
 ```ts
-interface SessionBranchProvider {
-  readonly name: string;
-  readBranchPrefix(id, atSeq?, mode?, signal?): Promise<BranchBoundary>;
-  forkFrom(sourceId, options?, signal?): Promise<SessionId>;
-  rewind(id, toBoundary, signal?): Promise<SessionPersistenceSnapshot>;
-}
+const boundary = await ctx.sessionBranch.readBranchPrefix(sessionId, userEventSeq, "before");
+await ctx.sessionBranch.rewind(sessionId, boundary.seq);
 ```
 
-- `readBranchPrefix`：定位 `atSeq` 锚定的闭合 `turn/end` 边界并返回前缀；
-  `mode: "after"`（包含目标轮，fork 语义）/ `"before"`（排除目标轮，编辑 /
-  重掷 / 重试语义）。
-- `forkFrom`：纯 append——新会话（`parentSession` / `seedLength`），seed =
-  边界前缀 + `seedSuffix`，不触碰源会话。
-- `rewind`：唯一的显式回退原语，事务整体提交或回滚；**支持 live 会话**
-  （内存 log 截断 + 派生缓存复位 + handle cursor / 继承前缀对齐，详见
-  `@morlay/session-rdb` 的 [分支能力](../session-rdb/.agents/designs/20260917-分支能力.md)）。
-
-## 版本效果（历史形状）
+- `readBranchPrefix(id, atSeq?, mode?)`：定位 `atSeq` 锚定的闭合 `turn/end` 边界并返回前缀；`mode: "after"`
+  含目标轮（fork 语义）/ `"before"` 排除目标轮（编辑 / 重掷 / 重试语义）。
+- `forkFrom(sourceId, options?)`：纯 append 派生新会话（`parentSession` / `seedLength`，seed = 边界前缀 +
+  `seedSuffix`），不触碰源会话。
+- `rewind(id, toBoundary)`：唯一的显式回退原语，事务整体提交或回滚；支持 live 会话（内存 log 截断 +
+  派生缓存复位 + handle cursor / 继承前缀对齐，机制见 session-rdb 的
+  [设计 20260917-分支能力](../session-rdb/.agents/designs/20260917-分支能力.md)）。
 
-`session-branch/version` 事件的类型定义仍在本包（`types.ts`），用于识别旧会话里
-已落库的历史事件；**写侧与读侧都已删除**（不再产出新事件、没有读者），理由见
-[ADR-删除版本树投影并停止写版本效果](./.agents/adrs/20260920-删除版本树投影并停止写版本效果.md)。
+`session-branch/version` 事件的类型仍在 `src/types.ts`：它只用于识别旧会话里已落库的该事件，本仓库当前
+没有生产方与消费者（[ADR-删除版本树投影并停止写版本效果](./.agents/adrs/20260920-删除版本树投影并停止写版本效果.md)）。

package/dist/index.d.mts

@@ -2,11 +2,11 @@ import { Context, Service } from "@deepseek-ai/cordis";
 import { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 import { SessionPersistenceSnapshot } from "@deepseek-ai/dsh-session-persistence";
 //#region src/types.d.ts
-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 {
+export declare 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;
@@ -17,11 +17,11 @@ interface SessionBranchEffect {
   before?: string;
   after?: string;
 }
-interface SessionBranchInverse {
+export interface SessionBranchInverse {
   kind: "restore-version";
   sessionId: SessionId;
 }
-interface SessionBranchVersionEvent {
+export interface SessionBranchVersionEvent {
   schemaVersion: typeof SESSION_BRANCH_VERSION_SCHEMA;
   effect: SessionBranchEffect;
   inverse: SessionBranchInverse;
@@ -31,40 +31,29 @@ declare module "@deepseek-ai/dsh-session" {
     "session-branch/version": SessionBranchVersionEvent;
   }
 }
-interface BranchBoundary {
+export interface BranchBoundary {
   seq: number;
   events: readonly SessionEvent[];
 }
-interface BranchForkMeta {
+export interface BranchForkMeta {
   cwd?: string;
   createdAt?: number;
   agentPreset?: string;
   origin?: "subagent";
   delegationDepth?: number;
 }
-interface ForkFromOptions {
+export interface ForkFromOptions {
   atSeq?: number;
   anchorMode?: BranchAnchorMode;
   seedSuffix?: readonly SessionEvent[];
   childSessionId?: SessionId;
   meta?: BranchForkMeta;
 }
-type SessionBranchErrorCode = "SESSION_NOT_FOUND" | "INVALID_BOUNDARY" | "OPEN_TURN" | "FORK_UNAVAILABLE" | "REWIND_CONFLICT";
-declare class SessionBranchError extends Error {
+export type SessionBranchErrorCode = "SESSION_NOT_FOUND" | "INVALID_BOUNDARY" | "OPEN_TURN" | "FORK_UNAVAILABLE" | "REWIND_CONFLICT";
+export 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";
@@ -76,7 +65,7 @@ interface SessionBranchProvider {
 }
 //#endregion
 //#region src/branch.d.ts
-declare abstract class SessionBranch extends Service {
+export 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>;
@@ -87,8 +76,8 @@ declare abstract class SessionBranch extends Service {
 interface BalanceRewindPrefixOptions {
   keepOpenTail?: boolean;
 }
-declare function balanceRewindPrefix(events: readonly SessionEvent[], options?: BalanceRewindPrefixOptions): SessionEvent[];
-declare function rewindKeepLength(types: readonly string[], rawKeepLength: number): number;
+export declare function balanceRewindPrefix(events: readonly SessionEvent[], options?: BalanceRewindPrefixOptions): SessionEvent[];
+export declare function rewindKeepLength(types: readonly string[], rawKeepLength: number): number;
 //#endregion
 //#region src/index.d.ts
 declare module "@deepseek-ai/cordis" {
@@ -96,6 +85,6 @@ declare module "@deepseek-ai/cordis" {
     sessionBranch: SessionBranch;
   }
 }
-declare function apply(_ctx: Context): void;
+export declare function apply(_ctx: Context): void;
 //#endregion
-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 };
+export type { BranchAnchorMode, SessionBranchProvider };

package/dist/index.mjs

@@ -65,11 +65,8 @@ var SessionBranchError = class extends Error {
 		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, apply, balanceRewindPrefix, isSessionBranchVersionEvent, rewindKeepLength };
+export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, apply, balanceRewindPrefix, rewindKeepLength };

package/dist/invariant.d.mts

@@ -1,7 +1,6 @@
 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 };
+export declare const name = "session-branch-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//#endregion

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Session Branch",
-    "description": "Provider abstraction and service for rewind / retry / fork over event-sourced sessions."
+    "description": "Contract layer for branch-based session editing: the data-layer provider abstraction and the high-level service for rewind / retry / fork over event-sourced sessions."
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morlay/session-branch",
-  "version": "0.1.1",
-  "description": "Provider abstraction + high-level service for rewind / retry / fork over DeepSeek Harness event-sourced sessions.",
+  "version": "0.1.3",
+  "description": "Contract layer for branch-based session editing: the provider abstraction (rewind / forkFrom / readBranchPrefix) plus the high-level service over DeepSeek Harness event-sourced sessions.",
   "keywords": [
     "dsh",
     "dsh-plugin",

package/src/balance.ts

@@ -41,9 +41,8 @@ export function balanceRewindPrefix(
   return events.slice(0, keep);
 }
 
-// rewind 只按 seq 读尾部窗口（`types` 是窗口内升序的事件类型），在窗口上做同样的配对修剪：
-// 从尾部往回扫，遇到 turn/end 即停（它之前的内容与保留前缀的尾部无关）；尾部未闭合的
-// step/start 一并丢弃，避免它之后的追加（重放的新 step）撞上未闭合的旧 step。
+// rewind 只按 seq 读尾部窗口（`types` 是窗口内升序的事件类型），在窗口上做同样的配对修剪：从尾部往回扫，
+// 遇到 turn/end 即停；尾部未闭合的 step/start 一并丢弃，避免它之后的追加撞上未闭合的旧 step。
 // 调用方必须保证窗口覆盖到「最近一个 turn/end」或前缀开头，否则结果不完整。
 export function rewindKeepLength(types: readonly string[], rawKeepLength: number): number {
   let relativeKeep = types.length;

package/src/types.ts

@@ -1,8 +1,7 @@
 import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 
-// `session-branch/version` 的**历史形状**：写侧（就地编辑产出）与读侧（版本树投影）都已删除
-// （见 ADR 版本效果停止落库 / 版本树投影删除）。这里的定义只用于识别旧数据里已落库的
-// ignorable 事件，不再有新事件产生、也没有读者。
+// `session-branch/version` 的形状定义：只用于识别既有日志里已落库的该事件，本仓库不产出它、读侧也不参与投影
+// （见 ADR-删除版本树投影并停止写版本效果）。
 export const SESSION_BRANCH_VERSION_SCHEMA = 1;
 
 export type CascadePolicy = "truncate" | "preserve";
@@ -85,20 +84,3 @@ export class SessionBranchError extends Error {
     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
-  );
-}