@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/approval-nonce-store.js

@@ -1,20 +1,48 @@
 import { join } from "node:path";
 import { atomicWriteFile, ensureDir, AppendLog } from "@sema-agent/core";
-import { mysqlDriver, pgDriver, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
+import { createLogger } from "../observability/logger.js";
 export const APPROVAL_NONCE_TABLE = "approval_nonce";
 export const MAX_APPROVAL_NONCE_CHARS = 190;
+export const APPROVAL_NONCE_FLOOR_TABLE = "approval_nonce_floor";
+export const APPROVAL_NONCE_CLOCK_ROLLBACK_EVENT = "approval_nonce_clock_rollback";
+let seamLogger;
+const warnToLogSeam = (msg, fields) => (seamLogger ??= createLogger()).warn(msg, fields);
+function storeClockOf(rawMs, floorMs, store, warn) {
+    if (floorMs === undefined || rawMs >= floorMs)
+        return rawMs;
+    warn(APPROVAL_NONCE_CLOCK_ROLLBACK_EVENT, {
+        store,
+        rolledBackMs: floorMs - rawMs,
+        floorMs,
+        clockMs: rawMs,
+        note: "the approval-nonce store's clock reads below the line it already deleted consumption records under (the clock was stepped back: an NTP step, a failover to a lagging host, or another database node answering) — " +
+            "the store answers that line instead, so proofs that expired before it stay refused; check time sync on the database host (SQL backends) or on this host (local lane)",
+    });
+    return floorMs;
+}
 export class SqlApprovalNonceStore {
     db;
-    constructor(db) {
+    warn;
+    constructor(db, opts) {
         this.db = db;
+        this.warn = opts?.warn ?? warnToLogSeam;
     }
     q(mysql, pg) {
         return this.db.dialect === "mysql" ? mysql : pg;
     }
     async nowMs() {
-        return sqlDbNowMs(this.db, APPROVAL_NONCE_TABLE);
+        const { rows } = await this.db.query(this.q(`SELECT ${SQL_DB_NOW_MS.mysql} AS db_now_ms, (SELECT floor_ms FROM ${APPROVAL_NONCE_FLOOR_TABLE} WHERE singleton = 'x') AS floor_ms`, `SELECT ${SQL_DB_NOW_MS.pg} AS db_now_ms, (SELECT floor_ms FROM ${APPROVAL_NONCE_FLOOR_TABLE} WHERE singleton = 'x') AS floor_ms`), []);
+        const raw = Number(rows[0]?.["db_now_ms"] ?? Number.NaN);
+        if (!Number.isFinite(raw))
+            throw new Error(`${APPROVAL_NONCE_TABLE}: the database clock came back unreadable (${String(rows[0]?.["db_now_ms"])})`);
+        const floorCell = rows[0]?.["floor_ms"];
+        const floor = floorCell === null || floorCell === undefined ? undefined : Number(floorCell);
+        if (floor !== undefined && !Number.isFinite(floor))
+            throw new Error(`${APPROVAL_NONCE_FLOOR_TABLE}: the time floor came back unreadable (${String(floorCell)})`);
+        return storeClockOf(raw, floor, "sql", this.warn);
     }
     async consume(sessionId, nonce, expiresAtMs) {
         try {
@@ -28,25 +56,32 @@ export class SqlApprovalNonceStore {
         }
     }
     async reapExpired() {
-        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= ${SQL_DB_NOW_MS.mysql}`, `DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= ${SQL_DB_NOW_MS.pg}`), []);
+        const line = await this.nowMs();
+        await this.db.query(this.q(`INSERT INTO ${APPROVAL_NONCE_FLOOR_TABLE} (singleton, floor_ms) VALUES ('x', ?) ON DUPLICATE KEY UPDATE floor_ms = GREATEST(floor_ms, VALUES(floor_ms))`, `INSERT INTO ${APPROVAL_NONCE_FLOOR_TABLE} (singleton, floor_ms) VALUES ('x', $1) ON CONFLICT (singleton) DO UPDATE SET floor_ms = GREATEST(${APPROVAL_NONCE_FLOOR_TABLE}.floor_ms, EXCLUDED.floor_ms)`), [line]);
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= ?`, `DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= $1`), [line]);
         return res.affected;
     }
 }
 export class TiDBApprovalNonceStore extends SqlApprovalNonceStore {
-    constructor(pool) {
-        super(mysqlDriver(pool));
+    constructor(pool, opts) {
+        super(mysqlDriver(pool), opts);
     }
 }
 export class PgApprovalNonceStore extends SqlApprovalNonceStore {
-    constructor(pool) {
-        super(pgDriver(pool));
+    constructor(pool, opts) {
+        super(pgDriver(pool), opts);
     }
 }
 const keyOf = (sessionId, nonce) => JSON.stringify([sessionId, nonce]);
 export class MemoryApprovalNonceStore {
     rows = new Map();
+    floorMs;
+    warn;
+    constructor(opts) {
+        this.warn = opts?.warn ?? warnToLogSeam;
+    }
     async nowMs() {
-        return Date.now();
+        return storeClockOf(Date.now(), this.floorMs, "memory", this.warn);
     }
     async consume(sessionId, nonce, expiresAtMs) {
         const k = keyOf(sessionId, nonce);
@@ -56,10 +91,11 @@ export class MemoryApprovalNonceStore {
         return true;
     }
     async reapExpired() {
-        const now = await this.nowMs();
+        const line = await this.nowMs();
+        this.floorMs = this.floorMs === undefined ? line : Math.max(this.floorMs, line);
         let n = 0;
         for (const [k, exp] of this.rows) {
-            if (exp <= now) {
+            if (exp <= line) {
                 this.rows.delete(k);
                 n++;
             }
@@ -67,11 +103,15 @@ export class MemoryApprovalNonceStore {
         return n;
     }
 }
-const NONCE_RECORD_SHAPE = {
-    what: "approval-nonce record without a string s / string n / numeric e",
+const NONCE_LOG_LINE_SHAPE = {
+    what: "approval-nonce line that is neither a record (string s / string n / numeric e) nor a time floor (numeric f alone)",
     read(record) {
-        const { s, n, e } = record;
-        return typeof s === "string" && typeof n === "string" && typeof e === "number" ? { s, n, e } : undefined;
+        const { s, n, e, f } = record;
+        if (typeof s === "string" && typeof n === "string" && typeof e === "number")
+            return { s, n, e };
+        if (typeof f === "number" && s === undefined && n === undefined && e === undefined)
+            return { f };
+        return undefined;
     },
 };
 export class FileApprovalNonceStore {
@@ -80,22 +120,29 @@ export class FileApprovalNonceStore {
     rows = new Map();
     log;
     gate;
+    floorMs;
+    warn;
     constructor(root, opts) {
+        this.warn = opts?.warn ?? warnToLogSeam;
         const dir = join(root, "approval-nonces");
         ensureDir(dir);
         this.tmpDir = join(dir, ".tmp");
         ensureDir(this.tmpDir);
         this.path = join(dir, "consumed.jsonl");
-        const { records, gate } = replayJsonlGuarded(this.path, "approval-nonce", NONCE_RECORD_SHAPE, opts?.warn);
+        const { records, gate } = replayJsonlGuarded(this.path, "approval-nonce", NONCE_LOG_LINE_SHAPE, opts?.warn);
         this.gate = gate;
-        for (const r of records)
-            this.rows.set(keyOf(r.s, r.n), r);
+        for (const r of records) {
+            if ("f" in r)
+                this.floorMs = this.floorMs === undefined ? r.f : Math.max(this.floorMs, r.f);
+            else
+                this.rows.set(keyOf(r.s, r.n), r);
+        }
     }
     logFor() {
         return (this.log ??= new AppendLog(this.path));
     }
     async nowMs() {
-        return Date.now();
+        return storeClockOf(Date.now(), this.floorMs, "file", this.warn);
     }
     async consume(sessionId, nonce, expiresAtMs) {
         this.gate.assertUsable();
@@ -109,11 +156,11 @@ export class FileApprovalNonceStore {
     }
     async reapExpired() {
         this.gate.assertUsable();
-        const nowMs = await this.nowMs();
+        const line = await this.nowMs();
         const survivors = [];
         let removed = 0;
         for (const record of this.rows.values()) {
-            if (record.e <= nowMs) {
+            if (record.e <= line) {
                 removed++;
                 continue;
             }
@@ -122,9 +169,11 @@ export class FileApprovalNonceStore {
         if (removed === 0)
             return 0;
         this.log?.closeForSwap();
-        atomicWriteFile(this.tmpDir, this.path, survivors.map((r) => `${JSON.stringify(r)}\n`).join(""));
+        const floor = { f: this.floorMs === undefined ? line : Math.max(this.floorMs, line) };
+        atomicWriteFile(this.tmpDir, this.path, [floor, ...survivors].map((r) => `${JSON.stringify(r)}\n`).join(""));
+        this.floorMs = floor.f;
         for (const [k, record] of [...this.rows])
-            if (record.e <= nowMs)
+            if (record.e <= line)
                 this.rows.delete(k);
         return removed;
     }

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

@@ -57,6 +57,8 @@ export declare class MinioBlobBackend implements BlobBackend {
     private readonly cfg;
     private readonly keyPrefix;
     private readonly ttl;
+    /** 六个站点(put / get / delete / listObjects / headObject / probeBucket)的唯一出口:端点回重定向 ⇒ 拒,预签名 URL 与对象体不被带去 `Location`。 */
+    private readonly egressFetch;
     constructor(cfg: MinioBlobBackendConfig);
     private objectKey;
     private presign;

package/dist/plugins/blob-backend.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { isNoSuchBucketAnswer } from "./s3-answer.js";
+import { createEgressFetch } from "../egress-redirect.js";
 export async function readAtAddress(port, hash) {
     const bytes = await port.get(hash);
     if (bytes === undefined)
@@ -23,10 +24,12 @@ export class MinioBlobBackend {
     cfg;
     keyPrefix;
     ttl;
+    egressFetch;
     constructor(cfg) {
         this.cfg = cfg;
         this.keyPrefix = cfg.keyPrefix ?? "blobs/";
         this.ttl = cfg.presignTtlSec ?? 3600;
+        this.egressFetch = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", cfg.fetchImpl);
     }
     objectKey(key) {
         return `${this.keyPrefix}${key}`;
@@ -45,7 +48,7 @@ export class MinioBlobBackend {
     }
     async put(key, bytes) {
         const url = this.presign(key, "PUT");
-        const res = await (this.cfg.fetchImpl ?? fetch)(url, { method: "PUT", body: bytes, signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+        const res = await this.egressFetch(url, { method: "PUT", body: bytes, signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         if (!res.ok) {
             const detail = await res.text().catch(() => "");
             throw new Error(`MinioBlobBackend.put ${key}: HTTP ${res.status} ${detail.slice(0, 200)}`);
@@ -55,7 +58,7 @@ export class MinioBlobBackend {
         const url = this.presign(key, "GET");
         let res;
         try {
-            res = await (this.cfg.fetchImpl ?? fetch)(url, { method: "GET", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+            res = await this.egressFetch(url, { method: "GET", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         }
         catch (err) {
             throw new Error(`MinioBlobBackend.get ${key}: transient fetch failure: ${err.message}`);
@@ -74,7 +77,7 @@ export class MinioBlobBackend {
         let firstFailure;
         await mapBounded(distinct, MINIO_OP_CONCURRENCY, async (key) => {
             try {
-                const res = await (this.cfg.fetchImpl ?? fetch)(this.presign(key, "DELETE"), { method: "DELETE", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+                const res = await this.egressFetch(this.presign(key, "DELETE"), { method: "DELETE", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
                 if (res.ok || res.status === 404)
                     return;
                 failed++;
@@ -89,7 +92,7 @@ export class MinioBlobBackend {
             throw new Error(`MinioBlobBackend.delete: ${failed} of ${distinct.length} object(s) could not be deleted (first: ${firstFailure})`);
     }
     async *listObjects() {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         let token;
         const MAX_PAGES = 1000;
         let pages = 0;
@@ -127,7 +130,7 @@ export class MinioBlobBackend {
         } while (token !== undefined);
     }
     async headObject(hash) {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         const res = await f(this.presign(hash, "HEAD"), { method: "HEAD", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         if (!res.ok)
             return undefined;
@@ -136,7 +139,7 @@ export class MinioBlobBackend {
         return { lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
     }
     async probeBucket(timeoutMs = OBJECT_STORE_IO_TIMEOUT_MS) {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         const url = presignS3ListUrl({
             endpoint: this.cfg.endpoint,
             bucket: this.cfg.bucket,

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

@@ -1,9 +1,12 @@
 import { type AcquiredSession, type PlacedSessionRow, type RetentionDeclaration, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import type { LocalSessionDeletionSection } from "../session-erase.js";
 import type { OwnerAwareSessionStore, SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
+import type { SessionDeletionFace } from "../session-deletion.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import type { InstructionSourceStore } from "../instruction-source-notice.js";
 import type { SessionWorkspaceStore } from "../session-workspace.js";
+import { type SessionBirthFace, type SessionWithdrawFace } from "./session-birth.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
@@ -60,7 +63,13 @@ export declare class CachingSessionStore implements SessionStore {
      *  缓存的会话活得比「另一只店删掉又重建了这一行」长)。内层店必有(本类的暖命中按它核新鲜)。🔴 必须转发:生产默认把真店包进本类,授权口 / 属主门 /
      *  k8s 工作区空间 / SSE 探针 / resume-at 读的都是本类。 */
     readonly headOf: SessionHeadReader["headOf"];
+    /** 删除门的头读(`OwnerAwareSessionStore.deletionHeadOf`;local 店才交):**纯转发、不经暖缓存**(与 `headOf` 同理)。内层店不交 ⇒ 本类也不交(删除门读 `headOf`)。 */
+    readonly deletionHeadOf?: OwnerAwareSessionStore["deletionHeadOf"];
     readonly register?: (sessionId: string, owner: string | null) => Promise<void>;
+    /** 出生回执面(`session-birth.ts`;纯转发 —— 写的是持久行)。🔴 必须转发:授权口读的是本类,不转发 = 永远没有候选 = 永不撤回。 */
+    readonly registerWithReceipt?: SessionBirthFace["registerWithReceipt"];
+    /** 条件撤回面(`session-birth.ts`;转发后逐出暖缓存,与 `deleteSession` 同一条纪律)。 */
+    readonly withdrawBirth?: SessionWithdrawFace["withdrawBirth"];
     /** Delegated SessionRepo seam (§0.5) — list/fork/delete operate on the DURABLE tables directly (they bypass the
      *  warm cache by design; a fork/delete must read/write durable state, not a possibly-stale cached view). */
     readonly listSessions?: (opts: {
@@ -80,7 +89,10 @@ export declare class CachingSessionStore implements SessionStore {
     readonly forkTo?: OwnerAwareSessionStore["forkTo"];
     /** 执行席(原样转发:放置是会话**行**上的一格,缓存只缓存会话日志的暖句柄,不缓存行格 —— 读与写都直达内层店)。 */
     readonly executionPlacement?: OwnerAwareSessionStore["executionPlacement"];
-    readonly deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
+    /** 删净一只在删会话的 local 执行体锁节(转发后逐出暖缓存)。 */
+    readonly deleteSession?: LocalSessionDeletionSection;
+    /** 删除面(会话三态的围栏 / 复核 / 收尾输入;`fence` 转发后逐出暖缓存 —— 在删即读作不在,暖条目不许再交出那只会话)。内层店不交 ⇒ 本类也不交。 */
+    readonly sessionDeletion?: SessionDeletionFace;
     /** The session row's list projection for one id + its writable bits (`title` / `pinned`) — DURABLE, pure pass-through
      *  (they read / write `session_meta` / the local sidecars, never the warm cache). 🔴 Must forward (the retention / placements
      *  lesson): the production default wraps the real store in this class, and the route's fact `sessionPatch` reads THIS object. */

package/dist/plugins/caching-session-store.js

@@ -1,5 +1,6 @@
 import { admitSessionPlacement, compareOccupants } from "@sema-agent/core";
 import { placementCapabilityOf } from "./session-placement.js";
+import { birthFaceOf, withdrawFaceOf } from "./session-birth.js";
 export class CachingSessionStore {
     inner;
     cache = new Map();
@@ -8,13 +9,17 @@ export class CachingSessionStore {
     timer;
     onStaleHit;
     headOf;
+    deletionHeadOf;
     register;
+    registerWithReceipt;
+    withdrawBirth;
     listSessions;
     listSessionRows;
     fork;
     forkTo;
     executionPlacement;
     deleteSession;
+    sessionDeletion;
     sessionSummaryOf;
     writeSessionRowCells;
     setTitleIfNull;
@@ -55,8 +60,24 @@ export class CachingSessionStore {
         if (typeof innerPlacementOf === "function")
             this.placementOf = (id) => innerPlacementOf.call(inner, id);
         const ownerAware = inner;
+        if (ownerAware.deletionHeadOf)
+            this.deletionHeadOf = ownerAware.deletionHeadOf.bind(inner);
         if (ownerAware.register)
             this.register = ownerAware.register.bind(inner);
+        const birth = birthFaceOf(inner);
+        if (birth !== undefined)
+            this.registerWithReceipt = birth.registerWithReceipt;
+        const withdraw = withdrawFaceOf(inner);
+        if (withdraw !== undefined) {
+            this.withdrawBirth = async (b, ownTaskId) => {
+                try {
+                    return await withdraw.withdrawBirth(b, ownTaskId);
+                }
+                finally {
+                    this.evict(b.sessionId);
+                }
+            };
+        }
         if (ownerAware.listSessions)
             this.listSessions = ownerAware.listSessions.bind(inner);
         if (ownerAware.listSessionRows)
@@ -130,10 +151,28 @@ export class CachingSessionStore {
             this.sweepStagingSessions = ownerAware.sweepStagingSessions.bind(inner);
         if (ownerAware.deleteSession) {
             const del = ownerAware.deleteSession.bind(inner);
-            this.deleteSession = async (sessionId, owner) => {
-                const removed = await del(sessionId, owner);
-                this.evict(sessionId);
-                return removed;
+            this.deleteSession = async (sessionId, owner, token, legs) => {
+                try {
+                    return await del(sessionId, owner, token, legs);
+                }
+                finally {
+                    this.evict(sessionId);
+                }
+            };
+        }
+        if (ownerAware.sessionDeletion) {
+            const face = ownerAware.sessionDeletion;
+            this.sessionDeletion = {
+                fence: async (sessionId, owner, fenceOpts) => {
+                    try {
+                        return await face.fence(sessionId, owner, fenceOpts);
+                    }
+                    finally {
+                        this.evict(sessionId);
+                    }
+                },
+                holds: (sessionId, token) => face.holds(sessionId, token),
+                pending: () => face.pending(),
             };
         }
         const interval = opts.sweepIntervalMs ?? Math.min(this.ttlMs || 60_000, 60_000);

package/dist/plugins/checkpoint-index-columns.d.ts

@@ -22,7 +22,7 @@
  * (`approval_card`,不是 facet —— 存一份 facet 会在 core 改表那天陈旧),谓词由那两张表机械生成({@link CHECKPOINT_FACET_CASES} → {@link CHECKPOINT_FACET_SQL}),
  * 逐行与 `facetOf` 同答(`test/checkpoint-index-columns.test.ts` B 节、db 组同名文件)。本仓不写第二份判据:没有手写门型表、没有手写卡词。
  * 卡那一侧不带「是不是审批门」的合取:列上的卡只在审批门上非 NULL(同一只派生),与 core 对生成谓词的成文形逐字相同。未登记门型 / NULL 门型 ⇒ 表达式 NULL(无 ELSE)。
- * 拒扫腿的选行序见 {@link CHECKPOINT_SWEEP_ORDER_SQL}:卡列有词的行先取 —— 混跑窗里旧副本写的行卡列为空,它们的 facet 要等下一次起服的 M29 才确证。
+ * 拒扫腿的选行序与游标谓词见 {@link CHECKPOINT_SWEEP_ORDER_SQL} / {@link checkpointSweepAfterSql}:截止、token 两键;拒扫按游标轮转走过期集,没有哪一行能替它后面的行占住窗。
  *
  * ## 谓词什么时候开
  * core 的迁移条款:存量行的卡列由同一只函数回填,并且只在部署自己记下「回填跑完了」之后才开生成谓词。本仓的记录 = 起服序列:M29 跑在一次性迁移段
@@ -100,6 +100,27 @@ export declare class CheckpointIndexRefusedError extends Error {
     readonly refusal: CheckpointIndexRefusal;
     constructor(sessionId: unknown, refusal: CheckpointIndexRefusal);
 }
+/**
+ * **一张卡归在哪只会话上**(`checkpoint.host_session_id` 列;local 孪生 = 归属索引的同一个事实)—— 兑现这张卡的那条 run 的会话:续跑链(决断、取消、
+ * 停驻收割、续跑输入回收、运维队列行的 run 联结)按它把卡与 run 连起来,本服务在会话上找卡的每一个读口只读它。只在写口 `put` 求值一次;
+ * 存量行由一次性迁移 M49 自 `session_id` 回填一次。卡自己的 `session_id`(那条腿的对话)仍在行上,只答「这是哪段对话」(问账匹配、问账留存锚、会话擦除)。
+ *
+ * 读法 = core 卡上的组合腿 `CheckpointState.compositionLeg`(闭集 `entry`;加一个词 ⇒ 本 `switch` 编译红,由人决定那种腿的卡归谁):
+ *  · `cascade` —— 梯子的一级:级跑在自己现铸的会话里,卡归**调用方的会话**(腿上的 `hostSessionId`;续跑入口 `resumeCascade` 接着爬梯子);
+ *  · `verify`  —— 验证器自己的腿:本服务兑现不了它(结算时当场作废,`verifier-pause-card.ts`),卡归它**自己的**会话 —— 不挂到宿主 run 上;
+ *  · 没有组合腿 —— 不是组合入口交出的腿(普通 run、verify 的实现腿与修复轮、委派子代):卡归它自己的会话。
+ * 组合腿形坏(不是对象 / `hostSessionId` 不是非空串 / 闭集外的词)⇒ 抛 {@link CheckpointHostSessionRefusedError},写口零写(引擎铸不出这样的卡;只来自嵌入方 / 手改数据)。
+ */
+export declare function hostSessionOf(cp: Pick<Checkpoint, "sessionId" | "state">): string;
+/** 写口对一张说不出归属的卡的拒(零写;理由见 {@link hostSessionOf})。店错误,不是 wire 码。 */
+export declare class CheckpointHostSessionRefusedError extends Error {
+    constructor(sessionId: unknown, why: string);
+}
+/**
+ * `host_session_id` 列的定义(两方言建表各插一处;列定义的唯一属主)。可空:存量库缺列 ⇒ 起服列册对账拒启并给 `ADD COLUMN` 句;存量行由 M49 回填,
+ * 写口恒写非空值。NULL 只剩一种来历:滚动升级窗里旧副本写下、还没被下一次起服的 M49 补上的行 —— 按会话的读口找不到它(见 MIGRATION 本版那一条)。
+ */
+export declare const CHECKPOINT_HOST_SESSION_COLUMN: Readonly<Record<SqlDialect, string>>;
 /** facet 的词(core 登记表 `facet` 列的值域)。 */
 type Facet = (typeof PAUSE_REGISTRY)[GateKind]["facet"];
 /** 生成谓词的一条 WHEN:某一列的值落在这几个词里 ⇒ 这个 facet。 */
@@ -121,10 +142,16 @@ export declare const CHECKPOINT_FACET_CASES: readonly FacetCase[];
  */
 export declare const CHECKPOINT_FACET_SQL: Readonly<Record<SqlDialect, string>>;
 /**
- * SLA 拒扫腿(`listExpiredApprovalGates`)的选行序:**卡列有词的行先取**,其后 deadline、token。卡列为 NULL 的审批行有两种来历 —— 引擎没给卡的门(照常是审批 SLA),或混跑窗里
- * 不认这一列的旧副本写的行(可能是引擎要拒收 `sla_timeout` 的问答卡,facet 要等下一次起服的 M29 回填才确证);列上没有任何东西能把两者分开,所以不在谓词里猜,而在序里:
- * 有卡词的行 facet 已确证,先占窗;卡列为空的行排在它们之后,各自仍按 deadline 升序。LIMIT 仍是调用方的界,不加旋钮。两方言同一句(`CASE` 在 MySQL 协议与 PG 上同形)。
+ * SLA 拒扫腿(`listExpiredApprovalGates`)的选行序:deadline、token 两键升序(两方言同一句)。拒扫按这个序**轮转**:每拍从上一拍读到的最后一行之后接着读一页
+ * ({@link checkpointSweepAfterSql}),一页不满就回到队首 —— 所以序只决定「一圈里谁先谁后」,不决定「谁轮得到」:一行在这一拍被拒、被跳过、留在停驻,
+ * 游标照样越过它,排在它后面的行下一拍就轮到。修前每拍只取序最前的一页,重新停驻、截止不变的行积满一页就把后面所有到期审批挡到收割;为挡住其中一种
+ * (混跑窗里旧副本写的卡列为空的行)曾把「卡列为空的排后」加成第一键 —— 轮转之后那一种与其余各种同样挡不住任何行,那一键退役。
+ */
+export declare const CHECKPOINT_SWEEP_ORDER_SQL = "deadline ASC, token ASC";
+/**
+ * 拒扫游标的「之后」谓词:严格在游标 `(deadline, token)` 之后 —— 与 {@link CHECKPOINT_SWEEP_ORDER_SQL} 同两键、同方向、同一把比较尺子(列自己的排序规则),
+ * 序与谓词住在一处:改了序必须同改这里,否则游标会跳行或重行。`ph(i)` = 第 i 个游标参数的占位符;参数依次是游标的 deadline、deadline、token。
  */
-export declare const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+export declare function checkpointSweepAfterSql(ph: (i: 0 | 1 | 2) => string): string;
 export {};
 //# sourceMappingURL=checkpoint-index-columns.d.ts.map

package/dist/plugins/checkpoint-index-columns.js

@@ -64,6 +64,38 @@ export class CheckpointIndexRefusedError extends Error {
         this.refusal = refusal;
     }
 }
+export function hostSessionOf(cp) {
+    const leg = cp.state?.compositionLeg;
+    if (leg === undefined)
+        return cp.sessionId;
+    if (typeof leg !== "object" || leg === null)
+        throw new CheckpointHostSessionRefusedError(cp.sessionId, "its composition leg is not an object");
+    const { entry, hostSessionId } = leg;
+    switch (entry) {
+        case "cascade":
+            if (typeof hostSessionId !== "string" || hostSessionId === "")
+                throw new CheckpointHostSessionRefusedError(cp.sessionId, "its cascade leg names no host session");
+            return hostSessionId;
+        case "verify":
+            return cp.sessionId;
+        case undefined:
+            throw new CheckpointHostSessionRefusedError(cp.sessionId, "its composition leg names no entry");
+        default: {
+            const unknownEntry = entry;
+            throw new CheckpointHostSessionRefusedError(cp.sessionId, `its composition leg names an entry this build does not know (${JSON.stringify(unknownEntry)})`);
+        }
+    }
+}
+export class CheckpointHostSessionRefusedError extends Error {
+    constructor(sessionId, why) {
+        super(`the checkpoint row for session ${JSON.stringify(sessionId) ?? "(none)"} was not written: ${why}, so the session it is filed under cannot be read`);
+        this.name = "CheckpointHostSessionRefusedError";
+    }
+}
+export const CHECKPOINT_HOST_SESSION_COLUMN = Object.freeze({
+    mysql: "host_session_id VARCHAR(190) NULL",
+    pg: `host_session_id VARCHAR(190) COLLATE "C"`,
+});
 function groupByFacet(pairs, column) {
     const groups = new Map();
     for (const [word, facet] of pairs) {
@@ -87,5 +119,8 @@ export const CHECKPOINT_FACET_SQL = Object.freeze({
     mysql: renderFacetCase((column) => `CAST(${column} AS BINARY)`),
     pg: renderFacetCase((column) => column),
 });
-export const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+export const CHECKPOINT_SWEEP_ORDER_SQL = "deadline ASC, token ASC";
+export function checkpointSweepAfterSql(ph) {
+    return `(deadline > ${ph(0)} OR (deadline = ${ph(1)} AND token > ${ph(2)}))`;
+}
 //# sourceMappingURL=checkpoint-index-columns.js.map