@sema-agent/server 7.73.1 → 7.74.0

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

@@ -0,0 +1,66 @@
+import type { Pool as MysqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+/** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
+export interface OneTimeMigrationReport {
+    /** M1:退役快照索引表 —— `dropped` = 本次真 drop 了,`absent` = 早已不在(第二跑/全新库)。 */
+    readonly retiredSnapshotTable: "dropped" | "absent";
+    /** M1:drop 之前表上的行数(`absent` 时恒 0)。非零 = 这次迁移真删掉了存量行,必须让运维看见。 */
+    readonly retiredSnapshotRows: number;
+    /** M2:退役单座列 —— `dropped` = 本次真 DROP COLUMN,`absent` = 早已不在。 */
+    readonly retiredSteerSeatColumn: "dropped" | "absent";
+    /** M3:改名的行数(账本 `tool_end` 行 + 已决 checkpoint 的执行判词列,两者相加)。 */
+    readonly askOriginRowsMigrated: number;
+}
+/** 三条迁移都不适用的载体(local 车道没有 SQL 表)。 */
+export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated">;
+/** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
+export interface MigrationLogSink {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * M2 的拒启。**具名类型**:`openStoreBackendWithFallback` 对默认推导的 local 有降级臂,而本拒启若与
+ * 普通 Error 同形会被吃掉 —— operator 面对的就会是「服务起来了,但那条指令悄悄没了」
+ * (`RunStoreStrictHydrateError` 的同族先例,锚类型不锚文案)。
+ */
+export declare class RetiredSteerSeatError extends Error {
+    readonly rows: number;
+    /** 结构化事件名(日志消费端按它分派;文案会变,这个不会)。 */
+    readonly code = "checkpoint.pending_steer_seat_retired";
+    constructor(rows: number);
+}
+/**
+ * SQL 两后端的一次性迁移。**调用点只有一个**(boot/stores.ts,在 `ensureSchema` 之后、任何路由装配
+ * 之前)—— 拒启在那一刻仍然是拒启(还没开始服务),而 `ensureSchema` 那条通道的契约是「只发 CREATE」
+ * (`test/ensure-schema.test.ts` 的运行时门),增量语句一条都不许进去。
+ *
+ * ## 并发(codex r1 [medium],亲核复现后修)
+ * 一次滚动升级会让 N 个副本同时跑到这里。整段因此跑在**一条连接**上、握着**与 `ensureSchema` 同一把**
+ * advisory 锁(MySQL 具名锁 / PG `pg_advisory_lock`):本段是「启动期改 schema 的活」,与 ensure 属同一类,
+ * 复用同一把锁 ⇒ 本仓这一类工作只有**一个**锁身份,而且本段也不会与另一个副本的 ensure 交错。
+ * 锁拿不到时按既有先例**降级**(不阻塞启动),但降级不等于放任:每条破坏性 DDL 的成功判据是它的
+ * **后置条件**({@link execUntil}),所以「另一个副本抢先删掉了同一列」不会把滚动升级变成启动失败循环。
+ *
+ * ## 次序(codex r1 [medium] 同轮)
+ * 读 → 非破坏改写 → 破坏性 DDL。①拒启臂是纯读,拒的时候盘上一个字节没动;②M3 是改值不丢信息的
+ * UPDATE,它是最可能超时的一步,放在删表删列**之前**;③真正的破坏排在最后,且失败时把**已完成的
+ * 破坏性步骤及其读数**写进拒因 —— 否则「删完表再失败」会让重试看到一张不存在的表、把行数报成 0,
+ * 证据永久消失。
+ *
+ * @throws {RetiredSteerSeatError} M2 探到非空的退役席位(唯一的拒启臂)。
+ */
+export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool): Promise<OneTimeMigrationReport>;
+/**
+ * M3 的**纯**改写(local 车道的账本行逐条走它;SQL 两腿在服务端用等价的 JSON 路径表达同一件事)。
+ * 不改原对象(调用方与账本共享引用):有变更时换一只信封,原记录一个字节不动;无变更 ⇒ 返回
+ * `undefined`,调用方据此**不写盘**(第二跑因此零 I/O)。
+ */
+export declare function migrateRetiredAskOrigin(type: string, data: unknown): Record<string, unknown> | undefined;
+/**
+ * 启动日志的读数行。零命中(第二跑起的常态)也照发 —— 「跑过了、什么都没改」与「压根没跑」必须可分辨。
+ *
+ * 🔴 **级别按「这次真动了没有」分**:动了 ⇒ `warn`(有人的持久数据被改写/删除了,运维该看见一次);
+ * 没动 ⇒ `info`。把恒常的空转也发成 warn 会训练运维忽略 warn —— 那是在为了本段的可见性去损耗整条告警轴。
+ */
+export declare function logOneTimeMigrations(log: MigrationLogSink, backend: string, report: OneTimeMigrationReport): void;
+//# sourceMappingURL=one-time-migrations.d.ts.map

package/dist/plugins/one-time-migrations.js

