@sema-agent/server 7.138.0 → 7.139.0

package/dist/plugins/memory-run-store.d.ts

@@ -47,7 +47,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
      *  OBSERVED, see {@link CreateRunOutcome}) and the session has no active run (the task_active unique-key claim). */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
-     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
+     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement reject):
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;

package/dist/plugins/one-time-migrations.d.ts

@@ -287,6 +287,35 @@
  *    ≤7.136.x 的读者只认 `promptProfile`,读到本条改写过的体(旧键已删、换成 `promptLean`)回到缺省形 —— 本版副本起服之后仍在续跑的 7.136.x 副本、回滚到 7.136.x 之后,
  *    被改写过的 `"classic"` 行静默回短形;也不能给旧读者留旧键(那是同一事实的两份表示,本版读者对仍带旧键的体响亮拒)⇒ 升级序是**先停光 ≤7.136.x 副本、再起第一个 7.137.0 副本**,
  *    回滚之前先决完或取消停驻的任务(随包 MIGRATION 7.137.0 第 4 条;与 M28 的混跑登记同形)。
+ *  · **M31 记忆同步游标搬到每层一只的路径**(7.139.0,引擎 7.60.0)—— 一轮的对端改由 transport 的身份(规范化的中心基址)说,游标改成每层一只
+ *    `sync-cursors/<scope 摘要>.json`(对端是游标里的一格事实,只由引擎判)。升级前的游标落在上一版的分区目录 `sync-cursors/central/<同名>` 与更早的
+ *    `sync-cursor-central.json` —— 新路径上找不到它们 ⇒ 那几层以空基线首轮跑(没人选过的重收敛:上一轮之后在一侧删掉的条目从另一侧回来)。
+ *    ⇒ **同步执行器的第一轮先把它们搬到各自那一层的路径**(只 `rename`、字节不变;编排在 `memory-sync-client.ts` `relocateSyncCursorsM31`,不在本文件的
+ *    迁移段里 —— 那一段跑在 SQL 店层,游标是 File 记忆根下的文件),搬来的游标照常交引擎判:它们绑的对端是 `"central"`,不等于任何铸出的身份 ⇒
+ *    这一层拒同步并点名两条出路(运维确认同一只中心后把游标的 `peer` 改成新身份,或删游标接受空基线重收敛)。目标路径上已有游标 ⇒ 不搬、一行 warn;
+ *    更早的那只文件读不成对象 / 没有 scope ⇒ 原地不动、一行 warn。读数不进 {@link OneTimeMigrationReport}(`reportKeys` 空),逐文件一行 info / warn。窗外不搬。
+ *  · **M32 执行放置切换**(7.139.0)—— 执行放置是根会话行上这一位住客的一格(`execution-placement.ts` 头注),根会话 ↔ 设备的绑定是这一格的 writer(device, D);
+ *    ≤7.137.x 的绑定住在单独一张表 `device_session` 里(起服无条件建它)。运行期只有会话行一种读法 ⇒ **一次性**把绑定整行搬进会话行、表退役,存量有 run 的会话
+ *    回填放置。判据只有库自己的形(读者 = 本文件的两只在场探针 `tableExists` / `columnExists`):**切换开始** ⇔ `session_meta.execution_role` 列在 ∨ 中途表
+ *    `device_session_retired` 在;**切换收尾** ⇔ 八列都在 ∧ 两张绑定表都不在(这就是「跑过了」的标记,没有账表)。
+ *    · **DDL 前只读探针**({@link assertExecutionPlacementSwitchAdmissible},与退役 schema 探针同层、同一只调用点 —— `store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE ⇒ 拒时库零写;
+ *      全新库不判):**围栏(唯一一条)** 切换开始 ∧ `device_session` 在 ∧ 有行 ⇒ 拒 `fence`(旧版副本在切换开始后还在写它,或手写行 —— 谁新谁旧本服务判不出、不替人挑;
+ *      拒句按方言给「采旧 = 改名进中途表、起服时整行覆盖」/「弃旧 = DROP」两条语句与根会话列表);**回填前提** 切换未收尾 ∧ 车道表不是一元 ∧ 回填前提表里任一员答「还有」⇒ 拒 `backfill_ambiguous`
+ *      (今天车道表恒一元 ⇒ 这一臂在声明多车道之前不可达;回填前提表是有序可扩的一张,问行车道的那一员由审批店那一侧补)。码 `config.execution_placement_switch_refused`。
+ *    · **迁移段**(本段最后一步,锁内;切换已收尾 ⇒ 零动作;否则先在锁内复判围栏,再按有序步骤表逐步收敛 —— 每步先读形再判、DDL 按后置条件 `execUntil`):
+ *      ⓪ 切换开始 ∧ `device_session` 在(围栏判过 ⇒ 空的:旧版副本在已切换库上起服建回的空表)⇒ DROP · ① `device_session` 在 ∧ 执行列不在 ⇒ 改名成中途表(先于加列)·
+ *      ② 八列里缺的逐列 ADD(列定义 = 中央 DDL 内插的同一份)· ③ 中途表整行覆盖根会话行的 device 位(`rev` 原值、`bound_at → execution_placed_at`;根会话行不在 / 是委派分区行的孤儿丢弃并计数)·
+ *      ④ 有 run、没有执行格、不是委派分区行的会话行 ⇒ writer(表唯一项)(device 车道 ⇒ writer(device, ∅) = 有 run 而设备未知;不是一元表而还有要回填的 ⇒ 与探针同一只拒)·
+ *      (问行车道回填由审批店那一侧补在 ④ 之后)· ⑤ 中途表 DROP。中断 ⇒ 下一次起服从首个未满足的后置条件续(钉:真库逐步注入中断后续跑收敛、不触围栏)。
+ *    · **local 车道**:没有绑定表、没有 `session_meta`(device 车道只在 SQL 后端)⇒ 只有 ④ 与回填前提:读本地 run 店有 run 的会话,执行席读出 absent 的 ⇒ 经同一只席 `place` 成 writer(表唯一项)
+ *      (`LocalBackend.runOneTimeMigrations`);local 没有「切换收尾」的形可读 ⇒ 窗内每次起服都判,首跑之后它只碰认领与放置之间被打断的会话(与 `place` 会落下的格同值)。
+ *      有 run、而**存档读不出**的会话 —— 会话元数据格缺(升级链上从没被再读过的老会话)而探针读不出,或 fork 创建的格而探针说不出存档在不在 ——:回填跳过它并点名
+ *      (读数 `executionPlacementSessionsUnreadable` + 一行一条 warn `execution_placement_session_unreadable`,带会话 id 与故障词〔闭集 `corrupt_session` / `invalid_session` / `storage`;
+ *      `storage` = 读存档文件时抛了别的故障:权限 / 磁盘 I/O / 超大,再带 `errno`〕),**不拒启**、一个字节没写 —— 回填只补一格放置、不动存档,读不出的存档不归它判
+ *      (这一支只收**探针对这只会话的读故障**;会话元数据边档本身读不出、问账日志压实失败等整库级故障照旧拒启);该会话的请求照旧答存档的故障,存档修好(从留存副本恢复,
+ *      或 `storage` 时权限 / 磁盘修好)后的下一次起服照常补放置;存档移走则它不再是本服务的会话(不补放置、不再点名;fork 创建的会话例外 —— 它的格还在,读作 fork 未落定,出路是同键重试那次 fork 或删除该会话)。
+ *    · **旧版在已切换库上**:≤7.137.x 起服建回空 `device_session`,随后列册对账见执行列为幽灵列拒启、零行写;再起本版 ⇒ ⓪ 删掉那张空表。回滚的唯一支持形 = 恢复切换前的备份。
+ *    读数:`executionPlacementColumnsAdded` / `deviceBindingsMoved` / `deviceBindingsOrphaned`(非零 ⇒ 另一行 warn)/ `deviceBindingTablesDropped` / `executionPlacementsBackfilled` / `executionPlacementSessionsUnreadable`(点名数组 `{ sessionId, fault, errno? }`,只 local;一行一条 warn),收据只记起服日志行。
  *
  * ## 收据账(一次起服一只,每一条迁移同一只)
  * 每一步把它**已提交**的改写 / 删除与点名读数当场记进同一只收据账({@link MigrationReceipts}):计数随每次提交累加、行随每次提交追加、形读数在那一步落定时写。走完 ⇒
@@ -304,7 +333,11 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type AllowEntryInertReason, type GateKind } from "@sema-agent/core";
+import { StoreBootRefusalError } from "./store-contracts.js";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
+import type { ExecutionLane } from "../execution-lane-caps.js";
+import { type LocalPlacementBackfillSeat, type UnusableArchiveWord } from "../execution-placement.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
     /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行,必须让运维看见。 */
@@ -375,6 +408,21 @@ export interface OneTimeMigrationReport {
     /** M29:该回填、卡词却放不进列的停驻行 —— 门上的卡词超过 `approval_card` 列的容量(MySQL 协议方言 TEXT = 65,535 UTF-8 字节;PG 无上限,恒空)。引擎铸不出这样的词,
      *  只会是手改 / 外来写者写下的行;一个字节没写(列留 NULL,读面按缺列读 —— 与「无卡」同读),起服不挡。一行一条 warn 点名(会话 id + 字节数)。SQL 独有;local 恒空。 */
     readonly parkedApprovalCardRowsTooLong: readonly ParkedApprovalCardRowTooLong[];
+    /** M32:本次给 `session_meta` 补上的执行放置列数(八列里缺的那几列;新库 / 切换已收尾恒 0)。非零 = 这次真改了表形。SQL 独有;local 恒 0。 */
+    readonly executionPlacementColumnsAdded: number;
+    /** M32:本次从退役的绑定表(经中途名)整行搬进根会话行执行格的绑定数(驱动回报的受影响行数)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingsMoved: number;
+    /** M32:搬的时候指向的根会话行不在(或是委派分区行)⇒ 丢弃的绑定数(非零 ⇒ 另一行 warn 点名条数)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingsOrphaned: number;
+    /** M32:本次删掉的绑定表数(⓪ 空的退役表 / ⑤ 搬完的中途表;0–2)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingTablesDropped: number;
+    /** M32:本次回填的执行放置数(有 run 行、没有执行格的会话 ⇒ writer(表唯一项))。SQL 与 local 都有。非零 = 真写了存量行。 */
+    readonly executionPlacementsBackfilled: number;
+    /** M32 ④b:本次回填了出处车道的问行数(车道未回填的问行 ⇒ 根会话放置的车道,无放置 / 无会话行 ⇒ 表唯一项)。SQL 与 local(问账日志一次压实)都有。非零 = 真写了存量行。 */
+    readonly askExecutionLanesBackfilled: number;
+    /** M32 local 腿:该回填放置、却读不出的会话 —— 有 run、存档读不出(会话头读不出 / 结构走不通 / 读存档文件时抛了别的故障:权限 / 磁盘 I/O / 超大)。一个字节没写,起服不挡:
+     *  该会话的请求照旧答存档的故障;存档修好(从留存副本恢复,或权限 / 磁盘修好)后的下一次起服照常补放置。点名行数组(会话 id + 故障词,`storage` 再带 errno),一行一条 warn,每次起服都报直到处置。SQL 独有的反面:SQL 没有这一形(行就是会话);SQL 恒空。 */
+    readonly executionPlacementSessionsUnreadable: readonly ExecutionPlacementSessionUnreadable[];
 }
 /** 退役的两只命令桶(引擎 7.51.0 起不是桶;只给 M17 点名认)。 */
 export type RetiredSessionRuleBucket = "commandAllow" | "commandDeny";
@@ -415,6 +463,16 @@ export interface ParkedApprovalCardRowUnreadable {
 export interface ParkedApprovalCardRowTooLong extends ParkedApprovalCardRowUnreadable {
     readonly bytes: number;
 }
+/**
+ * M32 local 腿被跳过的一只会话:会话 id 是点名坐标;故障词是闭集 {@link UnusableArchiveWord}(`corrupt_session` = 会话头读不出;`invalid_session` = 读得出、结构走不通;
+ * `storage` = 读的时候抛了别的故障,I/O 级 —— 权限 / 磁盘 / 超大,此时 `errno` 带那只故障的 `code`)。盘上路径与故障句不出店。
+ */
+export interface ExecutionPlacementSessionUnreadable {
+    readonly sessionId: string;
+    readonly fault: UnusableArchiveWord;
+    /** 仅 `fault === "storage"` 且那只故障带字符串 `code` 时在场(`EACCES` / `EIO` / `ERR_STRING_TOO_LONG` ……)。 */
+    readonly errno?: string;
+}
 /** 三个形读数(M9 主键 / M17 列名 / M24 scope 列)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
 type ShapeReadingKey = "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
 /**
@@ -485,8 +543,8 @@ export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow,
  * 还没有日期可写)⇒ 响亮抛,不铸一句带空日期的句子。
  */
 export declare function migrationWindowEnd(id: string): string;
-/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
-export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled">;
+/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 与 M32 的回填两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
+export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled" | "executionPlacementsBackfilled" | "askExecutionLanesBackfilled" | "executionPlacementSessionsUnreadable">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
 export interface MigrationLogSink {
     warn(msg: string, meta?: Record<string, unknown>): void;
@@ -519,7 +577,57 @@ export interface MigrationDb {
  * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了(起服对账一族 `schema-consistency.ts` 的探针口,先于建表);走公开序列
  * `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()` 的嵌入方与本服务的起服序列一样,有这一问、零动作。
  */
-export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool): Promise<OneTimeMigrationReport>;
+export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<OneTimeMigrationReport>;
+/** M32 的起服拒码(确定的拒启表态:再等也等不来另一个答案;不是线上 wire 码,与 `config.schema_mismatch` 同一族)。 */
+export declare const EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE = "config.execution_placement_switch_refused";
+/** 拒因闭集:`fence` = 切换开始之后退役绑定表里又出现了行(旧版副本 / 手工写下的);`backfill_ambiguous` = 车道表不止一项而还有要回填的存量。 */
+export type ExecutionPlacementSwitchRefusalReason = "fence" | "backfill_ambiguous";
+/**
+ * M32 的起服拒(DDL 前探针与迁移段同一只错误)。具名类型 + 机读码 + 拒因:日志消费端与测试按 `code` / `reason` 分派,不锚文案。
+ * 继承 {@link StoreBootRefusalError}:SQL 开库的等待窗不重试它(确定的拒启表态)。
+ */
+export declare class ExecutionPlacementSwitchRefusedError extends StoreBootRefusalError {
+    readonly reason: ExecutionPlacementSwitchRefusalReason;
+    readonly code = "config.execution_placement_switch_refused";
+    constructor(reason: ExecutionPlacementSwitchRefusalReason, detail: string);
+}
+/** M32 的输入:本部署声明的有序执行车道表(本版 `REMOTE_EXEC` 单值 ⇒ 一元表,`deployedExecutionLanes`)。回填只在一元表下有唯一答案。 */
+export interface ExecutionPlacementSwitchInput {
+    readonly lanes: readonly ExecutionLane[];
+}
+/**
+ * M32 的 **DDL 前只读探针**(与退役 schema 探针同层、同一只调用点:`store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE):围栏与回填前提。
+ * 拒在任何 DDL 之前 ⇒ 库零写。全新库(没有 `session_meta`)不判。纯读,不取 schema 锁(与退役 schema 探针同理)。
+ */
+export declare function assertExecutionPlacementSwitchAdmissible(read: SchemaProbeRead, dialect: "tidb" | "pg", input: ExecutionPlacementSwitchInput): Promise<void>;
+/** 探针口(入参形与本文件的迁移段入口 {@link runSqlOneTimeMigrations} 同:方言 + 它的池;借一条连接,用完即还)。 */
+export declare function assertExecutionPlacementSwitchAdmissibleOnPool(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<void>;
+/**
+ * M32(规则与理由见头注 M32 段):切换已收尾(八列在 ∧ 两张绑定表都不在)⇒ 零动作;否则先复判围栏(探针之后、锁内这一刻又有旧版副本写进行 ⇒ 同一只拒),
+ * 再按步骤表逐步收敛。跑在一次性迁移的锁里(与别的迁移步同一条连接)。导出给真库钉驱动「每步中断后续跑」。
+ */
+export declare function switchExecutionPlacement(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts, input: ExecutionPlacementSwitchInput): Promise<void>;
+/** {@link backfillLocalExecutionPlacements} 的结果:回填了几只会话 · 读不出而被跳过的会话(点名)。 */
+export interface LocalPlacementBackfill {
+    readonly backfilled: number;
+    readonly unreadable: readonly ExecutionPlacementSessionUnreadable[];
+}
+/**
+ * M32 的 **local 腿**(local 车道没有绑定表、没有 `session_meta`,只有 ④ 与回填前提):本地 run 店里有 run 的会话(`FileRunStore.sessionIdsWithRuns`),
+ * 执行席读出 absent 的 ⇒ 经**同一只席**的 `place` 写成 writer(表唯一项)(写只按住客谓词;forking / mirror / writer 与行不在的一律不碰)。
+ * 席读出「存档读不出」({@link LocalPlacementBackfillSeat}:会话头读不出 / 结构走不通 / 读的时候抛了别的故障 —— I/O 级的权限、磁盘、超大)⇒ **跳过并点名**
+ * (`unreadable`:会话 id + 故障词〔闭集 {@link UnusableArchiveWord}〕,`storage` 再带 errno;一个字节没写,不拒启):
+ * 回填不动存档、只补一格放置,读不出的存档不归它判;该会话的请求照旧答存档的故障,存档修好后的下一次起服照常补。读不出的会话不计入「还有要回填的」。
+ * 车道表不是一元而还有 absent 的 ⇒ 与 SQL 同一只拒(`backfill_ambiguous`),一个字节没写。起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前;数据根独占)。
+ */
+export declare function backfillLocalExecutionPlacements(sessionIds: Iterable<string>, seat: LocalPlacementBackfillSeat, input: ExecutionPlacementSwitchInput): Promise<LocalPlacementBackfill>;
+/**
+ * M32 ④b 的 **local 腿**:问账日志里升级前写下的问(没有出处车道)记成车道表的唯一项,一次压实重写整本账(`FileApprovalAskStore.backfillExecutionLanes`)。
+ * 车道表不是一元而还有缺车道的问 ⇒ 与 SQL 同一只拒(`backfill_ambiguous`),一个字节没写。返回回填数。起服时调(与 ④ 的 local 腿同位,任何读者之前)。
+ */
+export declare function backfillLocalAskExecutionLanes(store: {
+    backfillExecutionLanes(lanes: readonly ExecutionLane[], refuse: (pending: number) => never): number;
+}, input: ExecutionPlacementSwitchInput): number;
 /**
  * M24(7.133.0)—— workflow journal 的属主 scope 从逐行列搬进 `workflow_journal_owner` 一行,journal 行改按 `(run_id, incarnation, ordinal)` 记。规则与理由在
  * 头注 M24 段;这里只写各步为什么这样写。