@sema-agent/server 7.137.0 → 7.139.0

package/dist/plugins/local-session-store.d.ts

@@ -1,9 +1,12 @@
 import { FileSessionRepo, type AcquiredSession, type SessionHead, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
-import type { SessionRunRollupSource, SessionSummary } from "./store-contracts.js";
-import type { SessionRowPatch } from "../session-row.js";
+import type { SessionRunClaimSource, SessionRunRollupSource, SessionSummary } from "./store-contracts.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
+import { type ExecutionPlacementSeat, type LocalPlacementBackfillSeat } from "../execution-placement.js";
+import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import type { SessionWorkspace } from "../session-workspace.js";
 import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
@@ -53,8 +56,8 @@ export declare class LocalSessionStore implements SessionStore {
     /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     private readonly sidecarPath?;
     /** Title map (`session-titles.json`) — the local twin of the SQL `session_meta.title` column: one cell, two writers
-     *  (the user's {@link patchSessionMeta}, unconditional; the auto-titler's {@link setTitleIfNull}, fills an absent cell
-     *  only — writer order: `src/session-row.ts`). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
+     *  (the user's {@link writeSessionRowCells}; the auto-titler's {@link setTitleIfNull}, fills an absent cell
+     *  only — writer order: `src/session-row.ts`; both under the session write lock). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
      *  #10 clobber area); ultra-low-rate. Cross-instance sharing: see {@link SidecarMap}. */
     private readonly titles;
     /** Pin map (`session-pinned.json`, {@link readPinnedSidecar}) — the local twin of `session_meta.pinned`. Its own file for
@@ -64,6 +67,9 @@ export declare class LocalSessionStore implements SessionStore {
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
+    /** 会话行的位置与项目那一格(`session-workspaces.json`)—— SQL 孪生 `session_meta.workspace` 的 local 对位:`{ [sessionId]: 那一格的文本 }`,
+     *  文本与 SQL 列同一只编解码(`session-workspace-cell.ts`,一格读不出 ⇒ 读作没有记录并计一次)。缺键 = 没有记录。一事一档,理由同 titles。 */
+    private readonly workspaces;
     /**
      * 会话元数据(`session-incarnations.json`,一格的形与两种读法见 {@link SessionMetaCell}):**属主与化身的唯一真源**,SQL 孪生
      * `session_meta` 行上 `owner` / `incarnation` 两列在本店的对位。两样都**必须落盘**:
@@ -78,13 +84,27 @@ export declare class LocalSessionStore implements SessionStore {
     /** 认领行(`session_owner_claimed`)的出口 —— 一次性迁移 M10 的认领臂专用(窗口见 `plugins/one-time-migrations.ts` 登记表)。 */
     private readonly log;
     /**
-     * 按会话的写锁(表见 {@link SESSION_WRITE_LOCKS_BY_ROOT})—— 会话行两位的**每一笔**写(住客判 → 边档草稿 → 落盘 → 发布)与同一 id 上住客的**每一次**换人
+     * 按会话的写锁(表见 {@link SESSION_WRITE_LOCKS_BY_ROOT})—— 会话行两位的**每一笔**写(用户的行格写原语:判 → 边档草稿 → 落盘 → 发布;自动标题器的
+     * `setTitleIfNull`:见格在就不写)与同一 id 上住客的**每一次**换人
      * (删除:存档 + 三只行边档 + 元数据格;按 id 建会话:打开即建、登记;导入:铸新住客;换装:删后插回;staged 导入的提交)排在同一条链上:判过的住客
      * 在那一笔发布完之前不会被换掉,删除不会落在「判过、未发布」之间,同 id 的新住客也不会在删除做到一半时生出来、再被它的收尾抹掉。只有这一把;
      * SQL 孪生是一条带化身条件的 UPDATE、一条事务里的删除,没有这个窗,不需要它。按 id 的 acquire(打开 / 首建)也在这条链上:交出的会话挂的住客与打开
      * 同一节读到(见 `load`)。新 id 的建会话(不带 id 的 acquire、fork)不与任何人争同一 id,不上锁。
      */
     private readonly sessionWriteLocks;
+    /**
+     * 执行席(规则在 `src/execution-placement.ts`):读 = 那一格的 `execution` 位(fork 创建的格而存档不在 ⇒ `forking`);place / markMirror 在这只会话的写锁里判住客
+     * (化身 + 头读投影的属主 `owner ?? null`)再只改 `execution` 那一位 —— 住客换了(删后重建、M10 窗内认领)⇒ `gone`,不写。
+     * 认领(run 店的单活槽,{@link SessionRunClaimSource}):`markMirror` 在同一把写锁里读它、只拦「absent → mirror」这一笔(判序与 SQL 孪生同,见 {@link markMirrorExecution});`place` 是认领持有者自己的初始放置写,不读认领。
+     * local 的导入三写口不读认领 —— 它们的认领判在路由(第一阶段写前判 + 提交前复判),没有 SQL 孪生那样的写事务内读。
+     */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /**
+     * 一次性迁移 M32 的 local 腿用的席(随 M32 · 窗口见 `one-time-migrations.ts` 登记表):`read` 与 {@link executionPlacement} 的 `read` 是**同一读**({@link placementRead}),只差「这只会话的存档读不出」这一形
+     * (格缺而探针读不出;fork 创建的格而探针说不出在不在)—— 席的读照旧抛那只故障,本席答 {@link UnusableArchive}(开机回填不动存档、只补一格放置:读不出的会话由回填点名跳过,不拒启)。
+     * `place` 就是席的 `place`。
+     */
+    readonly executionPlacementBackfill: LocalPlacementBackfillSeat;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param runs     the run store whose per-session projection is the ONLY source of a row's `runCount` / `lastStatus` / `lastRunId` /
      *                  `lastTaskRunId` (LocalBackend passes its `FileRunStore`). Required — a run-less local session store does not exist.
@@ -93,9 +113,41 @@ export declare class LocalSessionStore implements SessionStore {
      *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives).
      *  @param opts.log the `session_owner_claimed` line's sink (LocalBackend passes a logger at the deployment's LOG_LEVEL;
      *                  absent ⇒ an info-level JSON-line logger — a claim is never silent). */
-    constructor(repo: HeadReadingSessionRepo, runs: SessionRunRollupSource, dataDir?: string, opts?: {
+    constructor(repo: HeadReadingSessionRepo, runs: SessionRunRollupSource & SessionRunClaimSource, dataDir?: string, opts?: {
         log?: Pick<Logger, "info">;
     });
+    /**
+     * 这一格此刻是不是 `forking`(fork 创建的格 {@link isForkCreatedCell} ∧ 存档不在)。存档在不在只问 repo 的唯一探针 {@link probeArchive} 的「不在」—— **只问有没有**:存档在而用不了(会话头读不出 / 截断)
+     * 是「在」,内容读不读得出归真正读内容的那一读(门之后、体之前读一次叶子,读不出 ⇒ `corrupt_session`)。所以带键的会话与不带键的会话在执行席上同形,坏档照样能被换装修好
+     * (换装是修坏档的唯一路径)。**唯一的例外是探针说不出在不在**(`storage` 词:读的时候抛了别的故障)⇒ 不替它答 forking 与否:{@link forkingOf} 把那只故障上抛(要对这只会话动手的读者 ——
+     * 写口的判、登记、缺档新建臂 —— 看到它就抛),{@link forkingRead} 交出 {@link UnusableArchive}(执行席的读上抛它,回填席点名它)。持这只会话的写锁时读数稳定(改存档在不在的写者都持这把锁);锁外是一次观察。
+     */
+    private forkingRead;
+    /** {@link forkingRead} 的上抛一形(与 {@link metaOf} 之于 {@link metaRead} 同一条规矩):探针说不出在不在 ⇒ 抛那只故障、原样。 */
+    private forkingOf;
+    /**
+     * 执行放置的读**本体**(一次:那一格 + 必要时的存档探针;两只席的读共用这一只)。行不在 ⇒ `undefined`;盘上有会话而格缺 ⇒ 补铸(与 {@link headOf} 同一只 {@link metaRead});
+     * 存档读不出({@link UnusableArchive}:格缺而探针读不出 ⇒ 不补铸;fork 创建的格而探针说不出在不在 ⇒ {@link forkingRead} 交出)⇒ 交出这只 {@link UnusableArchive}。
+     * 上抛还是点名,归两只席各自的读者({@link readExecutionPlacement} 上抛那只故障;{@link executionPlacementBackfill} 原样交出)。
+     */
+    private placementRead;
+    /** 执行席的读(core 席的合同:读故障抛,不吞成 absent):{@link placementRead} 的本体,存档读不出 ⇒ 上抛那只故障、原样(与 {@link metaOf} 同一条规矩:要动存档的读者看到读不出就抛)。 */
+    private readExecutionPlacement;
+    /** place(锁内):判官 {@link settledPlaceOutcome} 在写链的草稿上判(与登记的防 clobber 同一处),可写 ⇒ 只改 `execution` 位。 */
+    private placeExecution;
+    /**
+     * identical 臂补 mirror(锁内):先在这只会话的写锁里读 run 认领(行在才读;SQL 孪生:写事务内锁根行后读 `task_active`,根行不在 ⇒ 不读),再交判官 {@link settledMirrorOutcome};
+     * 判官的答案先于认领 —— 行不在 / 住客不同 ⇒ `gone`、writer ⇒ `writer`、已是 mirror ⇒ `mirrored`(幂等零写)都不被认领改写;只有「absent → mirror」这一笔写
+     * 遇上认领 ⇒ `active`(带那只认领的 task id,格不写)。可写且无认领 ⇒ 只改 `execution` 位为 mirror。
+     */
+    private markMirrorExecution;
+    /**
+     * 执行位两只写口的锁内一形(调用方持这只会话的写锁):在写链的草稿上读出这一格(`forking` 在锁内先判 —— 改存档在不在的写者都持这把锁)、交判官,
+     * 判官给 `execution` ⇒ 只改那一位。判官 / 解码抛的错**不在写链里抛**(写链一节抛了会把共享链留成拒态):收下、写链这一节不写、出链后原样上抛。
+     */
+    private settleExecutionHeld;
+    /** 已发布的那一格(同步读;调用方先 `meta.ensureLoaded()`)。 */
+    private metaCellOf;
     /**
      * 把 `sessionId` 那一格写成 `next(before)` 的结果并**落盘**(写链里在草稿上判、写、落盘后才发布给读者 —— 与 instruction-source 同一只 `commit`;
      * 判据建立在每一节之前的盘上状态上,所以防 clobber 的「已记下就不动」写在 `next` 里,不写在链外)。`next` 返回 `undefined` = 不改。
@@ -110,7 +162,15 @@ export declare class LocalSessionStore implements SessionStore {
      * 不可重入 —— 锁里的调用方只调 `…Held` 那一形(它们假定锁已在手),不再回到上锁的公开口。
      */
     private withSessionWriteLock;
-    /** 盘上有没有这只会话(repo 的唯一探针;`open` 读整只存档,所以只在边档里没有那一格时才走到这里)。 */
+    /**
+     * 盘上这只会话的存档此刻是什么状态(repo 的**唯一探针**;`open` 读整只存档,所以只在边档里没有那一格、或要判 `forking` 时才走到这里)。三种答案:
+     * 不在(`not_found`)· 在而读得出 · 读不出({@link UnusableArchive}:`corrupt_session` / `invalid_session` = 在而内容用不了;`storage` = 读的时候抛了别的故障,I/O 级,
+     * 说不出在不在 —— 词的读法见 {@link archiveFaultWord})。探针**不吞也不改**那只故障:{@link UnusableArchive.fault} 就是抛出来的那一只,每个读者各自决定上抛还是点名 ——
+     * 要对这份存档动手的({@link existsInRepo};{@link metaOf};{@link readExecutionPlacement})一律上抛它;一次性迁移 M32 的回填({@link executionPlacementBackfill})经
+     * {@link metaRead} / {@link forkingRead} 收下它、点名跳过,不上抛。只问有没有的 {@link forkingRead} 把 `corrupt_session` / `invalid_session` 读作「在」(存档找到了),`storage` 不替它答。
+     */
+    private probeArchive;
+    /** 盘上有没有一份**读得出**的这只会话的存档(补铸 / 登记 / 导入的落点判 / fork 目标这些要对存档动手的读者用):用不了的存档照旧上抛它的故障。 */
     private existsInRepo;
     /**
      * 一只会话的元数据 —— 属主与化身的**唯一读口**(按 id 读 {@link headOf} / 删除与换装的属主门都经它)。`undefined` = 无此会话。
@@ -118,6 +178,12 @@ export declare class LocalSessionStore implements SessionStore {
      * ⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)并落盘后再答 —— 之后的读都命中那一格,不再回 repo。
      */
     private metaOf;
+    /**
+     * {@link metaOf} 的本体(三态,不抛「用不了」):边档里有那一格 ⇒ 读它;没有 ⇒ 问**唯一探针** {@link probeArchive} 一次 —— 不在 ⇒ 无此会话;在而读得出 ⇒ 补铸({@link cellOfPresent});
+     * 读不出 ⇒ {@link UnusableArchive}(**不补铸**:不替一份读不出的存档铸化身)。要动存档的读者({@link metaOf})把它上抛;不动存档、只要「有没有」的读者
+     * ({@link executionPlacementBackfill})原样收下。
+     */
+    private metaRead;
     /**
      * 一只**已证明在盘上**的会话的那一格:有 ⇒ 读它;没有(7.104.0 之前写下、此后没被读过)⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)
      * 并落盘后再答。证明由调用方给:{@link metaOf} 探过 repo;acquire 的打开腿在这只会话的写锁里刚打开它({@link openForItselfHeld})。
@@ -146,21 +212,35 @@ export declare class LocalSessionStore implements SessionStore {
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
     /** The auto-titler's write (the local twin of the SQL setTitleIfNull): lands only on an absent cell — a title already
      *  there (the user's included) wins. Persists the whole (small) map via a SERIALIZED tmp+rename snapshot; a write
-     *  failure keeps the in-memory title (degrades to re-title after restart). */
+     *  failure keeps the in-memory title (degrades to re-title after restart). Runs under this session's write lock — the
+     *  user's conditional write ({@link writeSessionRowCells}) judges its row tag and writes under the same lock, so the two
+     *  writers of the title cell never interleave between a judgement and its write (the SQL twins get this from the row lock). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
     /**
-     * 会话行的可写位 —— 用户标题 / 置顶的**唯一**写口(SQL 孪生 `patchSessionMeta` 的 local 对位;写者次序见 `src/session-row.ts`)。
-     * 只写列表面上的会话(会话仓里有它),且只写调用方验过的那一位住客(`face.incarnation` 与会话元数据那一格的化身相等 —— SQL 孪生的
-     * `AND incarnation = ?`)。住客判、两只边档的草稿 → 落盘 → 发布、读回,**整段在这只会话的写锁里**({@link withSessionWriteLock}):删除 / 导入 /
-     * 换装同锁,判过的住客在这一笔发布完之前换不掉 —— 所以住客只判一次,读回的就是那一位的行;判不过(期间被删 / 被谁重新登记)⇒ `undefined`,什么都没写。
-     * `title` 串 ⇒ 无条件写进那一格(自动标题器的 {@link setTitleIfNull} 见格在就不写 ⇒ 用户那笔恒留下);`title: null` ⇒ 删那一格(清回自动标题);
+     * 会话行格写原语 —— 用户标题 / 置顶的**唯一**写口(SQL 孪生 `writeSessionRowCells` 的 local 对位;规则与判序:`src/session-row.ts` 头注「写原语」)。
+     * **整段在这只会话的写锁里**({@link withSessionWriteLock}):读出锁住的那一行(会话元数据那一格的属主 + 化身 + 执行位、列表面上有它、两只边档的格)→
+     * 同一只判官 `judgeSessionRowWrite`(行期望 → 写者身份 → 标签)→ 写 → 应答行(同锁内另读,经 `settleSessionRowWrite` 复核住客)。删除 / 导入 /
+     * 换装 / 登记 / 自动标题器同锁,判过的那一行在这一笔发布完之前换不掉。行期望带 `log` 时读这只会话存档的 mark(存档的追加不走这把锁 —— 那一维在 local 上是一次观察)。
+     * `title` 串 ⇒ 写进那一格(自动标题器的 {@link setTitleIfNull} 见格在就不写 ⇒ 用户那笔恒留下);`title: null` ⇒ 删那一格(清回自动标题);
      * `pinned:true` 写 `true`、`false` 删键。
-     * 落不了盘 ⇒ 抛、内存不动(用户的一笔写,不做「内存里先记着」的降级)。⚠️ 两键同一体时是两只文件、两次落盘:第二只落不了时第一只已在盘上
-     * (SQL 孪生是一条 UPDATE);抛出的错点名哪一只,重发同一体收敛。`lastActivity` 不动(改名不是活动 —— 列表的新近序不变)。
+     * local 的保证是「互斥 + 先判后写」,**不是多文件原子提交**:落不了盘 ⇒ 抛、那一只边档的内存不动;两键同一体时是两只文件、两次落盘,第二只落不了时第一只
+     * 已在盘上、标签已变(SQL 孪生是一条 UPDATE)—— 恢复 = 读当前行(或下一次带旧标签得 `changed` 的应答行)按它重发,收敛。`lastActivity` 不动(改名不是活动)。
+     * 重载按入口分:`replay` 的结局只有 `written` / `absent`。
+     */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
+    /**
+     * 写原语锁住的那一行(调用方持这只会话的写锁并已 {@link loadRowSidecars}):会话元数据那一格(属主 `owner ?? null` —— 与头读、列表行同读;化身经
+     * `incarnationFromCell` 的 `absent` 读法;执行位 `mirror`)+ 列表面上有它(会话仓里有;`forking` 中间态的存档不在 ⇒ 不在列表上)+ 两只边档的格。
+     * 没有那一格或不在列表面上 ⇒ `undefined`(没有行)。local 没有委派分区行。
      */
-    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
-    /** 会话元数据那一格此刻坐的是不是 `face` 那一位住客(同步读已发布的格;调用方先 `meta.ensureLoaded()`)。 */
-    private occupiedBy;
+    private lockedRowOf;
+    /** 两只边档上这只会话的可写格(已发布的值;缺键 = 缺省)。调用方先 {@link loadRowSidecars}。 */
+    private rowCellsOf;
+    /** 写原语的格写(锁内一形,调用方持这只会话的写锁):两只边档各经自己的写链(草稿 → 落盘 → 发布);落不了盘 ⇒ 抛、那一只的内存不动。 */
+    private writeRowCellsHeld;
+    /** 应答行(锁内另读):列表行同一只合成 + 读到它时那一格上的住客。不在列表面上 / 没有那一格 ⇒ `undefined`。 */
+    private listRowOf;
     /** ONE session's list row — {@link listSessions}' projection ({@link summaryOf}, the same synthesis) for one id;
      *  `undefined` = not a row of the list face (not in the session repo). */
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
@@ -175,6 +255,13 @@ export declare class LocalSessionStore implements SessionStore {
      * 开始之前共享的那张表只含落过盘的值,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /** 会话行的位置与项目那一格(local 孪生;读法与 SQL 两孪生同一只 `decodeSessionWorkspaceCell`)。缺键 ⇒ `undefined`。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座)。与 SQL 孪生「`UPDATE … WHERE session_id = ? AND incarnation = ?`」同义:**会话不在、或同 id
+     * 已换了住客 ⇒ 不写**,判与写排在这只会话的写锁里(删除 / 换人同锁 —— 判过的住客在这一笔落盘之前换不掉)。落不了盘 ⇒ 内存不动、抛。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
      *  read/parse error degrades to an empty map (createdAt ordering) rather than failing the list — the picker still
      *  works, just without restart-persisted recency. Memoized so concurrent listSessions share one read. */
@@ -235,11 +322,6 @@ export declare class LocalSessionStore implements SessionStore {
      * `REQUIRE_PRINCIPAL=true`,授权口也只在那时才把 principal 递过来认领(`security.ts` `createAuthorizer`)。
      */
     register(sessionId: string, owner: string | null): Promise<void>;
-    /** 2c P1d-β — re-stamp the session's owner WITHOUT rewriting entries (the staged-commit `identical` path: the log is
-     *  already present & equal, so only the owner needs re-stamping to the importing principal, §9). Persisted like every
-     *  owner write; the incarnation is untouched (same occupant). No cell (no such session) ⇒ no-op. Only caller:
-     *  {@link commitStagedImport}, inside the session's write lock. */
-    private restampOwner;
     touch(sessionId: string): Promise<void>;
     /** Durable history is retained by the repo; just drop the in-flight cache entry (mirrors TiDBSessionStore.release). */
     release(sessionId: string): Promise<void>;
@@ -281,6 +363,8 @@ export declare class LocalSessionStore implements SessionStore {
     private ownerCellOf;
     /** 一只会话的列表行 —— {@link listSessions} 与 {@link sessionSummaryOf} 的**同一只**合成(字段来源逐位见 listSessions 的头注)。调用方先 {@link loadRowSidecars}。 */
     private summaryOf;
+    /** 列表行的 `rowTag` 键(规则 `session-row.ts`):化身出自会话元数据那一格(与写原语锁住的那一行同读),属主与两格由调用方交 —— 就是这一行交出去的那两位(同一刻读);没有那一格 ⇒ 键缺席。 */
+    private rowTagKeyOf;
     /** [ref]:run 店里每个会话的 run 投影(按 sessionId 索引)。
      *  **一次读**:run 店的 `listSessions` 本来就按会话聚合全账(无会话过滤口),这里取全量再按会话仓的 id 查表 —— 比逐会话 N 次读便宜,
      *  也不在会话店里另存一份 run 账。读失败 ⇒ 抛(不吞成 `0 / ""`:那会把「读不到」说成「没跑过」)。 */
@@ -302,6 +386,19 @@ export declare class LocalSessionStore implements SessionStore {
      *  把它的答案原样交给引擎自己的 `repo.fork`(与 core 内存店 `TtlSessionStore.fork` 同一条调用链);两只 SQL 孪生同读它(`session-fork.ts`)。钉:
      *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。 */
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /**
+     * **fork 续写的店契约**(local 一形;规则与结果闭集在 `session-fork.ts`,SQL 孪生同义):
+     *  · **两把写锁**:按 id 字典序依次取源与目标的写锁(锁不可重入;同 id 只取一把)—— 同 id 的每个写者(删除 / 登记 / 导入 / 按 id 首建 / 别的 fork)都在目标那把锁里,
+     *    core `repo.fork` 的改名覆盖写只在锁内被调;
+     *  · **源先判**:源存档不在 ⇒ `null`(源被删之后的同键重试答「源不在」);属主读在拷贝之前(源锁持到拷贝落定)—— 唯一读法 `forkOwnerOf`;
+     *  · **唯一创建点 = 格先、存档后**:锁内「目标格不在 ∧ 目标存档不在」才写目标格(带 fork 键;新住客,执行位 absent),再交 core `repo.fork` 写存档。
+     *    崩在两步之间 = fork 创建的格而存档不在 = `forking`:普通取用一律 {@link SessionForkInProgressError};同键重试在两把锁内补拷存档、答 `replayed`。
+     *    拷贝抛错(不是崩溃)⇒ 撤掉刚写的目标格再上抛(撤不掉 ⇒ 留下的就是 `forking`,与崩在中间同形);
+     *  · **撞已在** ⇒ 按目标格的属主与 fork 键分类({@link classifyForkTarget})。
+     */
+    forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
+    /** {@link forkTo} 的锁内一形(调用方持源与目标两把写锁)。 */
+    private forkToHeld;
     /** 2c session-sync — EXPORT a session's full durable entry log (core `SessionRepo.exportEntries`; the
      *  in-memory/file repo holds the whole log so there is no floor to bypass). null if the source is unknown / the
      *  underlying repo lacks the optional seam. The owner is NOT exported — import re-stamps it. */
@@ -322,27 +419,67 @@ export declare class LocalSessionStore implements SessionStore {
         afterSeq?: number;
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
-    /** 2c session-sync — IMPORT a verbatim entry log into `sessionId` via core `SessionRepo.importEntries`
-     *  (which runs the `validateEntriesForImport` fail-closed gate before writing). `owner` is the authenticated
-     *  importing principal (re-stamped into the service-side owner map; core's local repo has no owner column, §9).
-     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`).
-     *  The owner is recorded in the session-meta cell (persisted), together with the incarnation. */
+    /**
+     * 2c session-sync — IMPORT a verbatim entry log into a **new** session `sessionId`(`owner` = 鉴权过的导入者)。按接口句(`importEntries` 只建新会话;改写既有会话走
+     * {@link replaceEntries} / 暂存提交),SQL 孪生同判(占行不成 ⇒ 拒):id 上已有行(或格缺而存档在)⇒ `conflict`,一个字节不写;新行的属主 = 导入者、铸一只化身、
+     * 执行位 mirror。属主在本店的属主格上判(会话元数据那一格是本店唯一的属主真源;本店建的存档在引擎仓里不带属主戳 —— `register` 只 `repo.create({ id })` ——
+     * 引擎仓的属主比较替这一格答不了)。整段在这只会话的写锁里,写序见 {@link importHeld}。
+     */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。调用方持这只会话的写锁。 */
-    private importEntriesAs;
-    /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
-     *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer
-     *  with NO compaction floor / cross-instance race (a process-local in-memory map / a single-process file repo), so
-     *  deleteSession-then-importEntries is effectively atomic for the local case (no concurrent reader can observe the
-     *  gap, unlike the durable cross-instance backends which do it in ONE SQL txn). Both halves are best-effort feature-
-     *  gated: a repo lacking either seam throws the same clear error importEntries does (no silent half-write). */
+    /**
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE,按接口句(`SessionStorage.replaceEntries`:先清这只会话既有的对话日志,再导入 `entries`)。
+     * 与 {@link importEntries} 同一个入口、同一只写序,只差落点(行不在,或行上的属主就是导入者)与内容那一半(先清内容存档再导入,见 {@link importHeld} ③)——
+     * 所以一只会话头读不出的存档也换得掉;存档是重建的那一只,建档时刻 = 换装时刻(SQL 孪生 replace 重插行、`created_at` 重记,同义)。行的四只边档原样。
+     */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** {@link replaceEntries} 的锁内一形(调用方持这只会话的写锁)。 */
-    private replaceEntriesHeld;
+    /**
+     * 换装三条写腿(公开 {@link importEntries} / {@link replaceEntries} 与暂存提交 {@link commitStagedImport})的**同一个入口**:调用方给的属主先过
+     * {@link importerOwnerOf}(主体名或 `null`;否则 `TypeError`,什么都没读、一个字节没写),再进这只会话的写锁 —— 锁里的写体只见判过的那一个值,
+     * 写进行的属主就是它。引擎导入口的属主判管不到这一格:换装交给引擎的是存档自己的戳(见 {@link importHeld} ③),不是调用方的属主。
+     */
+    private withImportLock;
+    /**
+     * 三个导入写口(`importEntries` / `replaceEntries` / 暂存提交的换装臂)的共用写序(调用方持这只会话的写锁,属主的形已在入口判过):
+     *  ① 只读、零写:引擎闸 `validateEntriesForImport`(坏包 ⇒ `invalid_session`)· 本处写者 ⇒ {@link SessionWriterPresentError} · `forking` ⇒
+     *    {@link SessionForkInProgressError} · 不是这个写口的门判过的行 ⇒ {@link importRowRefused}(判据 {@link importMayLand},按写口带来的 {@link ImportLanding};
+     *    这条路径上唯一一次判属主);
+     *  ② 行先:{@link landImportCell}(属主重戳为导入者、化身与 fork 键沿用或新铸、执行位 mirror);
+     *  ③ 内容,按写口的动词(唯一读法在下面这一只 switch;这里不读那一格、不判属主,只换**内容**):
+     *    · `create` / `judged`(导入):原地换锁里读到的那一份存档的日志(没有存档 ⇒ 导入新建一只),存档的元数据整只留着(其中的建档时刻是列表行的
+     *      firstActivityAt,与 SQL 孪生留在行上的 `created_at` 同义)。存档上的属主戳不是本店的事实(本店建的存档一律不带戳,存量存档可能带着此前导入者的戳),
+     *      只是引擎仓原地换的条件:按那一份存档自己的戳导入,并以它为 `expect`(戳 + 存档的令牌)—— 读与写之间它换了一代 ⇒ 引擎仓拒 `conflict`。
+     *      读存档、校验、存档判与写在引擎仓里是一步,抛在哪一处内容都一个字节没动 ⇒ 撤回 ②({@link withdrawImportCell}:行原样,SQL 孪生的事务回滚同义)再原样上抛;
+     *    · `replace`(接口句「先清既有对话日志,再导入」):先清掉内容存档(不带 `expect` —— 带了就得先读它的头,读不出的存档就清不掉),再导入一只新存档。
+     *      清不可撤:清过之后导入再抛(I/O 故障),内容就没了,行留 ② 落下的 mirror(只读方向,下次推送补齐)—— 已发版本的 replace 同形(删后导入)。
+     *      带 fork 键的行(fork 建出的目标)留下的是「mirror、键仍在、存档不在」:不读作 `forking`({@link isForkCreatedCell}:fork 创建点写下的格执行位恒缺,② 落下 mirror 之后它就不再是那一形),
+     *      下一次 replace / 暂存提交照常落定,同键 fork 重试仍 replayed(SQL 孪生一个事务里删重插、整段回滚,没有这个窗);
+     *  收尾:新近 = 此刻(推送即活动)。标题 / 置顶 / 指令来源 / 工作区四只行边档一个字节不碰。
+     * 崩在 ②③ 之间 = 格已是 mirror、内容旧或空 = 只读方向,下次推送补齐(SQL 孪生在一个事务里写行与内容,没有这个中间态)。
+     */
+    private importHeld;
+    /**
+     * ① 的属主 / 住客条件:这一行此刻是不是这个写口的门判过的行({@link ImportLanding};一次读、零写 —— 格缺时「行在不在」只问存档的唯一探针
+     * {@link existsInRepo},不补铸那一格)。属主比的是头读的读法 `owner ?? null`(从没被记下 = 无主;格缺而存档在 = 从没被记下),比较器是删除门的那一只
+     * {@link ownerEq}。M10 的认领只归登记({@link register}),导入不认领:遗留的「属主未记」格对带 principal 的 `replace` 读作别人的行,拒了之后那一格
+     * 原样仍是「未记」,窗内登记照样认领。
+     */
+    private importMayLand;
+    /**
+     * ② 推送落下的那一格 —— 三个导入写口与暂存提交「内容相同、日志不动」那一支都经这**一处**(调用方持写锁、① 已判过):属主重戳为导入者;
+     * 化身与 fork 键经 {@link carriedRowCells}(三只店同一句)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客,属主重戳与否不改这一判),刚建 ⇒ 新铸、不带键;
+     * 执行位 = mirror(导入落下的是「写者在别处」;SQL 孪生的提交点同一句写)。只写这一格:四只行边档与新近不在这里。
+     * 交回写之前的那一格(`undefined` = 原本没有),③ 撤回用。
+     */
+    private landImportCell;
+    /**
+     * 撤回 ② —— ③ 的原地换抛了(内容一个字节没动):那一格回到 ② 之前(原本没有 ⇒ 删掉),行原样。撤不掉 ⇒ 响亮:两只故障都点名
+     * (留下的格是 mirror —— 只读方向,与崩在 ②③ 之间同形,下次推送补齐)。
+     */
+    private withdrawImportCell;
     /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import. The LOCAL backend is single-writer with no
      *  cross-instance / cross-replica concurrency story (the durable twins carry that), so the staging handle simply
-     *  ACCUMULATES the streamed batches in memory then, on commit, runs the SAME validate-first → replaceEntries the
-     *  whole-bundle local import uses (effectively atomic locally — no concurrent reader can observe the gap). Keep it
+     *  ACCUMULATES the streamed batches in memory then, on commit, runs the SAME in-place log swap ({@link importHeld} ③: one
+     *  engine-repo import onto the archive as it stands — validate, judge and write in one step) the whole-bundle local import uses. Keep it
      *  simple per §1: the durable twins are where the SHADOW-id swap + bounded-memory + concurrency matter. */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
     /** 2c P1d-β (staged-row inspection) — the in-memory staged entries for a local staging id. No longer the import gate
@@ -354,7 +491,8 @@ export declare class LocalSessionStore implements SessionStore {
     /**
      * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
      * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 提交时重新分类(目的端此刻的日志 vs staged)
-     * → 拒未经同意的 fork / stale / 载荷分叉 → 换装(validate-first → 删 → 导入,化身按换装律沿用)或 identical 且内容相同时只重戳属主 → **在同一次持锁里**
+     * → 拒未经同意的 fork / stale / 载荷分叉 → 本处写者拒 → 换装(导入写序 ①②③,落点 `judged` = 上面这一判;化身与 fork 键按换装律沿用)或 identical 且内容相同时日志不动、
+     * 行照样落(② 那一格:重戳属主 + mirror)→ 两支同记新近(推送即活动)→ **在同一次持锁里**
      * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
      * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。
      */
@@ -367,10 +505,10 @@ export declare class LocalSessionStore implements SessionStore {
      *  tool-result rows are purged separately by the route's purgeSession coordinator. 整段在这只会话的写锁里(换人)。 */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     /**
-     * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装 {@link replaceEntriesHeld} 也走它)。
-     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、三只行边档(标题 / 置顶 / [ref] 的指令来源基线)、属主 + 化身那一格。
-     * 三只边档的那一键**都经各自的写链删**(`commit`:草稿上删、落盘、再发布 —— 与写它们的那一笔同一条链、同一把会话锁),落不了盘 ⇒ 抛:
-     * 留在盘上的值会挂到同 id 的下一位住客身上(E21 的删除权残留)。元数据格**最后**删:三只边档任一只落不了而抛时,那一格还在 ⇒ 会话对属主门仍
+     * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装不走它 —— 换装只换内容存档,行原样,见 {@link importHeld})。
+     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、四只行边档(标题 / 置顶 / 指令来源基线 / 工作区)、新近标记、属主 + 化身那一格。
+     * 四只边档的那一键**都经各自的写链删**(`commit`:草稿上删、落盘、再发布 —— 与写它们的那一笔同一条链、同一把会话锁),落不了盘 ⇒ 抛:
+     * 留在盘上的值会挂到同 id 的下一位住客身上(E21 的删除权残留)。元数据格**最后**删:四只边档任一只落不了而抛时,那一格还在 ⇒ 会话对属主门仍
      * 「在」,重发删除照样走得进来、收敛;反过来先删格,重发就成了 no-op,残留永远留下。
      * 🔴 hydrate FIRST (workflow audit 2026-07-13): after a restart the maps start empty — an un-hydrated delete would find nothing and
      * the sidecar would keep the value (an E21 right-to-delete residue that would RESURRECT onto a same-id re-import). ensureLoaded is