@sema-agent/server 7.103.1 → 7.104.0

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

@@ -1,12 +1,76 @@
 import { acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
 import { acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
 import { jsonColumnTextExpr } from "./sql-json-column.js";
+import { SESSION_META_INCARNATION_COLUMN, mintSessionIncarnation } from "../session-incarnation.js";
+export const ONE_TIME_MIGRATIONS = [
+    {
+        id: "M1",
+        introducedIn: "7.74.0",
+        releasedOn: "2026-09-13",
+        removableAfter: "2026-10-13",
+        removal: "删 migrateOn 的 M1 步(`snapshot_manifest` 在场探针、删前计数、`DROP TABLE`)与 `RETIRED_SNAPSHOT_TABLE`;报告、日志行与 " +
+            "`NO_SQL_MIGRATIONS` 的 `retiredSnapshotTable` / `retiredSnapshotRows`;与 M2 / M3 同一次删(见本表头注)",
+        afterRemoval: "没有响亮臂:存量库里的 `snapshot_manifest` 成一张无人读写的孤儿表 —— 它的读腿(边界探针)已随 core 7.17.0 的 seam 退役删掉," +
+            "起服列册探针 `schema-consistency.ts` 只对账代码认识的表。只有从 7.73.x 及更早直接跳到删码版的库会遇到;不影响任何读腿," +
+            "运维可手工 `DROP TABLE snapshot_manifest`",
+        reportKeys: ["retiredSnapshotTable", "retiredSnapshotRows"],
+    },
+    {
+        id: "M2",
+        introducedIn: "7.74.0",
+        releasedOn: "2026-09-13",
+        removableAfter: "2026-10-13",
+        removal: "删 migrateOn 的 M2 拒启臂与 `DROP COLUMN` 步、`RETIRED_STEER_SEAT_COLUMN`、`DELIVERABLE_STEER_SEAT_WHERE`、`RetiredSteerSeatError`;" +
+            "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `retiredSteerSeatColumn` / `retiredSteerSeatStaleRows`;与 M1 / M3 同一次删",
+        afterRemoval: "起服列册探针 `schema-consistency.ts`(S-547)的多列臂:存量库的 `checkpoint.pending_steer` 是代码不认识的列 ⇒ 拒启 " +
+            "`config.schema_mismatch`(响亮;⚠️ 那一臂的句子说「库比代码新」,对这一形方向说反了)。运维照拒句手工删列时,列上还送得出去的 " +
+            "steering 指令随之丢失 —— 删码之后没有任何东西再替它数一遍送得出去的格",
+        reportKeys: ["retiredSteerSeatColumn", "retiredSteerSeatStaleRows"],
+    },
+    {
+        id: "M3",
+        introducedIn: "7.74.0",
+        releasedOn: "2026-09-13",
+        removableAfter: "2026-10-13",
+        removal: "删 migrateOn 的 M3 两条整表 `UPDATE` 与它的「退役 schema 还在」跳过标记、`RETIRED_ASK_ORIGIN`、`GATE_BEARING_LEDGER_EVENT_TYPE`、" +
+            "`migrateRetiredAskOrigin`,以及 local 腿(`FileRunStore.migrateRetiredAskOriginRows` 与 `LocalBackend.runOneTimeMigrations` 里那一格);" +
+            "报告与日志行的 `askOriginRowsMigrated`;与 M1 / M2 同一次删",
+        afterRemoval: "读腿既有的 `server.trace.gate-outcome-defective`(`trace/project.ts` 的 `screenedGate`):残留旧拼法的 gate 与任何集外词同判 —— " +
+            "整条 withhold + 计数 + 一次 warn(与头注「M3 够不到的一格」同一条臂)",
+        reportKeys: ["askOriginRowsMigrated"],
+    },
+    {
+        id: "M4",
+        introducedIn: "7.93.5",
+        releasedOn: "2026-09-21",
+        removableAfter: "2026-10-21",
+        removal: "删 migrateOn 的 M4 步(`device_audit` 在场探针 + `UPDATE … SET detail = NULL`)与 `AUDIT_TABLE` / `AUDIT_DETAIL_COLUMN`;" +
+            "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `auditDetailJsonNullRows`;它若是表里最后一条,按头注「窗」一节整个文件一起删",
+        afterRemoval: "`device-store-sql.ts` `listAudit` 的读形拒(S-550:一行读不出形 ⇒ 整页拒,刻意不逐行隔离):含一行 JSON 文本 `null` 的那一页" +
+            "读不出来,拒句点名行 id —— 响亮,但那一页会一直读不出来,直到运维手工把那些行的 `detail` 置成 SQL NULL",
+        reportKeys: ["auditDetailJsonNullRows"],
+    },
+    {
+        id: "M5",
+        introducedIn: "7.104.0",
+        releasedOn: "2026-09-28",
+        removableAfter: "2026-10-28",
+        removal: "删 migrateOn 的 M5 步(`session_meta` 在场探针、`incarnation` 列在场探针 + `ADD COLUMN`、空化身回填循环)与 `backfillSessionIncarnations`;" +
+            "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `sessionIncarnationColumn` / `sessionIncarnationsBackfilled`;**列本身留在中央 DDL 里**(它不是迁移的一部分)",
+        afterRemoval: "① 列不在的存量库:起服列册探针 `schema-consistency.ts`(S-547)的缺列臂拒启 `config.schema_mismatch`,拒句里的 `ALTER TABLE … ADD COLUMN` " +
+            "由同一份 DDL 生成(响亮);② 列在但行上仍是空化身(跳过了带 M5 的版本直接升):会话店读口 `sessionFaceOf` 对那一行响亮拒 " +
+            "`session.incarnation_missing`(parked 决定腿因此拒、记忆座退回按 id 绑定并 warn)—— 运维手工给那些行填一只随机令牌即可",
+        reportKeys: ["sessionIncarnationColumn", "sessionIncarnationsBackfilled"],
+    },
+];
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
     retiredSteerSeatStaleRows: 0,
     retiredSteerSeatColumn: "absent",
     auditDetailJsonNullRows: 0,
+    sessionIncarnationColumn: "lazy-on-read",
+    sessionIncarnationsBackfilled: 0,
 };
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
@@ -37,24 +101,24 @@ export class RetiredSteerSeatError extends Error {
 }
 function mysqlDb(conn) {
     return {
-        async rows(sql) {
-            const [rows] = await conn.query(sql);
+        async rows(sql, params) {
+            const [rows] = params === undefined ? await conn.query(sql) : await conn.query(sql, [...params]);
             return rows;
         },
-        async exec(sql) {
-            const [r] = await conn.query(sql);
+        async exec(sql, params) {
+            const [r] = params === undefined ? await conn.query(sql) : await conn.query(sql, [...params]);
             return Number(r.affectedRows ?? 0);
         },
     };
 }
 function pgDb(client) {
     return {
-        async rows(sql) {
-            const r = await client.query(sql);
+        async rows(sql, params) {
+            const r = params === undefined ? await client.query(sql) : await client.query(sql, [...params]);
             return r.rows;
         },
-        async exec(sql) {
-            const r = await client.query(sql);
+        async exec(sql, params) {
+            const r = params === undefined ? await client.query(sql) : await client.query(sql, [...params]);
             return r.rowCount ?? 0;
         },
     };
@@ -139,6 +203,7 @@ async function migrateOn(db, dialect) {
         ? 0
         : await db.exec(`UPDATE ${AUDIT_TABLE} SET ${AUDIT_DETAIL_COLUMN} = NULL ` +
             `WHERE ${AUDIT_DETAIL_COLUMN} IS NOT NULL AND ${jsonColumnTextExpr(dialect, AUDIT_DETAIL_COLUMN)} = 'null'`);
+    const { sessionIncarnationColumn, sessionIncarnationsBackfilled } = await migrateSessionIncarnations(db, dialect);
     let retiredSnapshotTable = "absent";
     let retiredSnapshotRows = 0;
     let retiredSteerSeatColumn = "absent";
@@ -169,7 +234,64 @@ async function migrateOn(db, dialect) {
         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, retiredSteerSeatStaleRows, askOriginRowsMigrated, auditDetailJsonNullRows };
+    return {
+        retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated, auditDetailJsonNullRows,
+        sessionIncarnationColumn, sessionIncarnationsBackfilled,
+    };
+}
+const INCARNATION_BACKFILL_BATCH = 500;
+async function migrateSessionIncarnations(db, dialect) {
+    if (!(await tableExists(db, dialect, "session_meta")))
+        return { sessionIncarnationColumn: "no-table", sessionIncarnationsBackfilled: 0 };
+    const col = SESSION_META_INCARNATION_COLUMN;
+    let sessionIncarnationColumn = "present";
+    if (!(await columnExists(db, dialect, "session_meta", col.name))) {
+        try {
+            await db.exec(`ALTER TABLE session_meta ADD COLUMN ${dialect === "tidb" ? col.tidb : col.pg}`);
+            sessionIncarnationColumn = "added";
+        }
+        catch (e) {
+            if (!(await columnExists(db, dialect, "session_meta", col.name)))
+                throw e;
+        }
+    }
+    return { sessionIncarnationColumn, sessionIncarnationsBackfilled: await backfillSessionIncarnations(db, dialect) };
+}
+async function backfillSessionIncarnations(db, dialect) {
+    const remaining = async () => Number((await db.rows("SELECT COUNT(*) AS n FROM session_meta WHERE incarnation = ''"))[0]?.n ?? 0);
+    const initial = await remaining();
+    if (initial === 0)
+        return 0;
+    const ceiling = Math.ceil(initial / INCARNATION_BACKFILL_BATCH) * 2 + 2;
+    let written = 0;
+    let after;
+    for (let round = 0; round < ceiling; round++) {
+        const ids = (after === undefined
+            ? await db.rows(`SELECT session_id FROM session_meta WHERE incarnation = '' ORDER BY session_id LIMIT ${INCARNATION_BACKFILL_BATCH}`)
+            : await db.rows(`SELECT session_id FROM session_meta WHERE incarnation = '' AND session_id > ${dialect === "pg" ? "$1" : "?"} ORDER BY session_id LIMIT ${INCARNATION_BACKFILL_BATCH}`, [after])).map((r) => String(r.session_id));
+        if (ids.length === 0) {
+            if (after === undefined)
+                return written;
+            after = undefined;
+            continue;
+        }
+        const params = [];
+        const bind = (v) => {
+            params.push(v);
+            return dialect === "pg" ? `$${params.length}` : "?";
+        };
+        const cases = ids.map((id) => `WHEN ${bind(id)} THEN ${bind(mintSessionIncarnation())}`).join(" ");
+        const inList = ids.map((id) => bind(id)).join(", ");
+        written += await db.exec(`UPDATE session_meta SET incarnation = CASE session_id ${cases} END WHERE incarnation = '' AND session_id IN (${inList})`, params);
+        after = ids.length < INCARNATION_BACKFILL_BATCH ? undefined : ids[ids.length - 1];
+    }
+    const left = await remaining();
+    if (left > 0) {
+        throw new Error(`one-time migration M5: ${left} session_meta row(s) still carry an empty incarnation after ${ceiling} backfill round(s) ` +
+            `(${written} written) — refusing to start rather than serve sessions whose occupant cannot be told apart. Retry the boot; ` +
+            `if it repeats, something keeps writing rows without an incarnation (an older replica still inserting?).`);
+    }
+    return written;
 }
 export function migrateRetiredAskOrigin(type, data) {
     if (type !== GATE_BEARING_LEDGER_EVENT_TYPE)
@@ -186,7 +308,8 @@ export function migrateRetiredAskOrigin(type, data) {
     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 || report.auditDetailJsonNullRows > 0;
+    const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0 || report.auditDetailJsonNullRows > 0 ||
+        report.sessionIncarnationColumn === "added" || report.sessionIncarnationsBackfilled > 0;
     (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
         backend,
         retiredSnapshotTable: report.retiredSnapshotTable,
@@ -195,11 +318,16 @@ export function logOneTimeMigrations(log, backend, report) {
         retiredSteerSeatStaleRows: report.retiredSteerSeatStaleRows,
         askOriginRowsMigrated: report.askOriginRowsMigrated,
         auditDetailJsonNullRows: report.auditDetailJsonNullRows,
-        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; audit " +
-            "details written as the JSON text `null` by an earlier version folded to a SQL NULL, so \"no detail\" has exactly " +
-            "one on-disk spelling). This " +
-            "whole migration step is removed in the next minor — start this version at least once before upgrading past it.",
+        sessionIncarnationColumn: report.sessionIncarnationColumn,
+        sessionIncarnationsBackfilled: report.sessionIncarnationsBackfilled,
+        removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
+        note: "one-time persisted-data migrations (M1: retired whole-tree snapshot index table dropped; M2: retired single-seat " +
+            "steering column dropped; M3: retired ask-origin spelling rewritten in place; M4: audit details written as the JSON " +
+            "text `null` by an earlier version folded to a SQL NULL, so \"no detail\" has exactly one on-disk spelling; M5: the " +
+            "session incarnation column added and every session row without one minted its own token). Each step " +
+            "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
+            "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
+            "version that still carries a step at least once before upgrading past its deletion.",
     });
 }
 //# sourceMappingURL=one-time-migrations.js.map

package/dist/plugins/permission-rule-store-file.d.ts

@@ -1,6 +1,7 @@
 import { FileDurableRulePartitionProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type StaleRuleApprovalRecord } from "@sema-agent/core";
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
+import type { Logger } from "../observability/logger.js";
 import { type RuleCandidate } from "@sema-agent/core";
 /**
  * `RuleApprovalRecordStore` 的 File 形。
@@ -11,8 +12,10 @@ import { type RuleCandidate } from "@sema-agent/core";
 export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordStore {
     private readonly rows;
     private readonly log;
+    /** 本面的损坏闸(S-582 起由重放属主交回;置位后每个方法第一行响亮拒)。 */
     private readonly gate;
-    constructor(dir: string, onError?: (message: string) => void);
+    /** @param warn 腐读披露座(S-582;缺席 ⇒ 属主退回 `console.warn`)。 */
+    constructor(dir: string, warn?: Logger["warn"]);
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
     get corrupt(): boolean;
     /** 归还本面 eager 持有的日志描述符(束的 `dispose()` 唯一调用点)。`AppendLog` 上没有 finalizer,
@@ -39,10 +42,12 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
 export declare class FileRuleImportTicketStore {
     private readonly rows;
     private readonly log;
+    /** 本面的损坏闸(S-582 起由重放属主交回)。 */
     private readonly gate;
     /** 单调钟(判定用)。与 {@link now}(墙钟,记账用)是两只不同的钟,别混。 */
     private readonly monotonic;
-    constructor(dir: string, now?: () => number, onError?: (message: string) => void, monotonic?: () => number);
+    /** @param warn 腐读披露座(S-582;缺席 ⇒ 属主退回 `console.warn`)。 */
+    constructor(dir: string, now?: () => number, warn?: Logger["warn"], monotonic?: () => number);
     private readonly now;
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
     get corrupt(): boolean;
@@ -100,9 +105,11 @@ export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
  * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
  * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
  * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
+ * `warn`(S-582)接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ `console.warn`)。
  */
 export declare function createFilePermissionRuleStores(root: string, opts?: {
     onError?: (message: string) => void;
+    warn?: Logger["warn"];
     now?: () => number;
     monotonic?: () => number;
 }): FilePermissionRuleStores;

package/dist/plugins/permission-rule-store-file.js

@@ -2,10 +2,10 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readdirSync } from "node:fs";
 import { performance } from "node:perf_hooks";
-import { FileDurableRulePartitionProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
+import { FileDurableRulePartitionProvider, AppendLog, ensureDir, } from "@sema-agent/core";
 import { z } from "zod";
 import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
-import { createSkippedRecordSink } from "../observability/corrupt-read-seat.js";
+import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { RULE_BEHAVIORS } from "@sema-agent/core";
 const RuleScopeSchema = z.union([
@@ -109,53 +109,44 @@ const TicketLineSchema = z.union([
     z.object({ op: z.literal("settle"), ticketId: z.string().min(1), outcome: z.unknown() }).strict(),
 ]);
 const LEGACY_TICKET_PURPOSE = "cc-import";
-class CorruptionGate {
-    face;
-    path;
-    onError;
-    reason;
-    constructor(face, path, onError) {
-        this.face = face;
-        this.path = path;
-        this.onError = onError;
-    }
-    trip(reason) {
-        this.reason ??= reason;
-        this.onError?.(`${this.face} at ${this.path} is corrupt: ${reason}`);
-    }
-    get tripped() {
-        return this.reason !== undefined;
-    }
-    assertUsable() {
-        if (this.reason === undefined)
-            return;
-        throw new Error(`refusing to use a corrupt ${this.face} (${this.path}): ${this.reason} — ` +
-            "the permission-rule lane is fail-closed until a person inspects the file (moving it aside restarts the lane with an empty log)");
-    }
-}
+const APPROVAL_LOG_SHAPE = {
+    what: "permission-rule approval line that is neither a current-form put/discard nor a pre-form put",
+    read(record) {
+        const parsed = ApprovalLineSchema.safeParse(record);
+        if (parsed.success)
+            return { kind: "line", line: parsed.data };
+        const stale = StaleApprovalLineSchema.safeParse(record);
+        if (stale.success && stale.data.record.schema !== RULE_APPROVAL_RECORD_SCHEMA)
+            return { kind: "stale", envelope: toStaleEnvelope(stale.data.record) };
+        return undefined;
+    },
+};
+const TICKET_LOG_SHAPE = {
+    what: "permission-rule import-ticket line outside the mint/consume/release/settle shapes",
+    read(record) {
+        const parsed = TicketLineSchema.safeParse(record);
+        return parsed.success ? parsed.data : undefined;
+    },
+};
 export class FileRuleApprovalRecordStore {
     rows = new Map();
     log;
     gate;
-    constructor(dir, onError) {
+    constructor(dir, warn) {
         ensureDir(dir);
         const path = join(dir, "approvals.jsonl");
-        this.gate = new CorruptionGate("permission-rule approval log", path, onError);
-        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
-            const parsed = ApprovalLineSchema.safeParse(raw);
-            if (!parsed.success) {
-                const stale = StaleApprovalLineSchema.safeParse(raw);
-                if (stale.success && stale.data.record.schema !== RULE_APPROVAL_RECORD_SCHEMA) {
-                    this.rows.set(stale.data.record.id, toStaleEnvelope(stale.data.record));
-                    continue;
-                }
-                this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);
+        const { records, gate } = replayJsonlGuarded(path, "permission-rule-approvals", APPROVAL_LOG_SHAPE, warn);
+        this.gate = gate;
+        for (const entry of records) {
+            if (entry.kind === "stale") {
+                this.rows.set(entry.envelope.id, entry.envelope);
                 continue;
             }
-            if (parsed.data.op === "discard")
-                this.rows.delete(parsed.data.id);
+            const line = entry.line;
+            if (line.op === "discard")
+                this.rows.delete(line.id);
             else
-                this.rows.set(parsed.data.record.id, toApprovalRecord(parsed.data.record));
+                this.rows.set(line.record.id, toApprovalRecord(line.record));
         }
         this.log = new AppendLog(path);
     }
@@ -204,19 +195,14 @@ export class FileRuleImportTicketStore {
     log;
     gate;
     monotonic;
-    constructor(dir, now, onError, monotonic) {
+    constructor(dir, now, warn, monotonic) {
         this.now = now ?? Date.now;
         this.monotonic = monotonic ?? (() => performance.now());
         ensureDir(dir);
         const path = join(dir, "import-tickets.jsonl");
-        this.gate = new CorruptionGate("permission-rule import-ticket log", path, onError);
-        for (const raw of readJsonlRecords(path, createSkippedRecordSink((info) => this.gate.trip(info.reason)))) {
-            const parsed = TicketLineSchema.safeParse(raw);
-            if (!parsed.success) {
-                this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);
-                continue;
-            }
-            const line = parsed.data;
+        const { records, gate } = replayJsonlGuarded(path, "permission-rule-tickets", TICKET_LOG_SHAPE, warn);
+        this.gate = gate;
+        for (const line of records) {
             if (line.op === "mint") {
                 this.rows.set(line.ticketId, {
                     ownerKey: line.ownerKey,
@@ -344,8 +330,8 @@ export function createFilePermissionRuleStores(root, opts) {
     const dir = join(root, "permission-rules");
     ensureDir(dir);
     const durable = opts?.onError ? new FileDurableRulePartitionProvider(dir, opts.onError) : new FileDurableRulePartitionProvider(dir);
-    const approvals = new FileRuleApprovalRecordStore(dir, opts?.onError);
-    const tickets = new FileRuleImportTicketStore(dir, opts?.now, opts?.onError, opts?.monotonic);
+    const approvals = new FileRuleApprovalRecordStore(dir, opts?.warn);
+    const tickets = new FileRuleImportTicketStore(dir, opts?.now, opts?.warn, opts?.monotonic);
     return {
         durable,
         approvals,

package/dist/plugins/pg-session-storage.d.ts

@@ -4,6 +4,7 @@ import type { SessionSummary } from "./store-contracts.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import { type SessionFace } from "../session-incarnation.js";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
@@ -80,6 +81,8 @@ export declare class PgSessionStore implements SessionStore {
     }): Promise<PlacedSessionRow[]>;
     /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
+    /** S-790:属主 + 化身一次读(TiDB 孪生 {@link TiDBSessionStore.sessionFaceOf} 同义;空化身 ⇒ 响亮拒)。 */
+    sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
     touch(sessionId: string): Promise<void>;
     /** E18 — the session's current leaf SessionTreeEntry.id (session_meta.leaf_id). @see TiDBSessionStore.getLeafId
      *  (single SELECT, no acquire/lock, cache-bypassing — safe to read mid-run for the resume-at turn-capture). */

package/dist/plugins/pg-session-storage.js

@@ -11,6 +11,7 @@ import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "./ensure-index.js";
 const isDupKey = isPgUniqueViolation;
 function baselineQuery(text, values) {
@@ -40,6 +41,8 @@ export const PG_SESSION_SCHEMA = [
      placement_root_session_id   VARCHAR(190) COLLATE "C",
      placement_handle            VARCHAR(190) COLLATE "C",
      placed_at                   TIMESTAMPTZ(3),
+     -- S-790 / S-506:会话化身(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN)。
+     ${SESSION_META_INCARNATION_COLUMN.pg},
      PRIMARY KEY (session_id)
    )`,
     `CREATE TABLE IF NOT EXISTS session_event (
@@ -217,9 +220,9 @@ export class PgSessionStore {
     }
     async register(sessionId, owner, placement) {
         const now = new Date();
-        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, " +
+        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
-            "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, ...placementInsertValues(placement, now)]);
+            "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
     }
     async placementOf(sessionId) {
         const res = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
@@ -246,6 +249,12 @@ export class PgSessionStore {
             return undefined;
         return res.rows[0].owner ?? null;
     }
+    async sessionFaceOf(sessionId) {
+        const res = await this.pool.query("SELECT owner, incarnation FROM session_meta WHERE session_id = $1", [sessionId]);
+        if (res.rows.length === 0)
+            return undefined;
+        return sessionFaceFromRow(sessionId, res.rows[0].owner ?? null, res.rows[0].incarnation);
+    }
     async touch(sessionId) {
         await this.pool.query("UPDATE session_meta SET updated_at = $1 WHERE session_id = $2", [
             new Date(),
@@ -384,7 +393,7 @@ export class PgSessionStore {
                 const payload = String(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6)", [newId, owner, now, now, leafId, rows.length]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, owner, now, now, leafId, rows.length, mintSessionIncarnation()]);
             await conn.query("COMMIT");
             return newId;
         }
@@ -438,7 +447,7 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            await this.insertValidatedLog(conn, sessionId, owner, validated);
+            await this.insertValidatedLog(conn, sessionId, owner, validated, mintSessionIncarnation());
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -461,14 +470,14 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            const placedRes = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            const placedRes = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
             if (placedRes.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
                 throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placedRes.rows[0].placement_kind} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated);
+            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(placedRes.rows[0], owner));
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -485,7 +494,7 @@ export class PgSessionStore {
             conn.release();
         }
     }
-    async insertValidatedLog(conn, sessionId, owner, validated) {
+    async insertValidatedLog(conn, sessionId, owner, validated, incarnation) {
         let leafId = null;
         for (const e of validated)
             leafId = leafIdAfterEntry(e);
@@ -494,7 +503,7 @@ export class PgSessionStore {
             const e = validated[seq];
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [sessionId, seq, e.id, e.parentId ?? null, e.type, pgSafeJsonStringify(e), new Date(e.timestamp)]);
         }
-        await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6)", [sessionId, owner, now, now, leafId, validated.length]);
+        await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [sessionId, owner, now, now, leafId, validated.length, incarnation]);
     }
     beginImportStaging(realSessionId, token) {
         return new PgStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
@@ -614,8 +623,8 @@ class PgStagingHandle {
             if (lastRes.rows[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRes.rows[0].payload, this.realSessionId, "last staged row"));
             const now = new Date();
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6) " +
-                "ON CONFLICT (session_id) DO UPDATE SET owner = EXCLUDED.owner, updated_at = EXCLUDED.updated_at, leaf_id = EXCLUDED.leaf_id, leaf_seq = EXCLUDED.leaf_seq", [this.realSessionId, owner, now, now, leafId, srcIds.length]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7) " +
+                "ON CONFLICT (session_id) DO UPDATE SET owner = EXCLUDED.owner, updated_at = EXCLUDED.updated_at, leaf_id = EXCLUDED.leaf_id, leaf_seq = EXCLUDED.leaf_seq", [this.realSessionId, owner, now, now, leafId, srcIds.length, mintSessionIncarnation()]);
             const afterMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (afterMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");

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

@@ -83,10 +83,14 @@ export declare class SqlRunStore {
     /**
      * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
-     * terminal state or the reaper expires it. The token-bearing result is NOT stored (the submitter polling
-     * this row must never receive the capability token); only the status flips.
+     * terminal state or the reaper expires it.
+     *
+     * 🔴 S-173:park 也落 `result` 列 —— 存的是**摘掉恢复凭据、脱过敏的投影**(`sealRunRowResult`,与 `setTerminal`
+     * 同一只入口、同列同序列化),不是引擎交出的原件:`paused.token` / `failed.nestedPause.token` 两座在落列前摘掉,
+     * 所以 poll 这一行的调用方(`GET /v1/runs/:id → result`)拿到的是「停在哪扇门上」而拿不到 resume 能力。
+     * `result = null` = 这条腿没观察到 park 结果(断连竞态 / 重开 re-park),列写空 —— 与修前行形同。
      */
-    setSuspended(taskId: string): Promise<void>;
+    setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
     /**
      * [ref] D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
      * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
@@ -104,7 +108,7 @@ export declare class SqlRunStore {
      * mocked run-store unit tests stayed green. A mock cannot observe a unique-key claim race, a rolled-back loser,
      * or a multi-table reaper DELETE.
      */
-    setNeedsReview(taskId: string): Promise<void>;
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
     /**
      * Durable F4 resume: a suspended run is being actively resumed. Flip it back to `running` (CAS — only if
      * still suspended) and refresh liveness, so the in-flight resume is protected by the running-run heartbeat
@@ -288,6 +292,10 @@ export declare class SqlRunStore {
      * a NEW pending checkpoint — the `NOT EXISTS pending` clause excludes it. Idempotent across replicas. Returns count.
      *
      * Same alias-qualification divergence as {@link reapSuspended} — see its header note.
+     *
+     * S-173:两条收割腿都把 `result` 列写回 NULL —— park 行上那份 park 结果(`terminal.kind:"paused"`)说的是
+     * 「停在门上」,而这一刻行被打成 `failed`/`approval.expired`;留着它 = 一行两句互相矛盾的话(读面还会从它
+     * 投出 `review.pending` 之类的 park 码)。收割后的行形因此与 S-173 之前逐字同(结果空,码在 error_code 列)。
      */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
 }