@morlay/session-branch 0.0.9

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,50 @@
+# @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 骨架。
+
+## 安装
+
+```sh
+nub install @morlay/session-branch   # peer: @deepseek-ai/cordis, dsh-session, dsh-session-persistence
+```

package/lib/index.d.mts

@@ -0,0 +1,255 @@
+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;
+/** 版本效果事件的数据结构版本（独立于 session 的 SESSION_FORMAT_VERSION）。 */
+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（全局唯一，跨版本树去重用）。 */
+  id: string;
+  operation: VersionOperation;
+  cascade: CascadePolicy;
+  /** 被操作的目标轮次（0 基）。 */
+  targetTurn: number;
+  /** 被操作的目标事件 seq（turn/start 或 user/message 等）。 */
+  targetEventSeq: number;
+  targetBlockIndex?: number;
+  blockKind?: EditableBlockKind;
+  /** 编辑前的文本（编辑类操作）。 */
+  before?: string;
+  /** 编辑后的文本（编辑类操作）。 */
+  after?: string;
+}
+/** 一个版本效果的「逆向」半边：恢复目标（父版本会话）。 */
+interface SessionBranchInverse {
+  kind: "restore-version";
+  sessionId: SessionId;
+}
+/**
+ * 每个分支版本在自己的非继承后缀中包含的效果对。父版本链自动导出组合逆；
+ * 恢复不是删除事件，而是沿逆链切换到仍然存在的版本。
+ *
+ * 事件信封必须携带 `ignorable: true`：`session-branch/version` 是 branch 层
+ * 的 lineage 事实，上游核心不认识它——`ignorable` 标记让不认识它的读者
+ * （core / 非 branch 后端）安全跳过而不拒绝整条 log。branch 层后端
+ * （如 `@morlay/session-rdb`）特判保留该类型，确保 lineage 落盘。
+ */
+interface SessionBranchVersionEvent {
+  schemaVersion: typeof SESSION_BRANCH_VERSION_SCHEMA;
+  effect: SessionBranchEffect;
+  inverse: SessionBranchInverse;
+}
+declare module "@deepseek-ai/dsh-session" {
+  interface SessionEventMap {
+    /** 分支版本 provenance，由 branch provider / editor 追加到新版本会话。 */
+    "session-branch/version": SessionBranchVersionEvent;
+  }
+}
+/** 一次闭合边界的定位结果：边界事件（含）及之前的前缀。 */
+interface BranchBoundary {
+  /** 边界事件 seq（含；一个 `turn/end`）。 */
+  seq: number;
+  /** 边界及之前的前缀事件（`events[seq]` 即边界事件）。 */
+  events: readonly SessionEvent[];
+}
+/** 派生会话的 header 元数据（header 是「创建事实」，派生时冻结）。 */
+interface BranchForkMeta {
+  cwd?: string;
+  createdAt?: number;
+  agentPreset?: string;
+  origin?: "subagent";
+  delegationDepth?: number;
+}
+/** `forkFrom` 的派生入参。 */
+interface ForkFromOptions {
+  /**
+   * 锚定 seq：取 ≥ atSeq 的第一个 `turn/end` 为派生边界；省略或越过日志末尾
+   * 回退到源会话最后一个闭合轮次；atSeq 所在轮未闭合则拒绝（OPEN_TURN）。
+   * 与 {@link BranchAnchorMode} 配合决定派生点取「目标轮之后」还是
+   * 「目标轮之前」。
+   */
+  atSeq?: number;
+  /**
+   * 锚定模式（默认 `"after"`）。分支式编辑/重掷/重试传 `"before"`——派生点
+   * 取目标轮之前的闭合边界（排除目标轮，目标轮由后续 agent 重新驱动）。
+   */
+  anchorMode?: BranchAnchorMode;
+  /**
+   * 在边界前缀之后追加的事件（版本效果事件、手工闭合回合等）。这些事件
+   * 成为派生会话自己的非继承后缀，`seedLength` 只计边界前缀。
+   */
+  seedSuffix?: readonly SessionEvent[];
+  /** 派生会话 id；省略由后端按自身 id 策略 mint。 */
+  childSessionId?: SessionId;
+  /** 派生 header 元数据。 */
+  meta?: BranchForkMeta;
+}
+/** 版本树节点投影（值级，供 Timeline / 标题栏消费）。 */
+interface BranchVersionNode {
+  sessionId: SessionId;
+  parentSessionId?: SessionId;
+  /** durable fork 边界：继承前缀长度。 */
+  seedLength: number;
+  createdAt: number;
+  /** 本会话自有的版本效果（非继承）；根节点无。 */
+  effect?: SessionBranchEffect;
+  /** 恢复目标（= parentSession 时与 inverse 一致）。 */
+  inverseSessionId?: SessionId;
+}
+/** 完整版本树：根 + 全部已知节点（含根）。 */
+interface BranchTimeline {
+  root: BranchVersionNode;
+  nodes: BranchVersionNode[];
+}
+/** 分支操作的拒绝码。 */
+type SessionBranchErrorCode = "SESSION_NOT_FOUND" | "INVALID_BOUNDARY" | "OPEN_TURN" | "FORK_UNAVAILABLE" | "REWIND_CONFLICT";
+/** 分支操作的 typed error。 */
+declare class SessionBranchError extends Error {
+  readonly code: SessionBranchErrorCode;
+  constructor(message: string, code: SessionBranchErrorCode);
+}
+/**
+ * 版本效果事件的结构化信封（守卫的返回类型；不依赖 `SessionEvent<T>` 泛型）。
+ */
+interface SessionBranchVersionEventEnvelope {
+  type: "session-branch/version";
+  seq: number;
+  time: number;
+  ignorable?: true;
+  data: SessionBranchVersionEvent;
+}
+/**
+ * 版本效果事件守卫：事件确实是 `session-branch/version` 且结构受支持。
+ *
+ * 结构化守卫（参数宽化 + 独立返回类型）：augmentation 对 `keyof SessionEventMap`
+ * 可见，但对 dsh-session 内 `SessionEventType` 别名的重求值在 workspace+peer
+ * 解析下不可靠（`SessionEvent<"session-branch/version">` 泛型约束失败），
+ * 因此不依赖该泛型。
+ * @param event - 待判定事件。
+ * @returns 是当前 schema 的版本效果事件。
+ */
+declare function isSessionBranchVersionEvent(event: SessionEvent | {
+  type: string;
+  data: unknown;
+}): event is SessionBranchVersionEventEnvelope;
+//#endregion
+//#region src/provider.d.ts
+/** 边界锚定模式。 */
+type BranchAnchorMode = "after" | "before";
+/**
+ * 分支数据层的后端契约。实现方必须保证：
+ *
+ * - `readBranchPrefix`：只读、不提交修复、不发布；返回的边界必是闭合
+ *   `turn/end`，且 `events` 与其 seq 连续（与持久化读取语义一致）。
+ * - `forkFrom`：纯 append——新会话（新 id / `parentSession` / `seedLength`），
+ *   不触碰源会话；seed = 边界前缀 + `seedSuffix`。
+ * - `rewind`：唯一改写事件 log 的服务面操作；**独占条件**（无 live owner、
+ *   无 in-flight append、无 prepared reservation）由实现方校验；事务整体
+ *   提交或回滚（Abort 不部分截断）；成功后 revision 变化，后续 append 从
+ *   新尾部继续。
+ */
+interface SessionBranchProvider {
+  /** 后端名（rewind 冲突诊断用）。 */
+  readonly name: string;
+  /**
+   * 定位 `atSeq` 锚定的闭合边界并返回其前缀（含边界事件）。
+   *
+   * - `mode: "after"`（默认）：边界 = **≥ atSeq** 的第一个 `turn/end`——
+   *   「从目标轮结束处派生」（proposal 的 forkFrom 语义，包含目标轮）。
+   * - `mode: "before"`：边界 = **< atSeq** 的最后一个 `turn/end`——
+   *   「从目标轮之前分支」（分支式编辑/重掷/重试语义，排除目标轮）。
+   *
+   * 省略 `atSeq` 或越过日志末尾 → 最后一个闭合轮次；`atSeq` 锚定所在轮
+   * 未闭合（after 模式）→ 拒绝（`OPEN_TURN`）；会话不存在 → 拒绝
+   * （`SESSION_NOT_FOUND`）。
+   * @param id - 持久化源会话。
+   * @param atSeq - 锚定 seq（inclusive）；省略取最后闭合轮次。
+   * @param mode - 锚定模式（见上）。
+   * @param signal - 读取消。
+   */
+  readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  /**
+   * 从持久化源派生新会话：seed = 边界前缀 + `options.seedSuffix`，meta 记录
+   * `parentSession` / `seedLength`。纯 append（派生不修改源），派生会话在
+   * 返回前已 durable（沿用 lazily-materialized 语义——空 seed 派生仍注册
+   * header，首个 append 才落盘）。
+   * @param sourceId - 持久化源会话。
+   * @param options - 边界锚定、seed 后缀、派生 id 与 meta。
+   * @param signal - 派生过程取消。
+   * @returns 派生的会话 id（`options.childSessionId` 或后端 mint）。
+   */
+  forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  /**
+   * 显式授权的截断式回退：截断事件 log 至 `toBoundary`（含该事件，保留其前
+   * 历史）。`toBoundary` 必须是非负整数、事件存在、且为闭合 `turn/end`
+   * 边界；否则拒绝（`INVALID_BOUNDARY` / `OPEN_TURN` / `SESSION_NOT_FOUND`）。
+   * 返回截断后的快照（header + revision）。
+   * @param id - 持久化会话。
+   * @param toBoundary - 截断点 seq（inclusive，`turn/end`）。
+   * @param signal - 中断时事务整体回滚（不部分截断）。
+   */
+  rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+}
+//#endregion
+//#region src/branch.d.ts
+/**
+ * 抽象服务：组合分支数据层（rewind / forkFrom）与版本树投影，暴露统一的
+ * 服务面。`timeline` 的共享实现见 {@link buildTimeline}（后端组合
+ * `sessionPersistence` 快照 + 自有后缀读取后调用）。
+ */
+declare abstract class SessionBranch extends Service {
+  constructor(ctx: import("@deepseek-ai/cordis").Context);
+  /** 定位 `atSeq` 锚定的闭合边界并返回其前缀（含边界事件）。 */
+  abstract readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  /** 从持久化源派生新会话（纯 append；返回派生会话 id）。 */
+  abstract forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  /** 显式授权的截断式回退；返回截断后的快照（header + revision）。 */
+  abstract rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+  /** 完整版本树投影（根 + 全部已知节点）。 */
+  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
+  /**
+   * 同步 live 会话的 coordinator 内存 cursor 到其 log 长度。就地编辑时，
+   * 编排层会把 ignorable 的版本效果直接 push 进 live log（不发布
+   * `session/event`，不进 write-behind 缓冲），导致 coordinator 的 cursor
+   * 落后于 log——后续 manualTurn 的 append（seq 从 log 续接）会在 flush 的
+   * seq 校验上错位。默认无操作；rdb 后端覆写（访问 coordinator 的 states）。
+   */
+  syncLiveCursor(_sessionId: SessionId): void;
+}
+//#endregion
+//#region src/timeline.d.ts
+/**
+ * 读取一个会话「自有后缀」事件的函数——live 会话传 `events.slice(seedLength)`，
+ * 持久化会话传 `sessionPersistence.readFrom(id, seedLength)`。
+ */
+type OwnEventsReader = (id: SessionId, fromSeq: number, signal?: AbortSignal) => Promise<readonly import("@deepseek-ai/dsh-session").SessionEvent[]>;
+/**
+ * 从会话快照集合构建 `sessionId` 的完整版本树。
+ * @param snapshots - 全部持久化会话的轻量快照（header + revision）。
+ * @param readOwnEvents - 按会话读取自有后缀事件。
+ * @param sessionId - 当前会话 id（树中标记为 current 由调用方负责）。
+ * @param signal - 读取取消。
+ */
+declare function buildTimeline(snapshots: readonly SessionPersistenceSnapshot[], readOwnEvents: OwnEventsReader, sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;
+//#endregion
+//#region src/index.d.ts
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    /** 分支式会话编辑服务（rewind / forkFrom / timeline）。 */
+    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, buildTimeline, isSessionBranchVersionEvent };
+//# sourceMappingURL=index.d.mts.map

