@sema-agent/server 7.137.0 → 7.139.0

package/dist/execution-placement.d.ts

@@ -0,0 +1,259 @@
+/**
+ * **执行放置** —— 根会话行上「这一位住客」的一格(叶模块:型 + 纯函数 + 测试走廊的内存参照实现;运行期只依赖 core 的住客判官)。
+ *
+ * ## 规则(全仓唯一处写)
+ *  · **一格四态**:`absent`(这一位住客还没有放置)| `writer(L[, D])`(本引擎声明在车道 L 上写;device 车道带设备 D,D 缺 = 迁移回填的
+ *    「有 run、设备未知」)| `mirror`(写者在别处,本处只读)| `forking`(只 local:fork 的目标格已写、存档未落 —— 崩溃中间态,SQL 单事务不可达)。
+ *    载体:SQL `session_meta` 的 `execution_*` 七列(列定义与语句的唯一属主 = `plugins/execution-placement-sql.ts`);local = 会话元数据边档那一格的
+ *    `execution` 位(`plugins/local-session-store.ts`)。处处 `execution` 限定,与同行 `placement_*`(委派分区)不同义;执行格只在 `placement_kind IS NULL` 的行上 ——
+ *    委派分区行读作「不在」。
+ *  · **读只有一只**:会话店的执行席 {@link ExecutionPlacementSeat.read}(一次行读:住客 + 格;行不在 / 委派分区行 ⇒ `undefined`;读故障抛,不吞成 `absent`)。
+ *  · **写只按住客谓词** `(root, incarnation, owner) ∧ placement_kind IS NULL`:住客换了(删后重建,哪怕同一属主;local M10 窗内的认领)= 这一格不在 ⇒ 落空;
+ *    0 行一律按住客复读分类({@link settledPlaceOutcome} / {@link settledMirrorOutcome} / {@link settledDeviceBindOutcome}),**永不对现住客重试**。
+ *  · **没有的转换**:writer ↔ mirror、writer(L) → writer(L')(device 车道的换绑 writer(device, D) → writer(device, D') 除外,它有自己的语句与门)。
+ *  · **放置存在 ⇒ 住客存在**:放置是行的列 / 格,删会话即删放置;建行恒 absent(SQL 建行 INSERT 列名显式;local 新格整格新铸),导入新建的行同锁落 mirror。
+ *
+ * ## 测试走廊的会话行(不是第二只生产店)
+ * {@link InMemoryExecutionPlacementSeat} 是**语义参照实现**(与 `InMemoryDeviceStore` 同一身份):持「会话行」(root → 住客 + 格),给只用 `Map` 会话店的
+ * 测试走廊与 `InMemoryDeviceStore` 共用。**生产装配零引用** —— `src/` 非测试路径里只许 `device-store.ts` 与本模块提到它。
+ */
+import { type SessionHead } from "@sema-agent/core";
+import type { DeviceOwner } from "./device-store.js";
+import type { ExecutionLane } from "./execution-lane-caps.js";
+import type { SessionFace } from "./session-incarnation.js";
+/** writer(device, D) 的 D:设备、绑定属主(= 设备属主)、换绑序号、放下时刻(ISO)。 */
+export interface ExecutionDeviceCell {
+    readonly id: string;
+    readonly owner: DeviceOwner;
+    readonly rev: number;
+    readonly placedAt: string;
+}
+/** `lane = "device"` ∧ `device` 缺 = writer(device, ∅)(只来自迁移回填:有 run 而设备未知)。 */
+export type ExecutionWriterCell = {
+    readonly role: "writer";
+    readonly lane: ExecutionLane;
+    readonly device?: ExecutionDeviceCell;
+};
+export type ExecutionPlacementCell = {
+    readonly role: "absent";
+} | ExecutionWriterCell | {
+    readonly role: "mirror";
+} | {
+    readonly role: "forking";
+};
+/** 一次行读的答案:这一位住客 + 它的格(同一行、同一次读)。 */
+export interface ExecutionPlacementReading {
+    readonly occupant: SessionFace;
+    readonly cell: ExecutionPlacementCell;
+}
+/** place 的结果(0 行按住客复读分类;`gone` = 行不在或住客不是判过的那一位)。 */
+export type PlaceOutcome = {
+    readonly outcome: "placed";
+} | {
+    readonly outcome: "same";
+} | {
+    readonly outcome: "tree_bound";
+    readonly boundLane: ExecutionLane;
+} | {
+    readonly outcome: "mirror";
+} | {
+    readonly outcome: "gone";
+};
+/** identical 臂补 mirror 的结果(`active` = 写事务内(SQL)/ 写锁内(local)读到认领,带那只认领的 task id;判官的答案先于它,只拦「absent → mirror」这一笔写)。 */
+export type MarkMirrorOutcome = {
+    readonly outcome: "mirrored";
+} | {
+    readonly outcome: "writer";
+} | {
+    readonly outcome: "gone";
+} | {
+    readonly outcome: "active";
+    readonly activeTaskId: string;
+};
+/**
+ * 「谁带执行席」的唯一一句(要求会话店带席的装配拒句引它,不另抄):三店都带(SQL 两孪生 + local,即 `StoreBackend` 交出的会话店),两只包装原样转发;
+ * 只用 `Map` 会话店的测试走廊 / 内存嵌入给参照实现。
+ */
+export declare const EXECUTION_PLACEMENT_SEAT_CARRIERS = "every built-in session store carries one (the MySQL-protocol and PostgreSQL stores and the local store, i.e. the session store a StoreBackend hands out; the caching and fork-routing wrappers forward it), and an in-memory test or embedding passes InMemoryExecutionPlacementSeat";
+/** 会话店的执行席(三店 + 两只包装原样转发)。 */
+export interface ExecutionPlacementSeat {
+    /** 一次行读:行不在 / 委派分区行 ⇒ `undefined`;读故障抛(不吞成 absent)。 */
+    read(root: string): Promise<ExecutionPlacementReading | undefined>;
+    /** absent → writer(L)(非 device 车道;device 车道的首绑走设备店,同一只 SQL 语句模块)。传 device 车道 ⇒ 响亮抛(装配缝)。 */
+    place(root: string, occupant: SessionFace, cell: ExecutionWriterCell): Promise<PlaceOutcome>;
+    /** identical 臂补 mirror:WHERE 住客谓词 ∧ 不是 writer;写事务内先锁根行读认领(SQL),local 在这只会话的写锁里读同一个认领。 */
+    markMirror(root: string, occupant: SessionFace): Promise<MarkMirrorOutcome>;
+}
+/**
+ * 读不出的存档的故障词(闭集;一次性迁移 M32 的 local 腿点名用 —— 随 M32 · 窗口见 `plugins/one-time-migrations.ts` 登记表,窗关后随迁移码删):
+ *  · `corrupt_session` —— 存档在,会话头读不出 / 截断;`invalid_session` —— 读得出而日志结构走不通(两个都是 core 的 `SessionError` 词,原样);
+ *  · `storage` —— 读的时候抛了**别的**故障(I/O 级:权限 / 磁盘 I/O / 超大 —— core 的 `readJsonlRecords` 只吞 ENOENT,其余 errno 原样抛,不是 `SessionError`),
+ *    说不出在不在也说不出内容;{@link UnusableArchive.errno} 带那只故障的 `code`。
+ */
+export type UnusableArchiveWord = "corrupt_session" | "invalid_session" | "storage";
+/**
+ * local 的会话存档**读不出**(会话头读不出 / 日志结构走不通 / 读的时候抛了别的故障):盘上有这只会话的存档,只是读不出它 —— 与「不在」是两件事。
+ * (本型与 {@link isUnusableArchive} 随 M32 · 窗口见 `plugins/one-time-migrations.ts` 登记表。)
+ * local 店对存档的**唯一探针**答三态(不在 · 在而读得出 · 本型),要对存档动手的读者看到本型就把 {@link UnusableArchive.fault}(抛出来的那只故障,**原样**)上抛,
+ * 只问「有没有」的读者不上抛(见 `plugins/local-session-store.ts` 的 `probeArchive`)。
+ */
+export interface UnusableArchive {
+    readonly state: "unusable";
+    readonly word: UnusableArchiveWord;
+    /** `word === "storage"` 且那只故障带字符串 `code` 时:该 `code`(`EACCES` / `EIO` / `ERR_STRING_TOO_LONG` ……);其余缺席。盘上路径与故障句不进这一格。 */
+    readonly errno?: string;
+    /** 探针抛出来的那只故障,原样(上抛的读者抛的就是它)。 */
+    readonly fault: unknown;
+}
+export declare function isUnusableArchive(x: object | undefined): x is UnusableArchive;
+/**
+ * 一次性迁移 M32 **local 腿**的席(随 M32 · 窗口见 `plugins/one-time-migrations.ts` 登记表;只 local 有:SQL 的行就是会话,没有「会话元数据格缺 ∧ 存档读不出」这一形)。`read` 与 {@link ExecutionPlacementSeat.read} 是
+ * **同一读**(同一只实现的本体),只差一点:这只会话的存档读不出(格缺而探针读不出,或 fork 创建的格而探针读不出)⇒ **答 {@link UnusableArchive} 而不抛** —— 开机回填不动存档、
+ * 只补一格放置,读不出的会话由它点名跳过(该会话的请求照旧答存档的故障);席的 `read` 对同一形照旧抛。`place` 就是席的 `place`。
+ */
+export interface LocalPlacementBackfillSeat extends Pick<ExecutionPlacementSeat, "place"> {
+    read(root: string): Promise<ExecutionPlacementReading | UnusableArchive | undefined>;
+}
+/** wire 投影(新读面 + 受理回声共用)。 */
+export type ExecutionPlacementView = {
+    readonly role: "absent";
+} | {
+    readonly role: "writer";
+    readonly lane: ExecutionLane;
+    readonly device?: {
+        readonly deviceId: string;
+        readonly rev: number;
+    };
+} | {
+    readonly role: "mirror";
+} | {
+    readonly role: "forking";
+};
+/** 格 → wire 投影(唯一一只;设备只投 id 与 rev,属主与时刻不上 wire)。 */
+export declare function executionPlacementView(cell: ExecutionPlacementCell): ExecutionPlacementView;
+/**
+ * 住客谓词的 JS 读法(SQL `incarnation = ? AND owner <=> ?` 的对位)= core 的行期望判官 `sessionRowMatches`(会话行格写原语锁内判的也是它,
+ * `session-row.ts` 的 `judgeSessionRowWrite`):属主与化身两样都没变才是判过的那一位 —— 同一化身的属主会变(local M10 认领、identical 重戳、
+ * SQL 导入提交点改属主)。两侧收「属主 + 化身」那一读:活住客(`SessionFace`)与店的头(`SessionHead`,门判过的那一读);调用方一侧恒是执行席的读数
+ * (住客经 `sessionFaceFromRow` 解码,令牌非空),所以「两侧都没有令牌」这一形在这里不可达。写口的判官与执行上下文解析器步 ① 的 `judged` 复核都经它。
+ */
+export declare function sameOccupant(a: Pick<SessionHead, "owner" | "incarnation">, b: Pick<SessionHead, "owner" | "incarnation">): boolean;
+/**
+ * 写口撞上本处写者 —— 三个导入写口(staged 提交点 / 整段 `importEntries` / `replaceEntries`)在写事务内(local:写锁内、写格之前)复读到 `writer`
+ * ⇒ 回滚、目的端零字节、抛它。具名类型:会话同步路由按类型把它答 409 `conflict.session_writer`;不是 core `SessionError`(那张闭集的 `conflict` 在导入面另有固定答复)。
+ */
+export declare class SessionWriterPresentError extends Error {
+    readonly sessionId: string;
+    readonly lane: ExecutionLane;
+    readonly code = "conflict.session_writer";
+    constructor(sessionId: string, lane: ExecutionLane);
+}
+/**
+ * local 的 `forking` 中间态(fork 创建的格 —— 带 fork 键、执行位没人写过 —— 而存档不在)上的普通取用 —— 引擎 acquire 的缺档新建臂、登记、三个导入写口、执行席的写一律抛它;
+ * 只有同键的 `forkTo` 重试在两把写锁内补拷存档。具名类型:路由层按类型答 409 `conflict.fork_in_progress`。
+ */
+export declare class SessionForkInProgressError extends Error {
+    readonly sessionId: string;
+    readonly code = "conflict.fork_in_progress";
+    constructor(sessionId: string);
+}
+/**
+ * 写事务内的认领读命中(读写序律,`plugins/execution-placement-sql.ts` 的 `lockRootAndReadClaim`):改根住客 / 放置的写者在自己的事务里先锁根
+ * `session_meta` 行、再锁定读 `task_active(root)`,读到认领 ⇒ 回滚、一个字节不写、抛它。只 SQL 后端(local 不立此律:没有 device 工厂)。
+ * 具名类型、**不带 wire 码**:各门按自己的既有码答(导入 409 `session_active`、删除 409 `conflict.session_active_run`),体带 `activeTaskId`。
+ */
+export declare class SessionActiveRunError extends Error {
+    readonly sessionId: string;
+    readonly activeTaskId: string;
+    constructor(sessionId: string, activeTaskId: string);
+}
+/** 0 行分类的「这一格此刻可写」答案(只给锁内读写的实现用:local 与内存参照实现写它;SQL 在 0 行之后读到它 = 不变量破,响亮抛)。 */
+export declare const WRITABLE: "writable";
+/**
+ * place 的唯一判官(三店 + 内存参照实现同调):对一次按根的读数判「判过的住客 + 想要的格」此刻是什么结果。
+ * 行不在 / 住客不同 ⇒ `gone`;writer 同车道 ⇒ `same`;writer 异车道 ⇒ `tree_bound`;mirror ⇒ `mirror`;absent ⇒ {@link WRITABLE};forking ⇒ 抛 {@link SessionForkInProgressError}。
+ * 想要的格只认非 device 车道(device 首绑的判官是 {@link settledDeviceBindOutcome})。
+ */
+export declare function settledPlaceOutcome(root: string, reading: ExecutionPlacementReading | undefined, occupant: SessionFace, wanted: ExecutionWriterCell): PlaceOutcome | typeof WRITABLE;
+/** markMirror 的唯一判官(认领那一半在本判官之后,SQL 与 local 各在自己的写事务 / 写锁内判):行不在 / 住客不同 ⇒ `gone`;writer ⇒ `writer`;mirror ⇒ `mirrored`(幂等,零写);absent ⇒ {@link WRITABLE};forking ⇒ 抛。 */
+export declare function settledMirrorOutcome(root: string, reading: ExecutionPlacementReading | undefined, occupant: SessionFace): MarkMirrorOutcome | typeof WRITABLE;
+/** device 车道首绑(absent → writer(device, D) 或 writer(device, ∅) → writer(device, D))的结果(设备店的事务 / 内存参照实现同调)。 */
+export type DeviceBindOutcome = {
+    readonly outcome: "bound";
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly outcome: "same";
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly outcome: "device_conflict";
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly outcome: "tree_bound";
+    readonly boundLane: ExecutionLane;
+} | {
+    readonly outcome: "mirror";
+} | {
+    readonly outcome: "gone";
+};
+/**
+ * device 首绑的唯一判官:行不在 / 住客不同 ⇒ `gone`;absent 或 writer(device, ∅) ⇒ {@link WRITABLE};writer(device, D):D = 想要的设备 ⇒ `same`、否则 `device_conflict`;
+ * writer 异车道 ⇒ `tree_bound`;mirror ⇒ `mirror`;forking ⇒ 抛。
+ */
+export declare function settledDeviceBindOutcome(root: string, reading: ExecutionPlacementReading | undefined, occupant: SessionFace, deviceId: string): Exclude<DeviceBindOutcome, {
+    outcome: "bound";
+}> | typeof WRITABLE;
+/**
+ * device 换绑 writer(device, D) → writer(device, D') 的结果(按住客 ∧ 两属主列 ∧ rev 定址;0 行按住客复读分 `rev_conflict` / `gone`)。
+ * `rebound` 带被换下的那台(`from`,审计行 `session_rebound` 的 detail 要它);`idempotent` = 目标就是格上那台且前态 rev 对得上 ⇒ 零写、rev 不加、不写审计。
+ */
+export type DeviceRebindOutcome = {
+    readonly outcome: "rebound";
+    readonly device: ExecutionDeviceCell;
+    readonly from: string;
+} | {
+    readonly outcome: "idempotent";
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly outcome: "rev_conflict";
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly outcome: "gone";
+};
+/**
+ * device 换绑的唯一判官(设备店的事务 / 内存参照实现同调,在锁住的那一读上判):行不在 / 住客不同 / 不是 writer(device, D) / 绑定属主不是判过的那一位 ⇒ `gone`;
+ * rev 不等 ⇒ `rev_conflict`;rev 对得上而目标就是格上那台 ⇒ `idempotent`(必须先于写判 —— `execution_rev + 1` 恒变列会把一次无操作也推进一格);否则 {@link WRITABLE}。
+ */
+export declare function settledDeviceRebindOutcome(reading: ExecutionPlacementReading | undefined, occupant: SessionFace, owner: DeviceOwner, expectedRev: number, targetDeviceId: string): Exclude<DeviceRebindOutcome, {
+    outcome: "rebound";
+}> | typeof WRITABLE;
+/**
+ * 「这一格把这棵树放在哪台设备上」的**唯一读法**(准入链、device 工厂、换绑门与上面的换绑判官同调):writer(device, D) ⇒ D;其余一律 `undefined` ——
+ * absent(还没放)、mirror(写者在别处)、forking(local 中间态)、writer(device, ∅)(迁移回填的「有 run、设备未知」)、writer(别的车道)。
+ * 读者把 `undefined` 答成各自的「没有设备绑定」(`device.not_bound` / 设备 404);穷举 switch,新角色 = 编译红。
+ */
+export declare function boundDeviceOf(cell: ExecutionPlacementCell): ExecutionDeviceCell | undefined;
+/** seat.place 只认非 device 车道(device 首绑走设备店);传 device ⇒ 响亮抛 —— 这是装配缝,不是一个答案。 */
+export declare function assertPlaceableLane(root: string, cell: ExecutionWriterCell): void;
+/**
+ * **测试走廊的会话行**(语义参照实现,与 `InMemoryDeviceStore` 同一身份 —— 生产装配零引用,见头注):root → 住客 + 格。
+ * 只用 `Map` 会话店的测试走廊经 {@link seatRow} / {@link dropRow} 模拟会话行的生灭(= SQL 店的建行 / 删行),`InMemoryDeviceStore` 在它上面做设备首绑 / 换绑。
+ * 语义与 SQL 语句模块逐格同:同一组判官({@link settledPlaceOutcome} 等),写只按住客谓词。
+ */
+export declare class InMemoryExecutionPlacementSeat implements ExecutionPlacementSeat {
+    private readonly rows;
+    /** 建行(会话店建行的对位):行不在 ⇒ 建一只 absent 行;在 ⇒ 不动(与 SQL `ON CONFLICT DO NOTHING` 同一条 first-write 律)。 */
+    seatRow(root: string, occupant: SessionFace): void;
+    /** 删行(删会话的对位):放置随行消失。 */
+    dropRow(root: string): void;
+    read(root: string): Promise<ExecutionPlacementReading | undefined>;
+    place(root: string, occupant: SessionFace, cell: ExecutionWriterCell): Promise<PlaceOutcome>;
+    markMirror(root: string, occupant: SessionFace): Promise<MarkMirrorOutcome>;
+    /** device 首绑(SQL `placeDeviceStatement` / `bindDeviceStatement` 的对位):absent 或 writer(device, ∅) ⇒ writer(device, D)、rev 0。 */
+    bindDevice(root: string, occupant: SessionFace, device: {
+        readonly id: string;
+        readonly owner: DeviceOwner;
+    }, placedAt: string): DeviceBindOutcome;
+    /** device 换绑(SQL `rebindDeviceStatement` 的对位):按住客 ∧ 两属主列 ∧ rev 定址,rev + 1;目标就是格上那台 ⇒ `idempotent` 零写。 */
+    rebindDevice(root: string, occupant: SessionFace, owner: DeviceOwner, expectedRev: number, targetDeviceId: string, placedAt: string): DeviceRebindOutcome;
+}
+//# sourceMappingURL=execution-placement.d.ts.map