@@ -0,0 +1,193 @@
+import { acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
+import { ENSURE_SCHEMA_LOCK_KEY } from "./pg-pool.js";
+export const NO_SQL_MIGRATIONS = {
+    retiredSnapshotTable: "absent",
+    retiredSnapshotRows: 0,
+    retiredSteerSeatColumn: "absent",
+};
+const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
+const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
+const RETIRED_ASK_ORIGIN = { from: "unresolvable", to: "ancestor_marked" };
+const GATE_BEARING_LEDGER_EVENT_TYPE = "tool_end";
+export class RetiredSteerSeatError extends Error {
+    rows;
+    code = "checkpoint.pending_steer_seat_retired";
+    constructor(rows) {
+        super(`checkpoint.pending_steer_seat_retired: ${rows} checkpoint row(s) still carry a value in the RETIRED single-seat ` +
+            `steering column \`${RETIRED_STEER_SEAT_COLUMN}\`. That seat is gone from the engine (a resume of such a row is ` +
+            `refused pre-CAS), so the value is an operator instruction nothing will ever deliver, and this service refuses ` +
+            `to guess what it should become (folding a bare seat into the queue would mint a queue entry the engine never ` +
+            `wrote). Note that no earlier version ever cleared that cell after delivering it, so most non-NULL cells sit on ` +
+            `rows that can never be resumed again — those are stale and safe to clear: ` +
+            `\`UPDATE checkpoint SET ${RETIRED_STEER_SEAT_COLUMN} = NULL WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL AND ` +
+            `(status = 'expired' OR execution_outcome IS NOT NULL)\`. Any cell left after that is on a still-live row and holds an ` +
+            `undelivered instruction: decide or cancel those runs on server 7.73.x first (or accept dropping the instruction), ` +
+            `then clear the rest (\`UPDATE checkpoint SET ${RETIRED_STEER_SEAT_COLUMN} = NULL WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL\`) ` +
+            `and start this version again.`);
+        this.rows = rows;
+        this.name = "RetiredSteerSeatError";
+    }
+}
+function mysqlDb(conn) {
+    return {
+        async rows(sql) {
+            const [rows] = await conn.query(sql);
+            return rows;
+        },
+        async exec(sql) {
+            const [r] = await conn.query(sql);
+            return Number(r.affectedRows ?? 0);
+        },
+    };
+}
+function pgDb(client) {
+    return {
+        async rows(sql) {
+            const r = await client.query(sql);
+            return r.rows;
+        },
+        async exec(sql) {
+            const r = await client.query(sql);
+            return r.rowCount ?? 0;
+        },
+    };
+}
+async function tableExists(db, dialect, table) {
+    const sql = dialect === "tidb"
+        ? `SELECT 1 AS present FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = '${table}'`
+        : `SELECT 1 AS present FROM information_schema.tables WHERE table_schema = current_schema() AND table_name = '${table}'`;
+    return (await db.rows(sql)).length > 0;
+}
+async function execUntil(db, sql, postcondition) {
+    try {
+        await db.exec(sql);
+    }
+    catch (e) {
+        if (!(await postcondition()))
+            throw e;
+    }
+}
+async function columnExists(db, dialect, table, column) {
+    const scope = dialect === "tidb" ? "DATABASE()" : "current_schema()";
+    const sql = `SELECT 1 AS present FROM information_schema.columns WHERE table_schema = ${scope} AND table_name = '${table}' AND column_name = '${column}'`;
+    return (await db.rows(sql)).length > 0;
+}
+export async function runSqlOneTimeMigrations(dialect, pool) {
+    return dialect === "tidb" ? withMysqlLock(pool, (db) => migrateOn(db, "tidb")) : withPgLock(pool, (db) => migrateOn(db, "pg"));
+}
+async function withMysqlLock(pool, run) {
+    const conn = await pool.getConnection();
+    let locked = false;
+    try {
+        locked = await acquireEnsureSchemaLock(conn, "oneTimeMigrations");
+        return await run(mysqlDb(conn));
+    }
+    finally {
+        if (locked)
+            await releaseEnsureSchemaLock(conn, "oneTimeMigrations");
+        conn.release();
+    }
+}
+async function withPgLock(pool, run) {
+    const client = await pool.connect();
+    let locked = false;
+    try {
+        try {
+            await client.query("SELECT pg_advisory_lock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
+            locked = true;
+        }
+        catch (err) {
+            console.warn(`[oneTimeMigrations] pg_advisory_lock(${ENSURE_SCHEMA_LOCK_KEY}) failed; running the migration unserialized:`, err);
+        }
+        return await run(pgDb(client));
+    }
+    finally {
+        if (locked) {
+            await client
+                .query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY])
+                .catch((err) => void console.warn(`[oneTimeMigrations] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (auto-freed on connection close):`, err));
+        }
+        client.release();
+    }
+}
+async function migrateOn(db, dialect) {
+    const seatColumnPresent = await columnExists(db, dialect, "checkpoint", RETIRED_STEER_SEAT_COLUMN);
+    if (seatColumnPresent) {
+        const seatRows = await db.rows(`SELECT COUNT(*) AS n FROM checkpoint WHERE ${RETIRED_STEER_SEAT_COLUMN} IS NOT NULL`);
+        const seats = Number(seatRows[0]?.n ?? 0);
+        if (seats > 0)
+            throw new RetiredSteerSeatError(seats);
+    }
+    const snapshotTablePresent = await tableExists(db, dialect, RETIRED_SNAPSHOT_TABLE);
+    const retiredSchemaPresent = seatColumnPresent || snapshotTablePresent;
+    const askOriginRowsMigrated = !retiredSchemaPresent
+        ? 0
+        : dialect === "tidb"
+            ? (await db.exec(`UPDATE task_event SET data = JSON_SET(data, '$.gate.origin', '${RETIRED_ASK_ORIGIN.to}') ` +
+                `WHERE type = '${GATE_BEARING_LEDGER_EVENT_TYPE}' AND JSON_UNQUOTE(JSON_EXTRACT(data, '$.gate.origin')) = '${RETIRED_ASK_ORIGIN.from}'`)) +
+                (await db.exec(`UPDATE checkpoint SET execution_outcome = JSON_SET(execution_outcome, '$.origin', '${RETIRED_ASK_ORIGIN.to}') ` +
+                    `WHERE JSON_UNQUOTE(JSON_EXTRACT(execution_outcome, '$.origin')) = '${RETIRED_ASK_ORIGIN.from}'`))
+            : (await db.exec(`UPDATE task_event SET data = jsonb_set(data, '{gate,origin}', '"${RETIRED_ASK_ORIGIN.to}"') ` +
+                `WHERE type = '${GATE_BEARING_LEDGER_EVENT_TYPE}' AND data->'gate'->>'origin' = '${RETIRED_ASK_ORIGIN.from}'`)) +
+                (await db.exec(`UPDATE checkpoint SET execution_outcome = jsonb_set(execution_outcome, '{origin}', '"${RETIRED_ASK_ORIGIN.to}"') ` +
+                    `WHERE execution_outcome->>'origin' = '${RETIRED_ASK_ORIGIN.from}'`));
+    let retiredSnapshotTable = "absent";
+    let retiredSnapshotRows = 0;
+    let retiredSteerSeatColumn = "absent";
+    const destroyed = [];
+    try {
+        const counted = !snapshotTablePresent
+            ? undefined
+            : await db.rows(`SELECT COUNT(*) AS n FROM ${RETIRED_SNAPSHOT_TABLE}`).then((rows) => Number(rows[0]?.n ?? 0), async (e) => {
+                if (await tableExists(db, dialect, RETIRED_SNAPSHOT_TABLE))
+                    throw e;
+                return undefined;
+            });
+        if (counted !== undefined) {
+            retiredSnapshotRows = counted;
+            await execUntil(db, `DROP TABLE IF EXISTS ${RETIRED_SNAPSHOT_TABLE}`, async () => !(await tableExists(db, dialect, RETIRED_SNAPSHOT_TABLE)));
+            retiredSnapshotTable = "dropped";
+            destroyed.push(`dropped table ${RETIRED_SNAPSHOT_TABLE} (${retiredSnapshotRows} row(s))`);
+        }
+        if (seatColumnPresent) {
+            await execUntil(db, `ALTER TABLE checkpoint DROP COLUMN ${RETIRED_STEER_SEAT_COLUMN}`, async () => !(await columnExists(db, dialect, "checkpoint", RETIRED_STEER_SEAT_COLUMN)));
+            retiredSteerSeatColumn = "dropped";
+            destroyed.push(`dropped column checkpoint.${RETIRED_STEER_SEAT_COLUMN}`);
+        }
+    }
+    catch (e) {
+        if (destroyed.length === 0)
+            throw e;
+        throw new Error(`one-time migration failed AFTER completing destructive steps — record these before retrying, a retry cannot ` +
+            `report them again: ${destroyed.join("; ")}. Underlying failure: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    return { retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, askOriginRowsMigrated };
+}
+export function migrateRetiredAskOrigin(type, data) {
+    if (type !== GATE_BEARING_LEDGER_EVENT_TYPE)
+        return undefined;
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return undefined;
+    const d = data;
+    const gate = d.gate;
+    if (gate === null || typeof gate !== "object" || Array.isArray(gate))
+        return undefined;
+    const g = gate;
+    if (g.origin !== RETIRED_ASK_ORIGIN.from)
+        return undefined;
+    return { ...d, gate: { ...g, origin: RETIRED_ASK_ORIGIN.to } };
+}
+export function logOneTimeMigrations(log, backend, report) {
+    const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0;
+    (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
+        backend,
+        retiredSnapshotTable: report.retiredSnapshotTable,
+        retiredSnapshotRows: report.retiredSnapshotRows,
+        retiredSteerSeatColumn: report.retiredSteerSeatColumn,
+        askOriginRowsMigrated: report.askOriginRowsMigrated,
+        note: "one-time persisted-data migrations for this version's retirements (retired whole-tree snapshot index table " +
+            "dropped; retired single-seat steering column dropped; retired ask-origin spelling rewritten in place). This " +
+            "whole migration step is removed in the next minor — start this version at least once before upgrading past it.",
+    });
+}
+//# sourceMappingURL=one-time-migrations.js.map

package/dist/plugins/pg-pool.d.ts

@@ -69,6 +69,12 @@ export type PgPoolWarnSink = (msg: string, meta?: Record<string, unknown>) => vo
  *  `onIdleClientError` 缺省 console.warn(与本文件 `ensurePgSchema` 的既有告警姿势一致)——生产
  *  装配(store-backend `createStoreBackend`)递结构化 logger 的 warn 座。 */
 export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientError?: PgPoolWarnSink): pg.Pool;
+/** A fixed bigint key for the `pg_advisory_lock` that serializes the whole `ensurePgSchema` DDL run (see below).
+ *  Arbitrary constant; only its uniqueness within this app matters (advisory-lock keys are app-private).
+ *  Exported so **boot-time schema-shaped work outside this function** serializes against it under the SAME key —
+ *  one lock identity for the whole class (the one-time migration段 is the current user; it runs after ensure and
+ *  must not interleave with another replica's ensure). */
+export declare const ENSURE_SCHEMA_LOCK_KEY = 4906;
 /** Idempotent central schema apply (the PG twin of tidb-pool.ts ensureSchema): the run/checkpoint tables here +
  *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS, no cross-table FKs).
  *

package/dist/plugins/pg-pool.js

@@ -81,11 +81,10 @@ export const PG_SCHEMA_STATEMENTS = [
      terminal_at_ms BIGINT,
      gate_kind    VARCHAR(32) COLLATE "C",
      bound_input_hash VARCHAR(190) COLLATE "C",
-     -- pending_steer / pending_steer_queue / pending_steer_rev:队列化后的 durable steering(core 5.14.0
-     -- #147)。三列的语义、「为什么队列另起一列而不是覆盖旧列」(滚动升级窗里旧副本的无条件覆盖写)、
-     -- 48000 字节预算、以及「为什么另起一个整数 rev 列而不拿 JSON 旧值当 CAS 守卫」的完整由来见 MySQL
-     -- 孪生(tidb-pool.ts 同三列的行内注)。PG text 无长度上限,预算由 core 侧统一执法。
-     pending_steer TEXT COLLATE "C",
+     -- pending_steer_queue / pending_steer_rev:队列化后的 durable steering(core 5.14.0 #147)。两列的语义、
+     -- 退役的单座列 pending_steer 为何删列(以及存量库的一次性迁移与那条拒启臂)、48000 字节预算、
+     -- 以及「为什么另起一个整数 rev 列而不拿 JSON 旧值当 CAS 守卫」的完整由来见 MySQL 孪生
+     -- (tidb-pool.ts 同两列的行内注)。PG text 无长度上限,预算由 core 侧统一执法。
      pending_steer_queue TEXT COLLATE "C",
      pending_steer_rev BIGINT NOT NULL DEFAULT 0,
      risk_descriptor TEXT COLLATE "C",
@@ -155,14 +154,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (policy_key)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_session_policy_session ON session_policy (session_id)`,
-    `CREATE TABLE IF NOT EXISTS snapshot_manifest (
-     scope     VARCHAR(64) COLLATE "C"   NOT NULL,
-     snap_key  VARCHAR(64) COLLATE "C"   NOT NULL,
-     rel_path  VARCHAR(1024) COLLATE "C" NOT NULL,
-     blob_hash CHAR(64) COLLATE "C"      NOT NULL
-   )`,
-    `CREATE INDEX IF NOT EXISTS idx_snapshot_manifest_sk ON snapshot_manifest (scope, snap_key)`,
-    `CREATE INDEX IF NOT EXISTS idx_snapshot_manifest_blob ON snapshot_manifest (blob_hash)`,
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64) COLLATE "C"       PRIMARY KEY,
      byte_len   BIGINT         NOT NULL,
@@ -400,7 +391,7 @@ export function createPgPool(opts, onIdleClientError) {
     });
     return pool;
 }