package/lib/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/index.ts"],"mappings":";;;;KAiBK,yDAAyD;cACjD,mBAAmB;;cAGnB;;KAGD;;KAGA;;KAGA;;UAGK;;EAEf;EACA,WAAW;EACX,SAAS;;EAET;;EAEA;EACA;EACA,YAAY;;EAEZ;;EAEA;;;UAIe;EACf;EACA,WAAW;;;;;;;;;;;UAYI;EACf,sBAAsB;EACtB,QAAQ;EACR,SAAS;;;YAIC;;IAER,0BAA0B;;;;UAKb;;EAEf;;EAEA,iBAAiB;;;UAIF;EACf;EACA;EACA;EACA;EACA;;;UAIe;;;;;;;EAOf;;;;;EAKA,aAZe;;;;;EAiBf,sBAAsB;;EAEtB,iBAAiB;;EAEjB,OAAO;;;UAIQ;EACf,WAAW;EACX,kBAAkB;;EAElB;EACA;;EAEA,SAAS;;EAET,mBAAmB;;;UAIJ;EACf,MAAM;EACN,OAAO;;;KAIG;;cAQC,2BAA2B;WAC7B,MAAM;EACH,YAAA,iBAAiB,MAAM;;;;;UAUpB;EACf;EACA;EACA;EACA;EACA,MAAM;;;;;;;;;;;;iBAaQ,4BACd,OAAO;EAAiB;EAAc;IACrC,SAAS;;;;KCjKA;;;;;;;;;;;;;UAcK;;WAEN;;;;;;;;;;;;;;;;;EAkBT,iBACE,IAAI,WACJ,gBACA,OAAO,kBACP,SAAS,cACR,QAAQ;;;;;;;;;;;EAYX,SACE,UAAU,WACV,UAAU,iBACV,SAAS,cACR,QAAQ;;;;;;;;;;EAWX,OACE,IAAI,WACJ,oBACA,SAAS,cACR,QAAQ;;;;;;;;;uBCtES,sBAAsB;EAC9B,YAAA,mCAAmC;;WAKtC,iBACP,IAAI,WACJ,gBACA,OAFI,kBAGJ,SAAS,cACR,QAAQ;;WAGF,SACP,UAAU,WACV,UAAU,iBACV,SAAS,cACR,QAAQ;;WAGF,OACP,IAAI,WACJ,oBACA,SAAS,cACR,QAAQ;;WAGF,SAAS,WAAW,WAAW,SAAS,cAAc,QAAQ;;;;;;;;EASvE,eAAe,YAAY;;;;;;;;KC5BjB,mBACV,IAAI,WACJ,iBACA,SAAS,gBACN,oDAAoD;;;;;;;;iBASnC,cACpB,oBAAoB,8BACpB,eAAe,iBACf,WAAW,WACX,SAAS,cACR,QAAQ;;;;YCvBC;;IAER,eAAe;;;;iBAKH,MAAM,MAAM"}