package/dist/execution-placement.js

@@ -0,0 +1,199 @@
+import { sessionRowMatches } from "@sema-agent/core";
+export const EXECUTION_PLACEMENT_SEAT_CARRIERS = "every built-in session store carries one (the MySQL-protocol and PostgreSQL stores and the local store, i.e. the session store a StoreBackend hands out; the caching and fork-routing wrappers forward it), and an in-memory test or embedding passes InMemoryExecutionPlacementSeat";
+export function isUnusableArchive(x) {
+    return x !== undefined && x.state === "unusable";
+}
+export function executionPlacementView(cell) {
+    switch (cell.role) {
+        case "absent":
+            return { role: "absent" };
+        case "writer":
+            return cell.device === undefined ? { role: "writer", lane: cell.lane } : { role: "writer", lane: cell.lane, device: { deviceId: cell.device.id, rev: cell.device.rev } };
+        case "mirror":
+            return { role: "mirror" };
+        case "forking":
+            return { role: "forking" };
+        default: {
+            const unknownRole = cell;
+            throw new Error(`executionPlacementView: no projection for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+export function sameOccupant(a, b) {
+    return sessionRowMatches({ row: { owner: a.owner ?? null, incarnation: a.incarnation } }, b, noLogMark);
+}
+function noLogMark() {
+    throw new Error("sameOccupant: an occupant check carries no log mark, yet the judge asked for one");
+}
+export class SessionWriterPresentError extends Error {
+    sessionId;
+    lane;
+    code = "conflict.session_writer";
+    constructor(sessionId, lane) {
+        super(`session ${sessionId} is written here on the ${lane} lane — an import cannot turn it into a mirror; nothing was written`);
+        this.sessionId = sessionId;
+        this.lane = lane;
+        this.name = "SessionWriterPresentError";
+    }
+}
+export class SessionForkInProgressError extends Error {
+    sessionId;
+    code = "conflict.fork_in_progress";
+    constructor(sessionId) {
+        super(`session ${sessionId} is the target of a fork that has not finished copying — retry that fork with the same key, or delete the session`);
+        this.sessionId = sessionId;
+        this.name = "SessionForkInProgressError";
+    }
+}
+export class SessionActiveRunError extends Error {
+    sessionId;
+    activeTaskId;
+    constructor(sessionId, activeTaskId) {
+        super(`session ${sessionId} has an active run (${activeTaskId}) — this write was refused inside its transaction; nothing was written`);
+        this.sessionId = sessionId;
+        this.activeTaskId = activeTaskId;
+        this.name = "SessionActiveRunError";
+    }
+}
+export const WRITABLE = "writable";
+export function settledPlaceOutcome(root, reading, occupant, wanted) {
+    if (reading === undefined || !sameOccupant(reading.occupant, occupant))
+        return { outcome: "gone" };
+    const cell = reading.cell;
+    switch (cell.role) {
+        case "absent":
+            return WRITABLE;
+        case "writer":
+            return cell.lane === wanted.lane ? { outcome: "same" } : { outcome: "tree_bound", boundLane: cell.lane };
+        case "mirror":
+            return { outcome: "mirror" };
+        case "forking":
+            throw new SessionForkInProgressError(root);
+        default: {
+            const unknownRole = cell;
+            throw new Error(`settledPlaceOutcome: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+export function settledMirrorOutcome(root, reading, occupant) {
+    if (reading === undefined || !sameOccupant(reading.occupant, occupant))
+        return { outcome: "gone" };
+    const cell = reading.cell;
+    switch (cell.role) {
+        case "absent":
+            return WRITABLE;
+        case "writer":
+            return { outcome: "writer" };
+        case "mirror":
+            return { outcome: "mirrored" };
+        case "forking":
+            throw new SessionForkInProgressError(root);
+        default: {
+            const unknownRole = cell;
+            throw new Error(`settledMirrorOutcome: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+export function settledDeviceBindOutcome(root, reading, occupant, deviceId) {
+    if (reading === undefined || !sameOccupant(reading.occupant, occupant))
+        return { outcome: "gone" };
+    const cell = reading.cell;
+    switch (cell.role) {
+        case "absent":
+            return WRITABLE;
+        case "writer":
+            if (cell.lane !== "device")
+                return { outcome: "tree_bound", boundLane: cell.lane };
+            if (cell.device === undefined)
+                return WRITABLE;
+            return cell.device.id === deviceId ? { outcome: "same", device: cell.device } : { outcome: "device_conflict", device: cell.device };
+        case "mirror":
+            return { outcome: "mirror" };
+        case "forking":
+            throw new SessionForkInProgressError(root);
+        default: {
+            const unknownRole = cell;
+            throw new Error(`settledDeviceBindOutcome: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+export function settledDeviceRebindOutcome(reading, occupant, owner, expectedRev, targetDeviceId) {
+    if (reading === undefined || !sameOccupant(reading.occupant, occupant))
+        return { outcome: "gone" };
+    const device = boundDeviceOf(reading.cell);
+    if (device === undefined)
+        return { outcome: "gone" };
+    if (device.owner.tenant !== owner.tenant || device.owner.subject !== owner.subject)
+        return { outcome: "gone" };
+    if (device.rev !== expectedRev)
+        return { outcome: "rev_conflict", device };
+    return device.id === targetDeviceId ? { outcome: "idempotent", device } : WRITABLE;
+}
+export function boundDeviceOf(cell) {
+    switch (cell.role) {
+        case "writer":
+            return cell.lane === "device" ? cell.device : undefined;
+        case "absent":
+        case "mirror":
+        case "forking":
+            return undefined;
+        default: {
+            const unknownRole = cell;
+            throw new Error(`boundDeviceOf: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+export function assertPlaceableLane(root, cell) {
+    if (cell.lane === "device" || cell.device !== undefined) {
+        throw new Error(`execution placement of session ${root}: the device lane is placed by the device store (it judges the device row in the same transaction), not by the session store's seat`);
+    }
+}
+export class InMemoryExecutionPlacementSeat {
+    rows = new Map();
+    seatRow(root, occupant) {
+        if (!this.rows.has(root))
+            this.rows.set(root, { occupant, cell: { role: "absent" } });
+    }
+    dropRow(root) {
+        this.rows.delete(root);
+    }
+    async read(root) {
+        return this.rows.get(root);
+    }
+    async place(root, occupant, cell) {
+        assertPlaceableLane(root, cell);
+        const settled = settledPlaceOutcome(root, this.rows.get(root), occupant, cell);
+        if (settled !== WRITABLE)
+            return settled;
+        this.rows.set(root, { occupant, cell: { role: "writer", lane: cell.lane } });
+        return { outcome: "placed" };
+    }
+    async markMirror(root, occupant) {
+        const settled = settledMirrorOutcome(root, this.rows.get(root), occupant);
+        if (settled !== WRITABLE)
+            return settled;
+        this.rows.set(root, { occupant, cell: { role: "mirror" } });
+        return { outcome: "mirrored" };
+    }
+    bindDevice(root, occupant, device, placedAt) {
+        const settled = settledDeviceBindOutcome(root, this.rows.get(root), occupant, device.id);
+        if (settled !== WRITABLE)
+            return settled;
+        const placed = { id: device.id, owner: device.owner, rev: 0, placedAt };
+        this.rows.set(root, { occupant, cell: { role: "writer", lane: "device", device: placed } });
+        return { outcome: "bound", device: placed };
+    }
+    rebindDevice(root, occupant, owner, expectedRev, targetDeviceId, placedAt) {
+        const row = this.rows.get(root);
+        const settled = settledDeviceRebindOutcome(row, occupant, owner, expectedRev, targetDeviceId);
+        if (settled !== WRITABLE)
+            return settled;
+        const from = row !== undefined ? boundDeviceOf(row.cell)?.id : undefined;
+        if (from === undefined)
+            throw new Error(`execution placement of session ${root}: the rebind judge found a device cell that is no longer there — refusing to guess`);
+        const placed = { id: targetDeviceId, owner, rev: expectedRev + 1, placedAt };
+        this.rows.set(root, { occupant, cell: { role: "writer", lane: "device", device: placed } });
+        return { outcome: "rebound", device: placed, from };
+    }
+}
+//# sourceMappingURL=execution-placement.js.map

package/dist/field-conflict.d.ts

@@ -1,5 +1,5 @@
 /** 冲突的类(闭集)。同一个约束的几个拒点同一个词;新增一类见文件头。 */
-export declare const FIELD_CONFLICT_KINDS: readonly ["cascade_verify", "image_profile", "resume_anchor", "system_prompt_fold", "file_history_restore", "skills_disabled", "existing_session", "scratchpad_root", "ask_answer", "policy_person_ask", "plan_edit", "plan_mode_after", "bound_call_door", "remember_decision", "approval_feedback"];
+export declare const FIELD_CONFLICT_KINDS: readonly ["cascade_verify", "image_profile", "resume_anchor", "system_prompt_fold", "file_history_restore", "skills_disabled", "existing_session", "fork_target", "scratchpad_root", "ask_answer", "policy_person_ask", "plan_edit", "plan_mode_after", "bound_call_door", "remember_decision", "approval_feedback"];
 /** 冲突的类(闭集词)。 */
 export type FieldConflictKind = (typeof FIELD_CONFLICT_KINDS)[number];
 /**
@@ -11,9 +11,10 @@ export interface FieldConflictCoordinates {
     readonly image_profile: "capabilitiesNeeded" | "sandboxImageProfile";
     readonly resume_anchor: "resumeAtMode" | "resumeAt";
     readonly system_prompt_fold: "appendSystemPrompt" | "settings.outputStyle";
-    readonly file_history_restore: "fileHistory" | "restoreFiles" | "rewindFilesTo" | "rewindFiles";
+    readonly file_history_restore: "fileHistory" | "restoreFiles" | "rewindFilesTo";
     readonly skills_disabled: "disableSkills" | "skills" | `agents[${number}].skills`;
     readonly existing_session: "requireExistingSession" | "sessionId";
+    readonly fork_target: "forkId" | "forkNonce";
     readonly scratchpad_root: "cwd" | "scratchpadDir";
     readonly ask_answer: "decision" | "answer";
     readonly policy_person_ask: "decision" | "decidedBy";

package/dist/field-conflict.js

@@ -6,6 +6,7 @@ export const FIELD_CONFLICT_KINDS = [
     "file_history_restore",
     "skills_disabled",
     "existing_session",
+    "fork_target",
     "scratchpad_root",
     "ask_answer",
     "policy_person_ask",

package/dist/gate-settlement.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 回决门族 200 体上的**结清证据**(`decisionCommitted` / `checkpointId`)—— 唯一铸点与唯一读法。
+ *
+ * ## 律(一条)
+ * `decisionCommitted: true` = 「本请求点名的那道门,已以本请求的决定被耐久地结清过」的**历史证据**。它只在下面五个执行 / 回放边界之一
+ * 被跨过的那一拍、由 {@link buildSettlementEvidence} 铸(闭集 {@link SettlementCrossing},`switch` 穷尽):
+ *  ① `engine_accepted` —— 引擎续跑腿的受理点(`resumeStream` 解析 = 引擎的 pre-CAS 守卫与 checkpoint resolve CAS 都过了);
+ *  ② `engine_terminal` —— 引擎续跑腿交回结果之后的终局体(同步长调用形 / verify 臂;含「已提交、又重开同一张卡」的 `retriable:true` 那一形);
+ *  ③ `replay_matched`  —— `/decide` 幂等回放比对通过(同一决定早已与 resolve 原子地落在行上;回放不起续跑);
+ *  ④ `agent_revived`   —— 停驻后台子代复活成功(引擎以选中的 token 续跑、attach 之后才交回);
+ *  ⑤ `card_voided`     —— 复活不了的停驻子代被 deny 作废成功(这道门以本 deny **经作废结清**:卡 pending → expired;没有 resolve、没有 deny 结果行)。
+ * 调用方对一条引擎续跑腿的分类({@link GateCommitment})只说「这条腿到边界时能证什么」,**从不单独铸位** —— 位要有边界作证。
+ * 不铸的出口(都在调用点成文):`checkpoint.resume_aborted` 取消(拿不到 resolve 的返回值 ⇒ 证不出)、抛出臂的取消(受理之后也可能走到 ⇒
+ * **刻意不带**证据,fail-closed)、4xx、交给宿主 / 新铸一跑 / 同一决定重投的回执(`delivered`,门由别人结清或仍待决)、停驻子代认领到的
+ * token 不是选中的那一张(⇒ `409 decide.gate_moved`,不复活)。证据只随**同一次决定**的回放走:停驻赎回席的反向重试回放摘掉它
+ * ({@link withoutSettlementEvidence})。
+ *
+ * ## 读法(三句,契约 §4a「结清证据」同句)
+ *  · 位在场 ⇒ 门已以此决定结清过(历史证据;与 `errorCode:"cancelled"` 或 `retriable:true` 并存时同样成立 —— 它不证明卡的**当前**状态、
+ *    不证明批过的动作执行了);
+ *  · 位缺席 ⇒ 证不出或刻意不带,按「没提交」读;
+ *  · `checkpointId` = 执行**前**从选中的那一行捕获、过信任边界(`checkpoint-identity.ts` 的 `durableRowIdentity`,face `decision-receipt`)
+ *    的门身份,只随位出现;缺席 = 身份不可用(老行 / 没过边界)或不适用(回放的投影不带门身份),不推断任何事。
+ *
+ * ## 读者
+ * 本仓两个:`/decide` 的 [ref] 迟到结算留痕与 remember 豁免落店,都经 {@link decisionCommittedOf} 读体上的位(一处读法;不读 `errorCode`)。
+ * 纯数据、零运行时依赖(停驻子代腿与 HTTP 层共用)。
+ */
+import type { GateIdentity } from "./checkpoint-identity.js";
+/**
+ * 一条**引擎续跑腿**到达边界时能证什么(调用方声明;闭集)。`DriveResumeArgs` 的必填位 —— 同一条驱动路径既续本请求点名的门,也替宿主投递。
+ *  · `gate_resolved` —— 这条腿 resolve 的就是本请求点名的那道门(`/decide` 引擎臂、`/resume`、`/plan_review`);`checkpointId` = 执行前捕获的身份片段。
+ *  · `delivered`     —— 这条腿 resolve 的是宿主的门(wake;含 `/decide` workflow 车道的 wake 投递腿):本请求点名的那道门由别人结清或仍待决 ⇒ 到任何边界都不铸。
+ */
+export type GateCommitment = {
+    readonly kind: "gate_resolved";
+    readonly checkpointId?: string;
+} | {
+    readonly kind: "delivered";
+};
+/** 五个边界(铸点穷尽)。引擎两边界按腿的分类铸;回放不带身份;停驻子代两边界的门恒是本请求点名的那道,身份取执行前捕获的那一份。 */
+export type SettlementCrossing = {
+    readonly at: "engine_accepted" | "engine_terminal";
+    readonly commitment: GateCommitment;
+} | {
+    readonly at: "replay_matched";
+} | {
+    readonly at: "agent_revived" | "card_voided";
+    readonly gate: GateIdentity;
+};
+/** 体上的结清证据(两键都可缺席;wire 只加)。由调用方原样展开进它自己的体形(各体形保持各自的键集,不并进一张受理形)。 */
+export interface GateSettlementEvidence {
+    readonly decisionCommitted?: true;
+    readonly checkpointId?: string;
+}
+/** 没有跨过任何边界的回执(`/decide` workflow 车道的宿主新一跑、同一决定重投)带的证据:无。 */
+export declare const NO_SETTLEMENT_EVIDENCE: GateSettlementEvidence;
+/** **唯一铸点**:一次边界跨越 → 体上的证据片段。 */
+export declare function buildSettlementEvidence(crossing: SettlementCrossing): GateSettlementEvidence;
+/**
+ * 一张已带证据的回执被拿去答**另一个**决定(停驻赎回席的反向重试:回放首次受理的那一向、不改判)⇒ 证据两键都摘掉 ——
+ * 证据说的是当初被结清的那次决定,这一次请求的决定从没被结清。同向重试是同一次请求的回放,体原样(证据随它)。
+ * 只摘、不铸:本模块之外没有第二个写这两键的地方。
+ */
+export declare function withoutSettlementEvidence<B extends Record<string, unknown>>(body: B): Omit<B, keyof GateSettlementEvidence>;
+/** **唯一读法**:这张回决应答说「门已以此决定结清过」吗(`200` 且体上的位为真)。两个读者同调这一只。 */
+export declare function decisionCommittedOf(out: {
+    readonly status: number;
+    readonly body: object;
+}): boolean;
+//# sourceMappingURL=gate-settlement.d.ts.map

package/dist/gate-settlement.js

@@ -0,0 +1,40 @@
+export const NO_SETTLEMENT_EVIDENCE = Object.freeze({});
+const settled = (gate) => ({
+    decisionCommitted: true,
+    ...(gate.checkpointId !== undefined ? { checkpointId: gate.checkpointId } : {}),
+});
+export function buildSettlementEvidence(crossing) {
+    switch (crossing.at) {
+        case "engine_accepted":
+        case "engine_terminal": {
+            const c = crossing.commitment;
+            switch (c.kind) {
+                case "gate_resolved":
+                    return settled(c);
+                case "delivered":
+                    return NO_SETTLEMENT_EVIDENCE;
+                default: {
+                    const unhandled = c;
+                    throw new Error(`unhandled gate commitment: ${JSON.stringify(unhandled)}`);
+                }
+            }
+        }
+        case "replay_matched":
+            return settled({});
+        case "agent_revived":
+        case "card_voided":
+            return settled(crossing.gate);
+        default: {
+            const unhandled = crossing;
+            throw new Error(`unhandled settlement crossing: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+export function withoutSettlementEvidence(body) {
+    const { decisionCommitted: _committed, checkpointId: _identity, ...rest } = body;
+    return rest;
+}
+export function decisionCommittedOf(out) {
+    return out.status === 200 && out.body.decisionCommitted === true;
+}
+//# sourceMappingURL=gate-settlement.js.map

package/dist/hooks/classic-stations.d.ts

@@ -25,6 +25,7 @@ export declare const CLASSIC_STATION_ROLE: {
     readonly "classic.UserPromptSubmit": "chain";
     readonly "classic.Stop": "chain";
     readonly "classic.SubagentStop": "chain";
+    readonly "classic.SubagentStart": "chain";
     readonly "classic.StopFailure": "observe";
     readonly "classic.PreCompact": "chain";
     readonly "classic.PostCompact": "observe";

package/dist/hooks/classic-stations.js

@@ -6,6 +6,7 @@ export const CLASSIC_STATION_ROLE = {
     "classic.UserPromptSubmit": "chain",
     "classic.Stop": "chain",
     "classic.SubagentStop": "chain",
+    "classic.SubagentStart": "chain",
     "classic.StopFailure": "observe",
     "classic.PreCompact": "chain",
     "classic.PostCompact": "observe",

package/dist/hooks/command-spawn.d.ts

@@ -26,7 +26,7 @@ export declare function commandLineChars(entry: {
 export declare function hookPluginEnv(p: HookPluginContext | undefined): Record<string, string>;
 /**
  * 起法:shell 形交回命令串(shell 由调用点落定),exec 形交回可执行名与参数,起不来交回真因(进调用点的 `spawnError`)。
- * `env` = 这条 hook 的**有效环境层**({@link composeHookEnvLayer} 的产物;调用点铺在基础 allowlist 之上,不再自己合并任何一层)。
+ * `env` = 这条 hook 的**有效环境层**({@link composeHookEnvLayer} 的产物;调用点把它作为授予交给宿主子进程的唯一组合,不再自己合并任何一层)。
  */
 export type CommandSpawnPlan = {
     readonly kind: "shell";
@@ -42,7 +42,7 @@ export type CommandSpawnPlan = {
     readonly error: string;
 };
 /**
- * 一条 command hook 的**有效环境层**(基础 allowlist 之上的那一层)—— **唯一铺法**,后铺者赢:`CLAUDE_PROJECT_DIR` 的缺省(`cwd`,hook 的工作目录;请求没写它才取)< 请求 `settings.env`(`requestEnv`;
+ * 一条 command hook 的**有效环境层**(继承之上的那一层授予)—— **唯一铺法**,后铺者赢:`CLAUDE_PROJECT_DIR` 的缺省(`cwd`,hook 的工作目录;请求没写它才取)< 请求 `settings.env`(`requestEnv`;
  * 请求自己写了 `CLAUDE_PROJECT_DIR` 就是它,空串也照用)< 条目自己的插件上下文({@link hookPluginEnv})。键的枚举顺序 = 请求的键在前、`CLAUDE_PROJECT_DIR` 缺省时接后、插件键最后。调用点传**原料**(工作目录与请求 env),不预先取舍 `CLAUDE_PROJECT_DIR`。
  * 「有没有值」的判据、exec 形的占位替换、shell 形子进程的环境都读这一个对象(见文件头);http 条目的 `$NAME` 插值取环境也走这一只(无插件上下文)。
  */