-const ENSURE_SCHEMA_LOCK_KEY = 4906;
+export const ENSURE_SCHEMA_LOCK_KEY = 4906;
 export async function ensurePgSchema(pool) {
     const client = await pool.connect();
     let locked = false;

package/dist/plugins/retention-store-sql.js

@@ -377,7 +377,6 @@ export class SqlRetentionStore {
             ["approval_exemption", "session_id"],
             ["session_policy", "session_id"],
             ...(this.opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
-            ["snapshot_manifest", "scope"],
             ["file_history_tracked", "scope"],
             ["file_history_version", "scope"],
             ["file_history_boundary", "scope"],

package/dist/plugins/store-backend.d.ts

@@ -4,6 +4,7 @@ import type { SessionStore, SessionPolicyStore, FileHistoryStore, WorkflowJourna
 import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
+import { type OneTimeMigrationReport } from "./one-time-migrations.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -221,22 +222,17 @@ export interface StoreBackend {
      *  于是单机默认部署上 `memoryCapture:"off"` 两条 ingress 结构性不可达(B-085)。
      *  刻意仍不给 local 一个**内存** twin:内存形会在重启时把一条隐私记录静默丢掉(比文件三腿严格更差)。 */
     sessionCaptureRecords(): SessionCaptureRecordSource | undefined;
-    /** S-1 legacy-epoch discriminant (core `RunnerDeps.legacyRewindBoundaryProbe`): does the RETIRED whole-tree
-     *  snapshot epoch hold a boundary for (sessionId, entryId)? Reads the legacy `snapshot_manifest` table.
-     *  SQL backends only (local never had a whole-tree epoch table). Diagnostic input on the refusal path —
-     *  a probe that cannot tell answers undefined (reads exactly like an absent probe), never throws. */
-    legacyRewindBoundaryProbe?(query: {
-        sessionId: string;
-        entryId: string;
-    }): Promise<boolean | undefined>;
-    /** Retired-epoch byte hygiene: GC grace-passed orphan `snapshot_blob` rows/objects (rows the retention
-     *  lane's `snapshot_manifest` sweeps keep orphaning — without this leg their BYTES would outlive every
-     *  manifest reference forever, incl. MinIO objects). SQL backends only; reaper-driven. */
+    /** Retired-epoch byte hygiene: GC grace-passed orphan `snapshot_blob` rows/objects — the whole-tree snapshot
+     *  epoch is gone (its manifest index table retired with it), so EVERY row in that domain is an orphan and its
+     *  BYTES (incl. MinIO objects) would otherwise outlive the epoch forever. SQL backends only; reaper-driven. */
     legacySnapshotBlobSweep?(): Promise<number>;
-    /** Retired-epoch right-to-delete: drop the session's LEGACY `snapshot_manifest` rows on the online E21
-     *  purge (the retention lane already sweeps them on expiry — the two delete legs must converge on the
-     *  same row set; a user's DELETE must reach old-epoch data too). Bytes go via the async legacy sweep. */
-    legacySnapshotPurge?(sessionId: string): Promise<number>;
+    /** 🔴 **一次性迁移(随 7.75.0 连同 `one-time-migrations.ts` 一起从接口上删)** —— 本版三处退役落在
+     *  已写进库里的字节上,升一次级改完、兼容臂当场删干净(硬 breaking 纪律:持久数据面 = 响亮拒 +
+     *  一次性迁移,窗过即删,永不长期双读)。逐条语义、幂等与拒启臂见该模块头注。
+     *
+     *  **必选,不是 optional**:漏实装一支后端 = 那条车道的存量字节永远停在旧读法上,而读腿已经只认新的
+     *  ⇒ 必须是编译期错误,不是运行期的一次静默跳过。 */
+    runOneTimeMigrations(): Promise<OneTimeMigrationReport>;
     /** SVC-2 (core CORE-7) durable WorkflowJournalStore — the cross-replica resume journal for an LLM-authored workflow
      *  (RunWorkflowOptions.journalStore). REQUIRED on all backends (tidb/pg = durable twins; local = core's
      *  InMemoryWorkflowJournalStore, single-replica/in-process).

package/dist/plugins/store-backend.js

@@ -7,6 +7,7 @@ import { TiDBOutcomeLedger, PgOutcomeLedger } from "./outcome-ledger-sql.js";
 import { FileOutcomeSink } from "./file-outcome-sink.js";
 import { TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, TiDBWorkflowAgentSessionIndex, PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore, PgWorkflowAgentSessionIndex } from "./workflow-run-store-sql.js";
 import { FileRunStore, RunStoreStrictHydrateError } from "./file-run-store.js";
+import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
@@ -73,29 +74,8 @@ function legacyBlobBackend(config, dialect, pool) {
         ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
     }, { dialect, pool });
 }
-async function legacyProbeImpl(dialect, pool, query) {
-    try {
-        if (dialect === "tidb") {
-            const [rows] = await pool.query("SELECT 1 FROM snapshot_manifest WHERE scope = ? AND snap_key = ? LIMIT 1", [query.sessionId, query.entryId]);
-            return rows.length > 0;
-        }
-        const r = await pool.query("SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1", [query.sessionId, query.entryId]);
-        return r.rows.length > 0;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function legacyPurgeImpl(dialect, pool, sessionId) {
-    if (dialect === "tidb") {
-        const [r] = await pool.query("DELETE FROM snapshot_manifest WHERE scope = ?", [sessionId]);
-        return Number(r.affectedRows ?? 0);
-    }
-    const r = await pool.query("DELETE FROM snapshot_manifest WHERE scope = $1", [sessionId]);
-    return r.rowCount ?? 0;
-}
 async function legacySweepImpl(config, dialect, pool) {
-    const sql = "SELECT blob_hash FROM snapshot_blob WHERE blob_hash NOT IN (SELECT blob_hash FROM snapshot_manifest)";
+    const sql = "SELECT blob_hash FROM snapshot_blob";
     let orphans;
     if (dialect === "tidb") {
         const [rows] = await pool.query(sql);
@@ -140,9 +120,8 @@ class TiDBBackend {
     memoryOptOutGrant() { return new TiDBMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new TiDBSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
-    legacyRewindBoundaryProbe(query) { return legacyProbeImpl("tidb", this.pool, query); }
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "tidb", this.pool); }
-    legacySnapshotPurge(sessionId) { return legacyPurgeImpl("tidb", this.pool, sessionId); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("tidb", this.pool); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
     outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); }
@@ -188,9 +167,8 @@ class PgBackend {
     memoryOptOutGrant() { return new PgMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new PgSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
-    legacyRewindBoundaryProbe(query) { return legacyProbeImpl("pg", this.pool, query); }
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "pg", this.pool); }
-    legacySnapshotPurge(sessionId) { return legacyPurgeImpl("pg", this.pool, sessionId); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
     outcomeSink() { return new PgOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); }
@@ -269,6 +247,9 @@ class LocalBackend {
             : (plane) => fileSessionCaptureRecordStore(plane?.controlDir ?? ownControlDir);
     }
     async ensureSchema() { }
+    async runOneTimeMigrations() {
+        return { ...NO_SQL_MIGRATIONS, askOriginRowsMigrated: await this.runStore.migrateRetiredAskOriginRows() };
+    }
     async close() {
         await this.sessionStore.dispose();
         this.runStore.dispose();

package/dist/plugins/task-attachment-store.d.ts

@@ -2,8 +2,8 @@
  * TaskAttachmentStore —— D-1 通用文件上传的**独立附件 store**(clay 拍 2026-07-27:不复用 fileSnapshot
  * 的 content-addressed blob 面,新建)。TiDB/PG 双方言 + local 文件店(local-task-attachment-store.ts)。
  *
- * 为什么独立而不是骑 SqlBlobBackend/snapshot_blob:那套的引用追踪=「manifest 里没有的即 orphan」,
- * 附件不在任何 snapshot_manifest ⇒ 会被 sweepOrphanBlobs 在 1h grace 后误收。生命周期也不同:
+ * 为什么独立而不是骑 SqlBlobBackend/snapshot_blob:那套的引用追踪=「本域 manifest 里没有的即 orphan」,
+ * 附件不在任何一域的 manifest 里 ⇒ 会被孤儿扫在 1h grace 后误收。生命周期也不同:
  * snapshot blob 跟 session 的工作树;**附件跟 task/session 的绑定**(上传先行、提交时绑定、E21 随会话
  * 级联删、未绑定的按 TTL 收割)。
  *

package/dist/plugins/tidb-pool.js

@@ -222,20 +222,16 @@ export const SCHEMA_STATEMENTS = [
      -- D-1 TOCTOU binding guard is UNREACHABLE by the portal without it — it can then only do the unbound legacy
      -- fallback). NULL on PRE-D-1 rows ⇒ that unbound fallback.
      bound_input_hash VARCHAR(190) NULL,
-     -- pending_steer (design/80 D-A, durable steering):**队列化之前**的单座列,存 {text,trusted}。
-     -- core 5.14.0(#147 BREAKING)之后本服务**只读不写**它:存量行的那一座由 core readPendingSteerQueue
-     -- 折成 member 0,零迁移。NULL = 没有旧座。Never touches status/resolve (design/80 inv #4)。
-     pending_steer TEXT         NULL,
-     -- pending_steer_queue:core 5.14.0(#147)的**有界有序队列**(PendingSteerEntry[] 的 JSON)。
-     -- 为什么队列另起一列、而不是把信封写回 pending_steer(codex 复审 2026-08-06 F3,采纳):滚动升级/
-     -- 回滚窗里旧副本仍在跑,它对 pending_steer 是**无条件覆盖**写 —— 队列若躺在同一列,旧副本接的下一条
-     -- steer 会把 5.14 排好的整队悄悄抹掉,正是 #147 要消灭的那种静默丢失换了个位置复发。分列之后:
-     -- 旧副本写它的单座 ⇒ 落 pending_steer,新读侧把它折成 member 0,**两边都活着**;旧副本读不到队列
-     -- 是 core 自己已披露的回滚代价(CHANGELOG:rolling back across the queue event loses steers),
-     -- 那半无法在店面消除,但**写侧互相清零**这半可以,且代价只是一个可空列。
-     -- 容量:core 的 PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES = 48000 字节是对 {pendingSteer,queue} 整信封的
-     -- 硬上界(越界 fail-loud steering.queue_full,绝不驱逐)⇒ 本列恒小于它,MySQL TEXT 的 65535 字节
-     -- 够用,**不升 LONGTEXT**(core 常量注里点名「under a MySQL TEXT column with UTF-8 headroom」)。
+     -- 🔴 队列化之前的**单座**列 pending_steer 已**退役删列**:那个席位在引擎侧没了(core 7.17.0 #717 d
+     -- 对带席的行 PRE-CAS 拒 seat_retired),留着一列没人读、没人写的字节只会让下一个人以为还有两种读法。
+     -- 存量库由启动期的一次性迁移处置(plugins/one-time-migrations.ts,随 7.75.0 删):列上还有非空值 ⇒
+     -- **响亮拒启**并给出两条出路(回 7.16.0 把那些 checkpoint resume 一次让座位排空 / 运维手工清列),
+     -- 清空之后 DROP COLUMN。刻意**不**自动把裸单座折进队列:那等于本仓替引擎铸一条它从没写过的队列条目。
+     -- pending_steer_queue:core 5.14.0(#147)的**有界有序队列**(PendingSteerEntry[] 的 JSON),现在是本表上
+     -- durable steering 的唯一载体。Never touches status/resolve (design/80 inv #4)。
+     -- 容量:core 的 PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES = 48000 字节是整信封的硬上界(越界 fail-loud
+     -- steering.queue_full,绝不驱逐)⇒ 本列恒小于它,MySQL TEXT 的 65535 字节够用,**不升 LONGTEXT**
+     -- (core 常量注里点名「under a MySQL TEXT column with UTF-8 headroom」)。
      pending_steer_queue TEXT   NULL,
      -- pending_steer_rev:pending_steer_queue 列**自己**的乐观锁计数(与 resolve/reopen 的 rev 是两个轴,
      -- 刻意不复用)。队列化之后 setPendingSteer 从「一条无条件 UPDATE」变成「读-改-写」,中间那道窗必须
@@ -332,14 +328,6 @@ export const SCHEMA_STATEMENTS = [
      updated_at DATETIME(3)  NOT NULL,
      PRIMARY KEY (policy_key),
      KEY idx_session_policy_session (session_id)
-   ) COLLATE utf8mb4_bin`,
-    `CREATE TABLE IF NOT EXISTS snapshot_manifest (
-     scope     VARCHAR(64)   NOT NULL,
-     snap_key  VARCHAR(64)   NOT NULL,
-     rel_path  VARCHAR(1024) NOT NULL,
-     blob_hash CHAR(64)      NOT NULL,
-     KEY idx_snapshot_manifest_sk (scope, snap_key),
-     KEY idx_snapshot_manifest_blob (blob_hash)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64)    NOT NULL,
@@ -348,7 +336,7 @@ export const SCHEMA_STATEMENTS = [
      -- comment above; this column is where it is enforced). It was originally LONGBLOB NOT NULL back when the
      -- SQL store was the ONLY blob backend; the MinIO offload then required an INDEX-ONLY row here (bytes NULL,
      -- the bytes living in MinIO) so that gcOrphanBlobs / reap / deleteBySession (E21 purge) / sweepOrphanBlobs
-     -- keep computing the orphan/grace SET from snapshot_blob for BOTH backends identically — and so an E21 purge
+     -- keep computing the grace SET from snapshot_blob for BOTH backends identically — and so an E21 purge
      -- can DELETE the MinIO object instead of leaking it. Re-adding NOT NULL here would silently break MinIO-mode
      -- reference tracking. See blob-backend.ts MinioBlobBackend.
      bytes      LONGBLOB    NULL,

package/dist/plugins/workflow-run-store-sql.d.ts

@@ -85,6 +85,15 @@ export declare function withRedactedError<T extends {
  *  里找不到那一行 ⇒ 落 legacy 腿拿一个**错因**的 409 `conflict.resume_context_unavailable`,人的批准无处兑付;
  *  同时 core resume 路径上那道「blob 里 parked 而 journal 缺条目 ⇒ 拒 resume」的防线(`prior.agents`)也随之失明。
  *
+ *  🔴 **7.74.0(core 7.17.0 [ref] 义务②):`parks[]` 排在恢复身份之上 —— 一级都不裁。**
+ *  它不是观测位,是**下一次 resume 的准入输入**:core 的 resume 准入在任何 agent 被派发之前读记录上的
+ *  这一位,读不到就整条拒(`workflow.park_truth_unreadable` / `parks_unreadable`)——不是「少一条 park」,
+ *  是**这条 run 再也 resume 不了**。所以阶梯的判据现在是两条,按这个次序:①`parks` 永不放弃;
+ *  ②恢复身份行最后放弃。实现上五级全部走 `{...上一级}` 展开、没有任何一级点名裁它,机器背书 =
+ *  `test/slim-oversize-run.test.ts` 里那两格(最狠的 step 5 上 `parks` 仍逐字完整 + 负控:记录本来没有
+ *  这一位时不许凭空补 `[]`)。缺席 ⇒ 不补:补 `[]` 会把「这版引擎没写这个位」伪造成「这条 run 没有 park」,
+ *  而 core 对两者的处置相反。
+ *
  *  阶梯 = 一张**按价值排序的放弃清单**,一级一级试到装得下为止(**判据只有一条:恢复身份最后放弃**):
  *    step 1 —— 两个无界字符串(`result` / `error`)截断带标记;
  *    step 2 —— `phases` / `groups` 整段丢,`agents` 收敛成**恢复身份行**

package/dist/task-cwd.d.ts

@@ -5,7 +5,18 @@ export declare const MAX_CWD_CHARS = 4096;
  *  over-long, and NUL-byte injection. NOT an existence check (the env surfaces a missing dir at first tool use).
  *  Defense-in-depth (double-review LOW): `path.isAbsolute` is SYNTACTIC — `/a/../../etc` is "absolute" yet contains
  *  `..` traversal that the host env would `path.resolve` away. Single-user host lane = the caller's own machine (no
- *  cross-tenant escape), but we reject any path with a `..` segment so the honored cwd is the literal path sent. */
+ *  cross-tenant escape), but we reject any path with a `..` segment so the honored cwd is the literal path sent.
+ *
+ *  🔴 **接缝登记(7.74.0 / core 7.17.0 [ref],今日无可达分歧 —— 登记的是「以后会分歧」)**:这条判断回答的是
+ *  「引擎眼里这条 cwd 算不算绝对」,而引擎自本版起按**树的家族**判(`isAbsoluteForFamily(pathFamilyOf({root,cwd}), p)`,
+ *  家族从 root/cwd 的**拼法**读,**从不**读 `process.platform`)。本函数用的是 Node 的宿主口径,两者:
+ *   · **posix 家族逐字同判**(2026-09-12 实测六形 `/etc/passwd` / `a/b` / `\\host\share\x` / `C:\x` /
+ *     `//host/share/x` / `/c/x` 六格全同)⇒ 今天(Linux 宿主 + posix 树,本位又只在单用户 `host` 车道上场)
+ *     **零分歧**,不改;
+ *   · **win 家族分歧在 `/`-开头但没有盘符的那一类**(`/etc/passwd`、`/c/x`):Node 的 win32 口径说「绝对」,
+ *     引擎说「rooted 但未完全限定」(要拼上基准的盘/共享根才成一条真路径)。⇒ **哪天 `host` 车道要接 win 树,
+ *     先改这里**:把判据换成 core 的 `isAbsoluteForFamily`,并把家族从这条 cwd 自己的拼法取。
+ *  钉见 `test/task-cwd.test.ts` 的「[ref] 路径家族接缝」格(实测读数,不是推断)。 */
 export declare function isValidCwd(cwd: unknown): cwd is string;
 /**
  * The deployment-level gate: does THIS deployment honor a caller-supplied `cwd`? TRUE only for the single-user

package/dist/task-settings.d.ts

@@ -344,6 +344,12 @@ export interface FsWriteGateWiring {
      *  to confine the exemption to POSIX-absolute canonical keys — core's `canonicalizeTarget` short-circuits
      *  backslash-UNC forms to `ok:true, key=raw` WITHOUT consulting the env, and an unconfined name-keyed grant
      *  would turn those unresolvable forms into an allow (codex review 2026-08-05).
+     *  🔴 **坐标刷新(7.74.0 / core 7.17.0 [ref];结论不变,前提收窄了)**:那条短路现在**只在 `win` 家族上**
+     *  (`dist/tools/fs/safety.js` 的 `canonicalizeTarget`:`family === "win" && isUncSpelling(...)` 才折 UNC
+     *  并直接返回);在 `posix` 家族上,同一个反斜杠 UNC 拼法在更早一步的 `win32NamespaceScreen` 上就被
+     *  **拒**(`unc_on_posix_tree`),压根到不了短路。⇒ 今日部署形(posix 树)这条腿的暴露面比当年更小,
+     *  而本臂的 POSIX-absolute 收敛**继续是对的**:它挡的是「未经 env 解析的 key 拿到 name-keyed 放行」,
+     *  在两个家族上都成立,且方向仍是 fail-closed。不改实现。
      *  The probe is consulted by the gate RIGHT BEFORE it would ask (after the exempt/accept dir layering — dist 亲读:true ⇒
      *  allow with decisionReason "rule", a THROWN probe ⇒ not exempt = fail-closed to ask). Same canonical
      *  toolName key space as the ask-policy layer's exemption probe — ONE grant serves both layers; the gate-level

package/dist/trace/core-keyset-guard.d.ts

@@ -148,10 +148,16 @@ type _GuardSettlementReverse = AssertAllKeysHandled<Exclude<SettlementProjected,
 type SettlementWhoProjected = "party" | "approver" | "window";
 type _GuardSettlementWho = AssertAllKeysHandled<Exclude<SettlementWhoKeys, SettlementWhoProjected>>;
 type _GuardSettlementWhoReverse = AssertAllKeysHandled<Exclude<SettlementWhoProjected, SettlementWhoKeys>>;
-type WorkflowRunForwarded = "id" | "scope" | "status" | "startedAt" | "endedAt" | "createdAt" | "rev" | "name" | "description" | "result" | "error" | "errorCode" | "agentFailures" | "stats" | "phases" | "agents" | "groups";
+type WorkflowRunForwarded = "id" | "scope" | "status" | "startedAt" | "endedAt" | "createdAt" | "rev" | "parks" | "name" | "description" | "result" | "error" | "errorCode" | "agentFailures" | "stats" | "phases" | "agents" | "groups";
 type WorkflowRunStripped = "sourceTaskId" | "originatingSessionId" | "effectiveArgs" | "budgetOvershoot" | "timeoutInterruption" | "resultFull" | "completionId" | "resume" | "journalSkips";
 type _GuardWorkflowRun = AssertAllKeysHandled<Exclude<keyof WorkflowRun, WorkflowRunForwarded | WorkflowRunStripped>>;
 type _GuardWorkflowRunReverse = AssertAllKeysHandled<Exclude<WorkflowRunForwarded | WorkflowRunStripped, keyof WorkflowRun>>;
+type ParkRowKeys = keyof NonNullable<WorkflowRun["parks"]>[number];
+type ParkRowProjected = "callKey" | "sessionId" | "originRunId";
+type ParkRowWithheld = "token";
+type _GuardParkRow = AssertAllKeysHandled<Exclude<ParkRowKeys, ParkRowProjected | ParkRowWithheld>>;
+type _NoDoubleBookParkRow = AssertAllKeysHandled<Extract<ParkRowProjected, ParkRowWithheld>>;
+type _GuardParkRowReverse = AssertAllKeysHandled<Exclude<ParkRowProjected | ParkRowWithheld, ParkRowKeys>>;
 export type CoreKeysetGuards = [
     _GuardNotification,
     _GuardNotificationReverse,
@@ -223,7 +229,10 @@ export type CoreKeysetGuards = [
     _GuardSettlementWho,
     _GuardSettlementWhoReverse,
     _GuardWorkflowRun,
-    _GuardWorkflowRunReverse
+    _GuardWorkflowRunReverse,
+    _GuardParkRow,
+    _NoDoubleBookParkRow,
+    _GuardParkRowReverse
 ];
 export {};
 //# sourceMappingURL=core-keyset-guard.d.ts.map