package/lib/index.mjs

@@ -0,0 +1,131 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region src/branch.ts
+/**
+* 分支式会话编辑的高层服务（`ctx.sessionBranch`）：面向数据层
+* {@link SessionBranchProvider} 的抽象服务面。后端（如
+* `@morlay/session-rdb`）继承本类并提供 provider 实现，
+* 编排层（`@morlay/ui-conversation-message-actions`）只依赖本服务。
+*
+* @module @morlay/session-branch
+*/
+/**
+* 抽象服务：组合分支数据层（rewind / forkFrom）与版本树投影，暴露统一的
+* 服务面。`timeline` 的共享实现见 {@link buildTimeline}（后端组合
+* `sessionPersistence` 快照 + 自有后缀读取后调用）。
+*/
+var SessionBranch = class extends Service {
+	constructor(ctx) {
+		super(ctx, "sessionBranch");
+	}
+	/**
+	* 同步 live 会话的 coordinator 内存 cursor 到其 log 长度。就地编辑时，
+	* 编排层会把 ignorable 的版本效果直接 push 进 live log（不发布
+	* `session/event`，不进 write-behind 缓冲），导致 coordinator 的 cursor
+	* 落后于 log——后续 manualTurn 的 append（seq 从 log 续接）会在 flush 的
+	* seq 校验上错位。默认无操作；rdb 后端覆写（访问 coordinator 的 states）。
+	*/
+	syncLiveCursor(_sessionId) {}
+};
+//#endregion
+//#region src/types.ts
+const _branchKeyVisible = true;
+/** 版本效果事件的数据结构版本（独立于 session 的 SESSION_FORMAT_VERSION）。 */
+const SESSION_BRANCH_VERSION_SCHEMA = 1;
+/** 分支操作的 typed error。 */
+var SessionBranchError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "SessionBranchError";
+		this.code = code;
+	}
+};
+/**
+* 版本效果事件守卫：事件确实是 `session-branch/version` 且结构受支持。
+*
+* 结构化守卫（参数宽化 + 独立返回类型）：augmentation 对 `keyof SessionEventMap`
+* 可见，但对 dsh-session 内 `SessionEventType` 别名的重求值在 workspace+peer
+* 解析下不可靠（`SessionEvent<"session-branch/version">` 泛型约束失败），
+* 因此不依赖该泛型。
+* @param event - 待判定事件。
+* @returns 是当前 schema 的版本效果事件。
+*/
+function isSessionBranchVersionEvent(event) {
+	return event.type === "session-branch/version" && event.data.schemaVersion === 1;
+}
+//#endregion
+//#region src/timeline.ts
+/**
+* 从会话快照集合构建 `sessionId` 的完整版本树。
+* @param snapshots - 全部持久化会话的轻量快照（header + revision）。
+* @param readOwnEvents - 按会话读取自有后缀事件。
+* @param sessionId - 当前会话 id（树中标记为 current 由调用方负责）。
+* @param signal - 读取取消。
+*/
+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: header.seedLength ?? 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/index.ts
+/** 注册类型（无运行时副作用；服务由具体后端插件发布）。 */
+function apply(_ctx) {}
+//#endregion
+export { SESSION_BRANCH_VERSION_SCHEMA, SessionBranch, SessionBranchError, _branchKeyVisible, apply, buildTimeline, isSessionBranchVersionEvent };
+
+//# sourceMappingURL=index.mjs.map

