@sema-agent/server 7.146.0 → 7.148.0

package/dist/stores-sql/checkpoint-store-sql.d.ts

@@ -2,10 +2,9 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type SqlDialect, type SqlDriver } from "../plugins/sql-driver.js";
-import type { SqlRunStore } from "../plugins/run-store-sql.js";
-import type { FencedRun } from "../plugins/store-contracts.js";
+import type { CtxWriteClaim } from "../plugins/store-contracts.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type CheckpointAskCandidate, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "../plugins/checkpoint-store-face.js";
+import { type CheckpointAskCandidate, type CtxClaimPut, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type ExpiredApprovalGate, type ExpiredGatePosition, type PendingCheckpoint, type PendingRowBinding } from "../plugins/checkpoint-store-face.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 /**
  * The capability token IS the resume credential (token-as-auth) — anyone who reads it can impersonate a
@@ -73,10 +72,9 @@ interface SteerColumnRead {
  * 列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
  */
 export declare function readPendingSteerQueueColumn(queueRaw: unknown): SteerColumnRead;
-/** SQL checkpoint 店的装配选项:托管留存声明 + ctx 改写的认领栅栏(同一只池上的 run 店)。 */
+/** SQL checkpoint 店的装配选项:托管留存声明。(ctx 栅栏写口的认领由调用方每次交进来 —— [ref]:栅栏的来源是认领本身,店不另绑 run 店。) */
 export interface SqlCheckpointStoreOptions {
     readonly retention?: RetentionDeclaration;
-    readonly claims?: SqlRunStore;
 }
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export declare class SqlCheckpointStore implements CheckpointStore {
@@ -85,7 +83,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
         info?(msg: string, meta?: unknown): void;
     } | undefined;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
-     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
+     *  `retention-store-sql.ts`」逐字见 `plugins/retention-declaration.ts` 的 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
     readonly retention: RetentionDeclaration;
     /**
      * `CheckpointStore.durability` 声明([ref] 欠账,[ref] 件5)—— 行落在 MySQL-protocol / PostgreSQL 的
@@ -132,9 +130,6 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     readonly execution: {
         readonly outcome: true;
     };
-    /** ctx 改写的认领栅栏({@link SqlCheckpointStore.rewriteCtxWhileClaimed}):后端装配绑**同一只池**上的 run 店(`plugins/store-backend.ts` 的 `checkpoint()`)。
-     *  缺席 ⇒ 那一口响亮抛(装配缺陷),其余口不读它。 */
-    private readonly claims;
     /** 停驻行投影记忆([ref] ④;运维队列与调度视图共用,见 {@link StoredRowProjectionMemo})。进程内、按店实例。 */
     private readonly storedRowMemo;
     constructor(db: SqlDriver, logger?: {
@@ -290,19 +285,16 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * in SQL, before the LIMIT: `limit` bounds the per-tick deny-resume work (each is a model run), never hides a row behind
      * rows the sweep does not own.
      *
-     * Order ({@link CHECKPOINT_SWEEP_ORDER_SQL}): rows whose `approval_card` column carries a word come first, then rows whose card
-     * is NULL, each by deadline. A NULL card on an approval gate is either a gate the engine gave no card (a real SLA row) or a
-     * row a replica that does not know the column wrote during a mixed-version window — possibly a question, which the engine
-     * refuses to deny (`sla_timeout`) and which the next boot's M29 backfill settles. The column cannot tell the two apart, so the
-     * order does: rows whose facet is certain take the window first and a straggler cannot crowd them out.
+     * Order and paging ({@link CHECKPOINT_SWEEP_ORDER_SQL} / {@link checkpointSweepAfterSql}): deadline, then token. Each row carries
+     * its position on that order; `after` (the last position the sweep read) returns only the rows strictly after it, so the sweep
+     * walks the expired set round-robin — a row it could not settle (refused before claim, skipped, parked child) never holds the
+     * window for the rows behind it ([ref]). The two position columns are the cursor only: in-process, never on the wire.
      */
-    listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
-        sessionId: string;
-        scope: string;
-    }>>;
-    /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` is
-     *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
-     *  session claim, so the join is live for every pending row; null only in pathological windows). */
+    listExpiredApprovalGates(cutoff: number, limit?: number, after?: ExpiredGatePosition): Promise<ExpiredApprovalGate[]>;
+    /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` = the task the
+     *  parked leg runs as ([ref], written by `parkedLegTaskId`): the registry row the engine recorded on the row
+     *  (`$.state.rowTaskId`, a background child's `a…` handle), else the task_active join (a suspended run KEEPS its
+     *  session claim); null when neither (a synchronous / workflow child, a terminal-only park). */
     /**
      * [ref] 显式记账 —— **本口与 {@link SqlCheckpointStore.listByScope} 都不投执行判词,这是结构性的不是遗漏**:
      * 两口的谓词都硬 `status='pending'`,而执行记录的 CAS 谓词是 `status='resolved' AND execution_outcome IS NULL`
@@ -463,9 +455,15 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     peekScopeByToken(token: CheckpointToken): Promise<string | null | undefined>;
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
-    /** Upsert the resume rebuild inputs for a session — written at SUBMIT (durable mode on) and, since [ref] F2,
-     *  once per resume leg at its CAS win point (`DriveResumeArgs.resumeCtx`). Unconditional per `session_id`:
-     *  the ordering fence lives at the CALLER's CAS win, not in a version column here.
+    /**
+     * 一张卡**归在哪只会话上**(归属列;不判状态、不读 blob)—— 手里拿着卡(凭据)、要找它那条 run 的读者读它:决断腿的 run 行 / 续跑输入 / 认领,结算作废的核对。
+     * `undefined` = 没有这一行;`null` = 行在、归属列空(滚动升级窗里旧副本写下、还没被 M49 补上的行:说不出归属,读者按「找不到它的 run」处置)。
+     */
+    hostSessionOfCard(token: CheckpointToken): Promise<string | null | undefined>;
+    /** Upsert the resume rebuild inputs for a session —— 续跑输入的**唯一**写口([ref]):写者持有一只认领 ⇒ 交 `claim`,写落在那只认领的栅栏里
+     *  ({@link writeCtxWhileClaimed}:「这条 run 此刻仍持有会话认领、在跑、腿判据答是」与写同一笔,同一条事务连接;不持有 ⇒ 零写,答 `claim_released`);
+     *  没有认领的写者(leader 子工作者 / 无 run 店的部署)不交 ⇒ 无条件写(没有栅栏可依)。持认领的腿:提交腿 `createRun` 之后、续跑腿 CAS 赢点。
+     *  于是「认领 → 写在路上 → 认领被收割 / 终局放掉 → 同会话新 run 写下它的体 → 迟到的这一笔」**结构上落不下**。结局闭集 {@link CtxClaimPut}。
      *
      *  🔴 `ctx: object`, not `unknown` ([ref]): the read leg judges this column as a JSON **object**
      *  ({@link decodeCtxColumn}), so a writer that took `unknown` would be the "writes fine, reads back
@@ -479,7 +477,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *  SUCCEED and replace a readable durable row with an unreadable one (caller sees 2xx, the next resume
      *  409s forever). So the serialized value is judged by {@link assertJsonColumnWritable} — the SAME shape
      *  reader the read leg uses — BEFORE the statement runs: refuse loudly, leave the row on disk untouched. */
-    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx, claim?: CtxWriteClaim): Promise<CtxClaimPut>;
+    /** ctx 行的 upsert 语句(唯一一份;无栅栏写跑在池上,栅栏写跑在栅栏的事务连接上)。 */
+    private upsertCtx;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
     /**
      * **认领栅栏下改写既有 ctx 行** —— 在飞 run 的切档口(`http/routes/run-permission-mode.ts`)把准入的模式词写回存储体的唯一写口。
@@ -487,17 +487,22 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * 规则:只有**接下这笔改写的那条腿**此刻仍持有这条 run 时才写 —— `taskId` 持有 `sessionId` 的会话认领、这条 run 在跑、且调用方的腿判据 `legHolds`
      * 对锁住那一行的 {@link FencedRun} 答是(认领与 `running` 只认 taskId:续跑腿让同一个 taskId 停驻之后回到 `running`、认领仍在,旧腿迟到的改写不许盖掉续跑的新腿
      * 写下的体 —— 那是 ABA,只有腿判据分得开;今天的腿身份 = 副本 `instanceId`(续跑的 CAS 赢点改写它)∧ 调用方进程里这条 run 的活流仍是接下改写的那一只)。
-     * 写在所绑 run 店的认领栅栏事务里
+     * 写在调用方交来的那只认领(`claim.fence`,持认领的 run 店)的栅栏事务里
      * (`SqlRunStore.whileHoldingClaim`:先锁 run 行、再锁认领行 —— 与终局 / 收割同序 —— 刷新活性,本口的锁读 + UPDATE 在同一个事务连接上)。
      * 于是「这条 run 终局放掉认领 → 同会话新 run 写下它自己的 ctx → 本口迟到的改写」这一序**结构上不可能**盖掉新 run 的行:终局要等本事务提交才拿得到
-     * run 行的锁,拿到之后本口再来就判出不持有、一个字节都不写。`putCtx` 的无条件 upsert 只给持有认领的那几条腿自己的写点(提交 / 续跑 CAS 赢点)用;
-     * 不在腿里的写者走这一口。
+     * run 行的锁,拿到之后本口再来就判出不持有、一个字节都不写。持认领的腿自己的写(提交 / 续跑 CAS 赢点)经 {@link putCtx} 交认领、走同一只栅栏例程([ref])。
      * 只改**既有**行(锁读零行 ⇒ `context_absent`,不建行):切档改的是这条 run 提交时写下的那一行,没有那一行就没有要改的存储体。
      * 结局闭集 {@link CtxClaimRewrite}:`written` / `claim_released`(接下改写的那条腿已不持有这条 run —— 认领放了 / 不在跑 / 腿判据答否:零写)/ `context_absent`(持有、无行:零写)。
      * 腿判据在栅栏里同步问一次(锁已持有、写之前);它只读、不许 await。
      * 编码与形闸同 {@link SqlCheckpointStore.putCtx}(写之前判,坏形响亮拒、盘上不动);一行装不下 ⇒ `StoreRowTooLargeError`。
      */
-    rewriteCtxWhileClaimed(sessionId: string, taskId: string, ctx: SealedCheckpointCtx, legHolds: (run: FencedRun) => boolean): Promise<CtxClaimRewrite>;
+    rewriteCtxWhileClaimed(sessionId: string, ctx: SealedCheckpointCtx, claim: CtxWriteClaim): Promise<CtxClaimRewrite>;
+    /**
+     * 两只 ctx 栅栏写(`putCtx` 交认领的那一形 / `rewriteCtxWhileClaimed`)共用的栅栏例程(一处判形、一处判持有、一处折码):调用方交来的认领栅栏必须是 SQL run 店且与本店同方言
+     * (两店出自同一后端 —— 同一只池;错形 ⇒ 响亮抛,不降级成无栅栏写);在它的事务里(先锁 run 行、再锁认领行,与终局 / 收割同序)问一次腿判据,
+     * 答是才在**同一条事务连接**上跑 `write`。形闸在栅栏之前(坏形不开事务);一行装不下 ⇒ `StoreRowTooLargeError`。
+     */
+    private writeCtxWhileClaimed;
     /**
      * 🔴 **一次性迁移的 ctx 行改写店腿**({@link CheckpointCtxRowsRewriter};用它的迁移与各自的行改写见那里,窗与删法见 `plugins/one-time-migrations.ts` 登记表;
      * 本店不知道改写是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`

package/dist/stores-sql/checkpoint-store-sql.js

@@ -1,6 +1,6 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
+import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, checkpointSweepAfterSql, hostSessionOf, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
 import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { parkRowFacts, skillCardFacts } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
@@ -9,9 +9,9 @@ import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identi
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "../plugins/sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "../plugins/sql-errors.js";
 import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-store-sql.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
-import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
+import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, parkedLegTaskId, queueRowGateKind, queueTriageOrder, readRiskDescriptorBody, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
 const CTX_REWRITE_PAGE = 500;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
@@ -61,7 +61,14 @@ export const CHECKPOINT_ADDED_COLUMNS = [
         column: "execution_at_ms",
         breaksAt: "it is written in the same CAS as `execution_outcome` (the record and its stamp are one write group)",
     },
+    {
+        column: "host_session_id",
+        breaksAt: "the park-mint write (put) stamps it, the one-time backfill M49 (which runs right after this check) fills it on the rows already parked, " +
+            "and every read that finds a run's card — cancel, steer, both park reapers, resume-context retention, the queue row's run — names it, " +
+            "so every durable suspend fails at first park and every cancel of a parked run errors",
+    },
 ];
+const PENDING_ROW_AXIS_COLUMN = { card: "session_id", run: "host_session_id" };
 export async function assertCheckpointColumnSchema(query, dialect) {
     for (const { column, breaksAt } of CHECKPOINT_ADDED_COLUMNS) {
         try {
@@ -82,18 +89,12 @@ export async function assertCheckpointColumnSchema(query, dialect) {
 const readCheckpointBlobBody = createObjectColumnReader();
 const readResumeOutcomeBody = createObjectColumnReader();
 const readGateOutcomeBody = createObjectColumnReader();
-const readRiskDescriptorBody = createObjectColumnReader();
 function decodeCheckpointColumn(cell, where) {
     return decodeJsonColumn(cell, readCheckpointBlobBody, `checkpoint.checkpoint ${where}`);
 }
 function verdictOfUnreadableBody(cell) {
     return judgeCheckpointRow(cell);
 }
-const UNREADABLE_SUMMARY_MEMBERS = new Set(["token", "rowVerdict", "sessionId", "scope", "gateKind", "createdAt", "deadline"]);
-function isUnreadableSummaryForm(summary) {
-    const names = UNREADABLE_SUMMARY_MEMBERS;
-    return summary.rowVerdict.kind !== "ok" && Object.keys(summary).every((member) => names.has(member));
-}
 function readCheckpointBodyOrRefuse(cell, where) {
     try {
         return refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(cell, where));
@@ -161,8 +162,8 @@ function readParkRowActionCell(cell) {
         return undefined;
     }
 }
-const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
-const PARK_ROW_CHECKPOINT_ID = { key: "checkpointId", as: "checkpoint_id" };
+const PARK_ROW_PENDING_ACTION = { path: ["pendingAction"], as: "pending_action" };
+const PARK_ROW_CHECKPOINT_ID = { path: ["checkpointId"], as: "checkpoint_id" };
 const readCheckpointIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "checkpointId is not a JSON string" });
 function readCheckpointIdCell(cell) {
     try {
@@ -174,6 +175,18 @@ function readCheckpointIdCell(cell) {
         return null;
     }
 }
+const PARK_ROW_RECORDED_TASK_ID = { path: ["state", "rowTaskId"], as: "row_task_id" };
+const readRecordedTaskIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "state.rowTaskId is not a JSON string" });
+function readRecordedTaskIdCell(cell) {
+    try {
+        return decodeNullableJsonColumn(cell, readRecordedTaskIdMemberBody, "checkpoint.checkpoint $.state.rowTaskId (operator queue row)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return undefined;
+    }
+}
 const readPendingActionMemberBody = createObjectColumnReader();
 function candidateIdentityOfColumn(cell, where) {
     let cp;
@@ -187,39 +200,23 @@ function candidateIdentityOfColumn(cell, where) {
     }
     return candidateIdentityOf(cp);
 }
-function readActorAssertion(v) {
-    if (typeof v !== "object" || v === null)
-        return undefined;
-    const id = "id" in v ? v.id : undefined;
-    const hostAsserted = "hostAsserted" in v ? v.hostAsserted : undefined;
-    if (typeof id !== "string" || typeof hostAsserted !== "boolean")
-        return undefined;
-    const issuer = "issuer" in v ? v.issuer : undefined;
-    return { id, hostAsserted, ...(typeof issuer === "string" ? { issuer } : {}) };
-}
 function readQueueEntry(v) {
     if (typeof v !== "object" || v === null)
         return undefined;
-    const text = "text" in v ? v.text : undefined;
-    const trusted = "trusted" in v ? v.trusted : undefined;
     const seq = "seq" in v ? v.seq : undefined;
-    const inputId = "inputId" in v ? v.inputId : undefined;
-    if (typeof text !== "string" || typeof trusted !== "boolean")
-        return undefined;
     if (typeof seq !== "number" || !Number.isFinite(seq))
         return undefined;
-    if (typeof inputId !== "string" || inputId === "")
+    if (!("inputId" in v) || v.inputId === undefined)
         return undefined;
-    const priority = "priority" in v ? v.priority : undefined;
-    const actor = readActorAssertion("actor" in v ? v.actor : undefined);
-    return {
-        text,
-        trusted,
-        seq,
-        inputId,
-        ...(actor !== undefined ? { actor } : {}),
-        ...(priority === "now" || priority === "next" || priority === "later" ? { priority } : {}),
-    };
+    const carried = Object.fromEntries(Object.entries(v).filter(([key]) => key !== "seq"));
+    try {
+        return { ...validatePendingSteer(carried), seq };
+    }
+    catch (e) {
+        if (e instanceof CheckpointError && e.code === "steering.invalid_content")
+            return undefined;
+        throw e;
+    }
 }
 export function readPendingSteerQueueColumn(queueRaw) {
     let lossy = false;
@@ -254,13 +251,11 @@ export class SqlCheckpointStore {
     durability = "durable";
     fidelity = "json";
     execution = { outcome: true };
-    claims;
     storedRowMemo = new StoredRowProjectionMemo();
     constructor(db, logger, opts = {}) {
         this.db = db;
         this.logger = logger;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
-        this.claims = opts.claims;
     }
     q(mysql, pg) {
         return this.db.dialect === "mysql" ? mysql : pg;
@@ -276,7 +271,7 @@ export class SqlCheckpointStore {
     }
     pendingRowQuery(select, sessionId, scope, binding) {
         const params = [sessionId];
-        const where = [`session_id=${this.ph(1)}`, "status='pending'"];
+        const where = [`${PENDING_ROW_AXIS_COLUMN[binding?.axis ?? "card"]}=${this.ph(1)}`, "status='pending'"];
         if (scope !== undefined) {
             params.push(scope);
             where.push(`scope=${this.ph(params.length)}`);
@@ -302,15 +297,16 @@ export class SqlCheckpointStore {
         if (judged.kind !== "cells")
             throw new CheckpointIndexRefusedError(cp.sessionId, judged);
         const cells = judged.cells;
+        const hostSessionId = hostSessionOf(cp);
         const pa = cp.pendingAction;
         const toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
         const executionOutcome = cp.executionOutcome === undefined ? null : this.json(cp.executionOutcome, "execution outcome");
         const executionAtMs = cp.executionOutcome === undefined ? null : (cp.executionAtMs ?? null);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22)"), [
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
+                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22,$23)"), [
                 token,
                 cells.scope,
                 cells.session_id,
@@ -333,6 +329,7 @@ export class SqlCheckpointStore {
                 cp.reopenReason ?? null,
                 executionOutcome,
                 executionAtMs,
+                hostSessionId,
             ]);
         }
         catch (e) {
@@ -455,17 +452,20 @@ export class SqlCheckpointStore {
             `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND COALESCE(${CHECKPOINT_FACET_SQL.pg}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
-    async listExpiredApprovalGates(cutoff, limit = 100) {
-        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit]);
-        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
+    async listExpiredApprovalGates(cutoff, limit = DENY_SWEEP_PAGE_ROWS, after) {
+        const head = "SELECT session_id, scope, deadline, token FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ";
+        const { rows } = after === undefined
+            ? await this.db.query(this.q(`${head}? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `${head}$1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit])
+            : await this.db.query(this.q(`${head}? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' AND ${checkpointSweepAfterSql(() => "?")} ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `${head}$1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' AND ${checkpointSweepAfterSql((i) => `$${i + 2}`)} ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $5`), [cutoff, after.deadline, after.deadline, after.token, limit]);
+        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope), position: { deadline: Number(r.deadline), token: String(r.token) } }));
     }
     async listPending(scope) {
         const d = this.db.dialect;
         const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
             `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, c.approval_card, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_RECORDED_TASK_ID)}, ` +
             `${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)} ` +
-            "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
+            "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.host_session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
             : await this.db.query(`${base} ORDER BY c.created_at_ms ASC`);
@@ -488,7 +488,7 @@ export class SqlCheckpointStore {
                 ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
                 ...(boundInputHash !== null ? { boundInputHash } : {}),
                 gateKind,
-                taskId: r.task_id ?? null,
+                taskId: parkedLegTaskId(readRecordedTaskIdCell(r[PARK_ROW_RECORDED_TASK_ID.as]), r.task_id ?? null),
                 input: refusing("a tool input the operator would be approving unseen", () => decodeToolInputColumn(r.tool_input)) ?? null,
                 createdAt: Number(r.created_at_ms),
                 deadline: r.deadline == null ? null : Number(r.deadline),
@@ -505,7 +505,7 @@ export class SqlCheckpointStore {
             const p = projections.get(e.token);
             return p === undefined ? e.row : { ...e.row, ...p.skillCardFacts, rowVerdict: p.rowVerdict };
         });
-        return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
+        return out.sort(queueTriageOrder);
     }
     async storedRowProjections(rows) {
         const out = new Map();
@@ -692,42 +692,57 @@ export class SqlCheckpointStore {
             return undefined;
         return rows[0].scope ?? null;
     }
-    async putCtx(sessionId, ctx) {
+    async hostSessionOfCard(token) {
+        const { rows } = await this.db.query(this.q("SELECT host_session_id FROM checkpoint WHERE token = ?", "SELECT host_session_id FROM checkpoint WHERE token = $1"), [token]);
+        if (!rows[0])
+            return undefined;
+        const host = rows[0].host_session_id;
+        return typeof host === "string" && host !== "" ? host : null;
+    }
+    async putCtx(sessionId, ctx, claim) {
+        if (claim !== undefined)
+            return this.writeCtxWhileClaimed(sessionId, ctx, claim, "claim-fenced write", async (tx, text) => (await this.upsertCtx(tx, sessionId, text), "written"));
         const text = this.json(ctx, "checkpoint ctx");
         assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (write leg)`);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
-                "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
-                "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
+            await this.upsertCtx(this.db, sessionId, text);
         }
         catch (e) {
             throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)}`);
         }
+        return "written";
+    }
+    async upsertCtx(exec, sessionId, text) {
+        await exec.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
+            "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
+            "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
     }
     async getCtx(sessionId) {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
-    async rewriteCtxWhileClaimed(sessionId, taskId, ctx, legHolds) {
-        const claims = this.claims;
-        if (claims === undefined)
-            throw new Error("SqlCheckpointStore.rewriteCtxWhileClaimed: no claim fence is bound to this store (wiring defect: the backend binds its own run store)");
+    async rewriteCtxWhileClaimed(sessionId, ctx, claim) {
+        return this.writeCtxWhileClaimed(sessionId, ctx, claim, "claim-fenced rewrite", async (tx, text) => {
+            const row = await tx.query(this.q("SELECT session_id FROM checkpoint_ctx WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM checkpoint_ctx WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+            if (row.rows.length === 0)
+                return "context_absent";
+            await tx.query(this.q("UPDATE checkpoint_ctx SET ctx = ?, updated_at_ms = ? WHERE session_id = ?", "UPDATE checkpoint_ctx SET ctx = $1::jsonb, updated_at_ms = $2 WHERE session_id = $3"), [text, Date.now(), sessionId]);
+            return "written";
+        });
+    }
+    async writeCtxWhileClaimed(sessionId, ctx, claim, leg, write) {
+        const fence = claim.fence;
+        if (!("db" in fence) || fence.db.dialect !== this.db.dialect) {
+            throw new Error(`SqlCheckpointStore ${leg}: the claim fence must be the ${this.db.dialect} run store on this store's database (wiring defect: the run store and the checkpoint store come from one backend)`);
+        }
         const text = this.json(ctx, "checkpoint ctx");
-        assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (claim-fenced rewrite)`);
+        assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         let fenced;
         try {
-            fenced = await claims.whileHoldingClaim(sessionId, taskId, async (tx, run) => {
-                if (!legHolds(run))
-                    return "claim_released";
-                const row = await tx.query(this.q("SELECT session_id FROM checkpoint_ctx WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM checkpoint_ctx WHERE session_id = $1 FOR UPDATE"), [sessionId]);
-                if (row.rows.length === 0)
-                    return "context_absent";
-                await tx.query(this.q("UPDATE checkpoint_ctx SET ctx = ?, updated_at_ms = ? WHERE session_id = ?", "UPDATE checkpoint_ctx SET ctx = $1::jsonb, updated_at_ms = $2 WHERE session_id = $3"), [text, Date.now(), sessionId]);
-                return "written";
-            });
+            fenced = await fence.whileHoldingClaim(sessionId, claim.taskId, async (tx, run) => (claim.legHolds(run) ? write(tx, text) : "claim_released"));
         }
         catch (e) {
-            throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (claim-fenced rewrite)`);
+            throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         }
         return fenced.held ? fenced.value : "claim_released";
     }
@@ -776,9 +791,9 @@ export class SqlCheckpointStore {
     }
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at_ms < ? " +
-            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT host_session_id FROM checkpoint WHERE status='pending' AND host_session_id IS NOT NULL) " +
             "AND session_id NOT IN (SELECT session_id FROM task_active)", "DELETE FROM checkpoint_ctx WHERE updated_at_ms < $1 " +
-            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT host_session_id FROM checkpoint WHERE status='pending' AND host_session_id IS NOT NULL) " +
             "AND session_id NOT IN (SELECT session_id FROM task_active)"), [cutoff]);
         return res.affected;
     }

package/dist/{plugins → stores-sql}/file-history-store-sql.d.ts

@@ -1,10 +1,11 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
-import { type BlobBackend } from "./blob-backend.js";
-import type { ServiceBlobExchange } from "./store-backend.js";
-import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
-/** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
+import type { BlobBackend } from "../plugins/blob-backend.js";
+import { SqlBlobIndex } from "./blob-index-sql.js";
+import type { ServiceBlobExchange } from "../plugins/store-backend.js";
+import { type SqlDriver, type SqlDialect } from "../plugins/sql-driver.js";
+/** The file-history blob domain's SQL table (this store's blob index + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
 /** MinIO object-key prefix for this domain (snapshot epoch used "blobs/"; a separate prefix keeps the
  *  two domains' objects disjoint so neither sweep can see the other's keys). */
@@ -17,18 +18,29 @@ export declare const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
  */
 export interface SqlFileHistoryStoreOptions {
     retention?: FileHistoryRetentionPolicy;
+    /** Where the blob bytes go — the shape of the engine package's `fileHistory.blobs`: absent ⇒ in this store's own
+     *  `file_history_blob` rows (SQL, capped per blob); a byte port ⇒ the port holds them and the rows keep bytes NULL. */
+    blobs?: BlobBackend;
+    /** The operator's explicit per-blob cap for SQL-kept bytes (`SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ derived from the walls of
+     *  the connection that writes. Not read with a byte port. */
+    blobSqlMaxBytes?: number;
+    /** Where a stale connection's replacement on an SQL-kept blob write is logged. */
+    log?: {
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
 }
 /** Dual-dialect durable FileHistoryStore. See the file header for posture + dialect-delta ledger. */
 export declare class SqlFileHistoryStore implements FileHistoryStore {
     protected readonly db: SqlDriver;
-    /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
+    /** RAW native pool — handed to the blob index (`blob-index-sql.ts`, outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
     protected readonly pool: MySqlPool | PgPool;
     /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link ServiceBlobExchange}): how another machine's bytes
      *  come in ahead of an `importHistory`, go out to a puller, and are asked about. Its presence IS the capability — read through
      *  `blobExchangeOf` (`session-sync.ts`), which defers to core's judge; there is no second word for it on this class. */
     readonly blobExchange: ServiceBlobExchange;
-    protected readonly blobs: BlobBackend;
+    /** This store's blob index (the `file_history_blob` rows; the byte port, when given, behind it). */
+    protected readonly blobs: SqlBlobIndex;
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
     private readonly spentAttempts;
     private readonly activeAttempts;
@@ -36,9 +48,9 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  由 core 的 `resolveFileHistoryRetention` 在构造期裁定 —— 与两只内置后端同一道门、同一句拒绝。 */
     private readonly boundaryKeep;
     constructor(db: SqlDriver, 
-    /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
+    /** RAW native pool — handed to the blob index (`blob-index-sql.ts`, outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
-    pool: MySqlPool | PgPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    pool: MySqlPool | PgPool, opts?: SqlFileHistoryStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     private bool;
@@ -174,18 +186,18 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /**
      * Fetch + content-address verify EVERY blob the envelope references from the source, one at a time (memory bounded by one blob) —— 首推与同图重推共用的**唯一**取值校验;
      * 任何一枚取不出 / 核不过 ⇒ 整信封典型拒,什么都不发布。`onVerified` = 校验过的这一枚拿来做什么:首推传「续租式 upsert」(delete-in-use 租约 —— 发布前的孤儿清扫不许收走
-     * 这次导入正要引用的字节);同图重推不传 —— 已发布的图的版本行本身就是引用,租约无事可护,而回写会把每只对象重传一遍(MinIO 的 `putBlob` 是整体 PUT)。
+     * 这次导入正要引用的字节);同图重推不传 —— 已发布的图的版本行本身就是引用,租约无事可护,而回写会把每只对象重传一遍(对象存储字节口的 `put` 是整体 PUT)。
      */
     private verifySourceBlobs;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
 }
 /** MySQL-protocol (TiDB) binding. */
 export declare class TiDBFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool: MySqlPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    constructor(pool: MySqlPool, opts?: SqlFileHistoryStoreOptions);
 }
 /** PostgreSQL binding. */
 export declare class PgFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool: PgPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    constructor(pool: PgPool, opts?: SqlFileHistoryStoreOptions);
 }
 /**
  * [ref] D1② — A7-recipe upgrade precondition assert (**refuse to start**, never a warn; the form and