package/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/branch.ts","../src/types.ts","../src/timeline.ts","../src/index.ts"],"sourcesContent":["/**\n * 分支式会话编辑的高层服务（`ctx.sessionBranch`）：面向数据层\n * {@link SessionBranchProvider} 的抽象服务面。后端（如\n * `@morlay/session-rdb`）继承本类并提供 provider 实现，\n * 编排层（`@morlay/ui-conversation-message-actions`）只依赖本服务。\n *\n * @module @morlay/session-branch\n */\n\nimport { 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\n/**\n * 抽象服务：组合分支数据层（rewind / forkFrom）与版本树投影，暴露统一的\n * 服务面。`timeline` 的共享实现见 {@link buildTimeline}（后端组合\n * `sessionPersistence` 快照 + 自有后缀读取后调用）。\n */\nexport abstract class SessionBranch extends Service {\n  constructor(ctx: import(\"@deepseek-ai/cordis\").Context) {\n    super(ctx, \"sessionBranch\");\n  }\n\n  /** 定位 `atSeq` 锚定的闭合边界并返回其前缀（含边界事件）。 */\n  abstract readBranchPrefix(\n    id: SessionId,\n    atSeq?: number,\n    mode?: import(\"./provider.ts\").BranchAnchorMode,\n    signal?: AbortSignal,\n  ): Promise<BranchBoundary>;\n\n  /** 从持久化源派生新会话（纯 append；返回派生会话 id）。 */\n  abstract forkFrom(\n    sourceId: SessionId,\n    options?: ForkFromOptions,\n    signal?: AbortSignal,\n  ): Promise<SessionId>;\n\n  /** 显式授权的截断式回退；返回截断后的快照（header + revision）。 */\n  abstract rewind(\n    id: SessionId,\n    toBoundary: number,\n    signal?: AbortSignal,\n  ): Promise<SessionPersistenceSnapshot>;\n\n  /** 完整版本树投影（根 + 全部已知节点）。 */\n  abstract timeline(sessionId: SessionId, signal?: AbortSignal): Promise<BranchTimeline>;\n\n  /**\n   * 同步 live 会话的 coordinator 内存 cursor 到其 log 长度。就地编辑时，\n   * 编排层会把 ignorable 的版本效果直接 push 进 live log（不发布\n   * `session/event`，不进 write-behind 缓冲），导致 coordinator 的 cursor\n   * 落后于 log——后续 manualTurn 的 append（seq 从 log 续接）会在 flush 的\n   * seq 校验上错位。默认无操作；rdb 后端覆写（访问 coordinator 的 states）。\n   */\n  syncLiveCursor(_sessionId: SessionId): void {\n    // 默认无操作。\n  }\n}\n","/**\n * 分支式会话编辑的共享类型：版本效果事件（`session-branch/version`）、\n * 闭合边界定位、派生元数据与版本树投影。\n *\n * 设计对齐 `@deepseek-ai/dsh-session` 的 merge-extensible `SessionEventMap`：\n * 版本事件是插件合并进事件映射的**持久**事件（占 seq、入 canonical log），\n * `parentSession` + `seedLength`（durable lineage）区分「继承」与「自有」。\n *\n * @module @morlay/session-branch/types\n */\n\nimport type { SessionEvent, SessionId } from \"@deepseek-ai/dsh-session\";\nimport type { SessionEventMap } from \"@deepseek-ai/dsh-session\";\n\n// 编译期诊断：module augmentation 后 `keyof SessionEventMap` 可见，但 dsh-session\n// 内已解析的 `SessionEventType` 别名（= keyof SessionEventMap）不会重求值——\n// 因此 `SessionEvent<\"session-branch/version\">` 泛型不可用，守卫/消费走结构化。\ntype _BranchKeyCheck = \"session-branch/version\" extends keyof SessionEventMap ? true : false;\nexport const _branchKeyVisible: _BranchKeyCheck = true as const;\n\n/** 版本效果事件的数据结构版本（独立于 session 的 SESSION_FORMAT_VERSION）。 */\nexport const SESSION_BRANCH_VERSION_SCHEMA = 1;\n\n/** 下游历史策略：目标轮次之后旧后续的去留。 */\nexport type CascadePolicy = \"truncate\" | \"preserve\";\n\n/** 一个版本效果代表的用户可见操作。 */\nexport type VersionOperation = \"edit\" | \"reroll\" | \"retry\" | \"fork\" | \"rewind\";\n\n/** 可编辑的模型可见块分类。 */\nexport type EditableBlockKind = \"user\" | \"assistant.reasoning\" | \"assistant.response\";\n\n/** 一个版本效果的「正向」半边：记录做了什么、改了什么。 */\nexport interface SessionBranchEffect {\n  /** 效果 id（全局唯一，跨版本树去重用）。 */\n  id: string;\n  operation: VersionOperation;\n  cascade: CascadePolicy;\n  /** 被操作的目标轮次（0 基）。 */\n  targetTurn: number;\n  /** 被操作的目标事件 seq（turn/start 或 user/message 等）。 */\n  targetEventSeq: number;\n  targetBlockIndex?: number;\n  blockKind?: EditableBlockKind;\n  /** 编辑前的文本（编辑类操作）。 */\n  before?: string;\n  /** 编辑后的文本（编辑类操作）。 */\n  after?: string;\n}\n\n/** 一个版本效果的「逆向」半边：恢复目标（父版本会话）。 */\nexport interface SessionBranchInverse {\n  kind: \"restore-version\";\n  sessionId: SessionId;\n}\n\n/**\n * 每个分支版本在自己的非继承后缀中包含的效果对。父版本链自动导出组合逆；\n * 恢复不是删除事件，而是沿逆链切换到仍然存在的版本。\n *\n * 事件信封必须携带 `ignorable: true`：`session-branch/version` 是 branch 层\n * 的 lineage 事实，上游核心不认识它——`ignorable` 标记让不认识它的读者\n * （core / 非 branch 后端）安全跳过而不拒绝整条 log。branch 层后端\n * （如 `@morlay/session-rdb`）特判保留该类型，确保 lineage 落盘。\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    /** 分支版本 provenance，由 branch provider / editor 追加到新版本会话。 */\n    \"session-branch/version\": SessionBranchVersionEvent;\n  }\n}\n\n/** 一次闭合边界的定位结果：边界事件（含）及之前的前缀。 */\nexport interface BranchBoundary {\n  /** 边界事件 seq（含；一个 `turn/end`）。 */\n  seq: number;\n  /** 边界及之前的前缀事件（`events[seq]` 即边界事件）。 */\n  events: readonly SessionEvent[];\n}\n\n/** 派生会话的 header 元数据（header 是「创建事实」，派生时冻结）。 */\nexport interface BranchForkMeta {\n  cwd?: string;\n  createdAt?: number;\n  agentPreset?: string;\n  origin?: \"subagent\";\n  delegationDepth?: number;\n}\n\n/** `forkFrom` 的派生入参。 */\nexport interface ForkFromOptions {\n  /**\n   * 锚定 seq：取 ≥ atSeq 的第一个 `turn/end` 为派生边界；省略或越过日志末尾\n   * 回退到源会话最后一个闭合轮次；atSeq 所在轮未闭合则拒绝（OPEN_TURN）。\n   * 与 {@link BranchAnchorMode} 配合决定派生点取「目标轮之后」还是\n   * 「目标轮之前」。\n   */\n  atSeq?: number;\n  /**\n   * 锚定模式（默认 `\"after\"`）。分支式编辑/重掷/重试传 `\"before\"`——派生点\n   * 取目标轮之前的闭合边界（排除目标轮，目标轮由后续 agent 重新驱动）。\n   */\n  anchorMode?: import(\"./provider.ts\").BranchAnchorMode;\n  /**\n   * 在边界前缀之后追加的事件（版本效果事件、手工闭合回合等）。这些事件\n   * 成为派生会话自己的非继承后缀，`seedLength` 只计边界前缀。\n   */\n  seedSuffix?: readonly SessionEvent[];\n  /** 派生会话 id；省略由后端按自身 id 策略 mint。 */\n  childSessionId?: SessionId;\n  /** 派生 header 元数据。 */\n  meta?: BranchForkMeta;\n}\n\n/** 版本树节点投影（值级，供 Timeline / 标题栏消费）。 */\nexport interface BranchVersionNode {\n  sessionId: SessionId;\n  parentSessionId?: SessionId;\n  /** durable fork 边界：继承前缀长度。 */\n  seedLength: number;\n  createdAt: number;\n  /** 本会话自有的版本效果（非继承）；根节点无。 */\n  effect?: SessionBranchEffect;\n  /** 恢复目标（= parentSession 时与 inverse 一致）。 */\n  inverseSessionId?: SessionId;\n}\n\n/** 完整版本树：根 + 全部已知节点（含根）。 */\nexport interface BranchTimeline {\n  root: BranchVersionNode;\n  nodes: BranchVersionNode[];\n}\n\n/** 分支操作的拒绝码。 */\nexport type SessionBranchErrorCode =\n  | \"SESSION_NOT_FOUND\"\n  | \"INVALID_BOUNDARY\"\n  | \"OPEN_TURN\"\n  | \"FORK_UNAVAILABLE\"\n  | \"REWIND_CONFLICT\";\n\n/** 分支操作的 typed error。 */\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\n/**\n * 版本效果事件的结构化信封（守卫的返回类型；不依赖 `SessionEvent<T>` 泛型）。\n */\nexport interface SessionBranchVersionEventEnvelope {\n  type: \"session-branch/version\";\n  seq: number;\n  time: number;\n  ignorable?: true;\n  data: SessionBranchVersionEvent;\n}\n\n/**\n * 版本效果事件守卫：事件确实是 `session-branch/version` 且结构受支持。\n *\n * 结构化守卫（参数宽化 + 独立返回类型）：augmentation 对 `keyof SessionEventMap`\n * 可见，但对 dsh-session 内 `SessionEventType` 别名的重求值在 workspace+peer\n * 解析下不可靠（`SessionEvent<\"session-branch/version\">` 泛型约束失败），\n * 因此不依赖该泛型。\n * @param event - 待判定事件。\n * @returns 是当前 schema 的版本效果事件。\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","/**\n * 版本树投影的共享组合逻辑：从持久化快照列表 + 每会话「自有后缀」读版本\n * 效果事件，导出完整 lineage 树。具体后端（`SessionBranch` 实现）提供数据\n * 读取，本模块做纯投影——根与后代的确定、自有版本效果的扫描、节点归一。\n *\n * 规则（对齐 `dsh-message-edit` 的数据模型）：\n * - `parentSession` 构成版本树；`seedLength` 区分继承与自有后缀。\n * - 每个会话至多一个**自有** `session-branch/version` 事件（seq ≥ seedLength）。\n * - 根节点（无 `parentSession`）不带版本效果。\n * - 版本效果 id 全局唯一；逆链（`inverse.sessionId`）必须指向树内父节点。\n *\n * @module @morlay/session-branch/timeline\n */\n\nimport 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\n/**\n * 读取一个会话「自有后缀」事件的函数——live 会话传 `events.slice(seedLength)`，\n * 持久化会话传 `sessionPersistence.readFrom(id, seedLength)`。\n */\nexport type OwnEventsReader = (\n  id: SessionId,\n  fromSeq: number,\n  signal?: AbortSignal,\n) => Promise<readonly import(\"@deepseek-ai/dsh-session\").SessionEvent[]>;\n\n/**\n * 从会话快照集合构建 `sessionId` 的完整版本树。\n * @param snapshots - 全部持久化会话的轻量快照（header + revision）。\n * @param readOwnEvents - 按会话读取自有后缀事件。\n * @param sessionId - 当前会话 id（树中标记为 current 由调用方负责）。\n * @param signal - 读取取消。\n */\nexport async function buildTimeline(\n  snapshots: readonly SessionPersistenceSnapshot[],\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: header.seedLength ?? 0,\n      createdAt: header.createdAt,\n    };\n    // 根节点不可能带版本效果；其余节点读自有后缀。\n    if (header.parentSession !== undefined) {\n      const events = await readOwnEvents(header.id, node.seedLength, signal);\n      // 结构化守卫 + find（避免 filter 的 `S extends T` 约束——版本事件类型不在\n      // SessionEvent 判别联合的固化 `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","/**\n * @morlay/session-branch —— 分支式会话编辑的 provider 抽象 + 高层服务。\n *\n * 本包是 better-session monorepo 的**契约层**：定义数据层分支原语\n * {@link SessionBranchProvider}（rewind / forkFrom）、高层服务\n * {@link SessionBranch}（`ctx.sessionBranch`）与共享的版本树投影\n * {@link buildTimeline}。具体持久化后端实现 provider 后，编排层\n * （`@morlay/ui-conversation-message-actions`）即可在不修改上游 `@deepseek-ai/*` 代码的\n * 前提下提供完整的 rewind / retry / fork 功能。\n *\n * @module @morlay/session-branch\n */\n\nimport 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 * from \"./types.ts\";\n\ndeclare module \"@deepseek-ai/cordis\" {\n  interface Context {\n    /** 分支式会话编辑服务（rewind / forkFrom / timeline）。 */\n    sessionBranch: SessionBranch;\n  }\n}\n\n/** 注册类型（无运行时副作用；服务由具体后端插件发布）。 */\nexport function apply(_ctx: Context): void {\n  // 契约层不发布服务——`ctx.sessionBranch` 由实现 provider 的后端插件\n  // （如 @morlay/session-rdb）在启动时注册为 `SessionBranch`\n  // 子类实例。此处保留 apply 是为了 cordis 插件装配兼容（类型声明 + 可空\n  // 生命周期），不注入任何服务。\n}\n"],"mappings":"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"}

package/lib/invariant.d.mts

@@ -0,0 +1,15 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/invariant.d.ts
+/** Cordis companion plugin name. */
+declare const name = "session-branch-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+declare const apply: (ctx: Context) => Promise<() => void>;
+//#endregion
+export { apply, inject, name };
+//# sourceMappingURL=invariant.d.mts.map

package/lib/invariant.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.mts","names":[],"sources":["../src/invariant.ts"],"mappings":";;;cAWa;;cAEA;;;;;;cAcA,QAAS,KAAK,YAAU"}

package/lib/invariant.mjs

@@ -0,0 +1,22 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "@morlay/session-branch";
+/** Cordis companion plugin name. */
+const name = "session-branch-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: branch semantics (rewind / forkFrom / boundary
+* anchoring) are validated by contract tests; this package exposes no
+* continuously observable in-process relation.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };
+
+//# sourceMappingURL=invariant.mjs.map

package/lib/invariant.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.mjs","names":[],"sources":["../src/invariant.ts"],"sourcesContent":["/**\n * Package-owned invariant companion for `@morlay/session-branch`.\n * @module @morlay/session-branch/invariant\n */\n\nimport type { Context } from \"@deepseek-ai/cordis\";\nimport type { InvariantInstaller } from \"@deepseek-ai/dsh-invariants\";\n\nconst PACKAGE_NAME = \"@morlay/session-branch\";\n\n/** Cordis companion plugin name. */\nexport const name = \"session-branch-invariant\";\n/** Service required before the companion can reserve package ownership. */\nexport const inject = [\"invariants\"];\n\n/**\n * No runtime invariant: branch semantics (rewind / forkFrom / boundary\n * anchoring) are validated by contract tests; this package exposes no\n * continuously observable in-process relation.\n */\nconst install: InvariantInstaller = () => {};\n\n/**\n * Register this package's invariant companion.\n * @param ctx - Cordis context carrying the invariant service.\n * @returns the installed registration's disposer after setup succeeds.\n */\nexport const apply = (ctx: Context): Promise<() => void> =>\n  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));\n"],"mappings":";AAQA,MAAM,eAAe;;AAGrB,MAAa,OAAO;;AAEpB,MAAa,SAAS,CAAC,YAAY;;;;;;AAOnC,MAAM,gBAAoC,CAAC;;;;;;AAO3C,MAAa,SAAS,QACpB,QAAQ,QAAQ,IAAI,WAAW,SAAS,cAAc,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@morlay/session-branch",
+  "version": "0.0.9",
+  "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": [
+    "lib"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.mts",
+      "default": "./lib/invariant.mjs"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.8"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {}
+}