@sema-agent/server 7.150.0 → 7.152.0

package/dist/stores-sql/blob-index-sql.d.ts

@@ -13,8 +13,9 @@
  *    unreachable and harmless); a port read is checked against its hash here ({@link readAtAddress}) — a mismatch reads as absent.
  *
  * Deletion stays ASYNCHRONOUS (clay 2026-06-26): a purge deletes only the referencing rows, so a blob becomes an orphan; the periodic
- * {@link SqlBlobIndex.sweep} removes the grace-passed index rows FIRST and then asks the port to delete exactly those keys. A port
- * delete that fails surfaces (the sweep rejects — the reaper's throttled guard is the loud channel) and leaves an object with no row.
+ * {@link SqlBlobIndex.sweep} first asks the port whether it may delete at all (refused ⇒ nothing written, the rows wait for the next
+ * sweep), then removes the grace-passed index rows and asks the port to delete exactly those keys. A port delete that still fails
+ * surfaces (the sweep rejects — the reaper's throttled guard is the loud channel) and leaves an object with no row.
  *
  * The SQL statements below are the ones the retired `SqlBlobBackend` / indexed `MinioBlobBackend` sent, verbatim — this module only
  * gathers them under their owner.
@@ -24,6 +25,18 @@ import type { Pool as PgPool } from "pg";
 import { type BlobBackend } from "../plugins/blob-backend.js";
 import { type SqlEngineFacts, type SqlEngineReading, type SqlWallSource, type SqlWallsReading, type SqlDialect } from "../plugins/sql-driver.js";
 import { type Logger } from "../observability/logger.js";
+/** Orphan-blob GC grace — the ONE source (the file-history store's sweep reads it for its blob rows AND its per-landing grant rows):
+ *  a blob is GC-eligible only if unreferenced AND untouched for this long; {@link SqlBlobIndex.put} refreshes created_at on every touch
+ *  (incl a dedup hit, monotonically — a delayed older write never moves it back) so an in-flight snapshot's blobs are protected from
+ *  delete-in-use. 1h ≫ any bounded snapshot. */
+export declare const BLOB_GC_GRACE_MS = 3600000;
+/** One sweep's cutoff (`now − grace`): a sweep reads the clock ONCE and hands the same instant to every leg (grant expiry, index rows). */
+export declare function blobGcCutoffAt(nowMs: number): Date;
+/** Hash-set statements are batched at this many values per statement, both dialects (an unbatched `IN` grows with the input — PG's
+ *  bind protocol caps a statement at 65 535 parameters; MySQL's packet wall caps the statement text). */
+export declare const BLOB_HASH_BATCH = 500;
+/** `hashes` (deduplicated) in batches of {@link BLOB_HASH_BATCH}. */
+export declare function hashBatches(hashes: readonly string[]): string[][];
 /**
  * 文本协议的 blob 膨胀律 —— mysql2 `query()` 把 Buffer 参数写成 `X'<hex>'`,一字节两个字符,所以承载一个 blob 的语句至少是它的 2 倍。
  * 包墙折成「能装下多大的 blob」只用这一只常量,推导里不手写 `/ 2`。
@@ -133,14 +146,22 @@ export declare class SqlBlobIndex {
      *  is loud, not a silent "missing blob"). Port-kept: the port's bytes, checked against `hash` ({@link readAtAddress}: a mismatch —
      *  corruption or a poisoned object — reads as absent, never as wrong bytes; a transient port fault throws). */
     get(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` with an index row — one `blob_hash IN (...)` SELECT, the same reading for both byte homes (a bytes-NULL
-     *  row counts as present). No bytes are read. */
+    /** The subset of `hashes` with an index row — `blob_hash IN (...)` SELECTs batched at {@link BLOB_HASH_BATCH}, the same reading for both
+     *  byte homes (a bytes-NULL row counts as present). No bytes are read. */
     has(hashes: readonly string[]): Promise<Set<string>>;
-    /** Collect orphans: the caller (the store) computes the orphan SET from its own domain's references and hands it here. Removes the
-     *  index rows past the grace window (`created_at < cutoff` — a just-written blob an in-flight write still needs is never deleted:
-     *  delete-in-use is data loss, under-delete is harmless), then — with a byte port — deletes exactly those keys' bytes. Returns the
-     *  number of blobs removed (the grace-passed subset). A port delete failure surfaces as a rejection after the rows are gone. */
-    sweep(orphans: readonly string[]): Promise<number>;
+    /** One orphan sweep of the domain, in the one order — whether the byte port may delete is judged ONCE, before the sweep writes anything,
+     *  because the index rows are a later sweep's only way back to bytes the port still holds:
+     *   ① with a byte port, the port's deletion precondition alone: its own `delete` with no keys (the port contract, `BlobBackend.delete`).
+     *      Refused — the session blob namespace not proven this database's — ⇒ the sweep rejects with the port's refusal having written
+     *      nothing (no row, no byte); the next sweep starts over from the same rows;
+     *   ② `collect`: the caller (the store) computes the orphan SET from its own domain's references — together with its own writes of this
+     *      sweep (the file-history store drops its expired grant rows there) — under the sweep's ONE cutoff ({@link blobGcCutoffAt});
+     *   ③ the index rows past the grace window (`created_at < cutoff` — a just-written blob an in-flight write still needs is never deleted:
+     *      delete-in-use is data loss, under-delete is harmless);
+     *   ④ exactly those keys' bytes (the port's `delete` checks its precondition again: the port's own floor).
+     *  Returns the number of blobs removed (the grace-passed subset). A port delete that fails at ④ surfaces as a rejection after the rows are
+     *  gone. */
+    sweep(collect: () => Promise<readonly string[]>, cutoff: Date): Promise<number>;
     /** DELETE the index rows for `hashes` that have passed the grace window; returns the hashes ACTUALLY deleted. Best-effort: a DB
      *  error is swallowed (under-delete is harmless; the next sweep retries). */
     private deleteRowsPastGrace;

package/dist/stores-sql/blob-index-sql.js

@@ -1,7 +1,18 @@
 import { readAtAddress } from "../plugins/blob-backend.js";
 import { connectJudged, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "../plugins/sql-driver.js";
 import { createLogger } from "../observability/logger.js";
-const BLOB_GC_GRACE_MS = 3_600_000;
+export const BLOB_GC_GRACE_MS = 3_600_000;
+export function blobGcCutoffAt(nowMs) {
+    return new Date(nowMs - BLOB_GC_GRACE_MS);
+}
+export const BLOB_HASH_BATCH = 500;
+export function hashBatches(hashes) {
+    const distinct = [...new Set(hashes)];
+    const out = [];
+    for (let i = 0; i < distinct.length; i += BLOB_HASH_BATCH)
+        out.push(distinct.slice(i, i + BLOB_HASH_BATCH));
+    return out;
+}
 export const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
 export function packetWallBlobCap(maxPacketBytes) {
     return Math.floor(packetWallStatementBytes(maxPacketBytes) / SQL_TEXT_PROTOCOL_BLOB_INFLATION);
@@ -69,10 +80,10 @@ export class SqlBlobIndex {
         if (port !== undefined) {
             await port.put(hash, bytes);
             if (this.dialect === "mysql") {
-                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,NULL,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`, [hash, bytes.byteLength, new Date()]);
+                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,NULL,?) ON DUPLICATE KEY UPDATE created_at = GREATEST(created_at, VALUES(created_at))`, [hash, bytes.byteLength, new Date()]);
             }
             else {
-                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,NULL,$3) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, new Date()]);
+                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,NULL,$3) ON CONFLICT (blob_hash) DO UPDATE SET created_at = GREATEST(${this.opts.table}.created_at, EXCLUDED.created_at)`, [hash, bytes.byteLength, new Date()]);
             }
             return;
         }
@@ -87,8 +98,8 @@ export class SqlBlobIndex {
             throw new BlobTooLargeError(bytes.byteLength, judged.refusal.cap);
         try {
             await judged.conn.query(this.dialect === "mysql"
-                ? `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`
-                : `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+                ? `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = GREATEST(created_at, VALUES(created_at))`
+                : `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = GREATEST(${this.opts.table}.created_at, EXCLUDED.created_at)`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
         }
         finally {
             judged.conn.release();
@@ -106,30 +117,38 @@ export class SqlBlobIndex {
         return b.rows[0]?.bytes != null ? new Uint8Array(b.rows[0].bytes) : undefined;
     }
     async has(hashes) {
-        if (hashes.length === 0)
-            return new Set();
-        const distinct = [...new Set(hashes)];
-        if (this.dialect === "mysql") {
-            const ph = distinct.map(() => "?").join(",");
-            const [rows] = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, distinct);
-            return new Set(rows.map((r) => String(r.blob_hash)));
+        const present = new Set();
+        for (const batch of hashBatches(hashes)) {
+            if (this.dialect === "mysql") {
+                const ph = batch.map(() => "?").join(",");
+                const [rows] = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, batch);
+                for (const r of rows)
+                    present.add(String(r.blob_hash));
+            }
+            else {
+                const ph = batch.map((_, i) => `$${i + 1}`).join(",");
+                const r = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, batch);
+                for (const row of r.rows)
+                    present.add(row.blob_hash);
+            }
         }
-        const ph = distinct.map((_, i) => `$${i + 1}`).join(",");
-        const r = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, distinct);
-        return new Set(r.rows.map((row) => row.blob_hash));
+        return present;
     }
-    async sweep(orphans) {
-        const removed = await this.deleteRowsPastGrace(orphans);
+    async sweep(collect, cutoff) {
         const port = this.opts.bytes;
+        if (port !== undefined)
+            await port.delete([]);
+        const orphans = await collect();
+        const removed = [];
+        for (const batch of hashBatches(orphans))
+            removed.push(...(await this.deleteRowsPastGrace(batch, cutoff)));
         if (port !== undefined && removed.length > 0)
             await port.delete(removed);
         return removed.length;
     }
-    async deleteRowsPastGrace(hashes) {
-        if (hashes.length === 0)
+    async deleteRowsPastGrace(distinct, cutoff) {
+        if (distinct.length === 0)
             return [];
-        const distinct = [...new Set(hashes)];
-        const cutoff = new Date(Date.now() - BLOB_GC_GRACE_MS);
         if (this.dialect === "mysql") {
             const ph = distinct.map(() => "?").join(",");
             const grace = await this.pool

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

@@ -4,7 +4,7 @@ import { type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCurs
 import { type SqlDialect, type SqlDriver } from "../plugins/sql-driver.js";
 import type { CtxWriteClaim } from "../plugins/store-contracts.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-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 CardScopeRootSeat, type CheckpointAskCandidate, type CtxClaimPut, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type ExpiredApprovalGate, type ExpiredGatePosition, type PendingCheckpoint, type PendingRowBinding, type QueueActionFacts } 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
@@ -12,6 +12,33 @@ import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
  * resume-read-path log we emit a stable, non-reversible fingerprint instead, enough to correlate get↔resolve.
  */
 export declare function tokenFingerprint(token: string): string;
+/** {@link StoredRowProjectionMemo} 的字节上界:按每份投影的 JSON UTF-8 字节数累计(常量,不是旋钮 —— 挤出只换代价、不换答案)。 */
+export declare const STORED_ROW_MEMO_MAX_BYTES: number;
+/** {@link StoredRowProjectionMemo} 的条数上界(与字节上界同时生效,先到者挤)。 */
+export declare const STORED_ROW_MEMO_MAX_ENTRIES = 8192;
+/**
+ * [ref] K5 / ④:一份停驻行字节的**动作事实**({@link QueueActionFacts},两孪生同一只投影 `buildQueueActionFacts` 的产物)按 **(停驻行字节, 引擎构建)** 记忆 ——
+ * 字节 = 库内对 `checkpoint` 列投影文本算的 sha256({@link jsonColumnTextSha256},主读只出这 64 字节,整只文档不出库),引擎构建 = core 包版本
+ * `CONTRACT_KIT_ENGINE_VERSION`(不是格式版本上限 `MAX_SUPPORTED_CHECKPOINT_VERSION`:同一格式版本下不同构建的要求表不同,core 7.60.0 / 7.61.0 实证)。
+ * 字节变(带外改行、同 token 重写)⇒ 键变 ⇒ 重读重投;换构建 ⇒ 键变。续跑**不读**本记忆(core 准入恒现算)。
+ *
+ * 有界(LRU):条数 ≤ `maxEntries`,且各条投影的 JSON UTF-8 字节数之和 ≤ `maxBytes`(店用 {@link STORED_ROW_MEMO_MAX_BYTES} / {@link STORED_ROW_MEMO_MAX_ENTRIES});
+ * 超出 ⇒ 挤最久未用的,被挤的行下一次列表按未命中整行重读 —— 代价退回整行读,答案不变。单只投影就超出字节上界 ⇒ 不记(也不为它冲掉别的)。
+ * 只记**完整**的投影:整行解不出、或摘要读不动的行不进记忆(它们的响亮计数按「每次列表」计,不被记忆吃掉)。
+ */
+export declare class StoredRowProjectionMemo {
+    private readonly maxBytes;
+    private readonly maxEntries;
+    private readonly rows;
+    private total;
+    constructor(maxBytes?: number, maxEntries?: number);
+    /** 记着的投影字节数之和(读数;钉读它)。 */
+    get bytes(): number;
+    private keyOf;
+    get(sha256: string): QueueActionFacts | undefined;
+    set(sha256: string, actionFacts: QueueActionFacts): void;
+    private evict;
+}
 /**
  * `checkpoint` 表上**本仓后加、且被无条件引用**的列册 —— 升级前置探针({@link assertCheckpointColumnSchema})
  * 的唯一数据源。一行一列:列名 + 这一列不在时**运行期**先坏在哪(拒启文案逐字用它,所以运维读到的是
@@ -74,6 +101,8 @@ interface SteerColumnRead {
 export declare function readPendingSteerQueueColumn(queueRaw: unknown): SteerColumnRead;
 export interface SqlCheckpointStoreOptions {
     readonly retention?: RetentionDeclaration;
+    /** 「不再询问」规则 project root 的铸卡快照席(后端一只、本店写口读;缺席 = 一只永不绑的席 ⇒ 列 NULL)。 */
+    readonly cardScopeRoot?: CardScopeRootSeat;
 }
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export declare class SqlCheckpointStore implements CheckpointStore {
@@ -134,6 +163,13 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
     } | undefined, opts?: SqlCheckpointStoreOptions);
+    /** 「不再询问」规则 project root 的铸卡快照席(写口 `put` 读一次)。 */
+    private readonly cardScopeRoot;
+    /**
+     * 这张卡上「不再询问」规则的 project root **铸卡快照**(列 `card_scope_root`;续跑腿的停驻行规则记录读者读它)。`null` = 不可知(没铸 / 加这一列之前落下的行)
+     * 或这一行不在 —— 两者对兑付同答(不铸 scope ⇒ `scope-unresolved`)。
+     */
+    cardScopeRootOf(token: CheckpointToken): Promise<string | null>;
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** JSON column binding. TiDB: plain `JSON.stringify`, stored verbatim. PG: `pgProtocolJsonStringify` —
@@ -312,7 +348,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     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
+     *  (`state.rowTaskId` of the same whole-row decode, 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} 都不投执行判词,这是结构性的不是遗漏**:
@@ -323,39 +359,30 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
     /**
-     * 运维队列 / 调度视图要的**整行事实**({@link StoredRowProjection}:判官的判决 + 技能卡两位),按令牌交回。
-     *
-     * 为什么要整行:判官 `judgeCheckpointRow` 读要求表要整只用(词集 + 摘要重算读整个 `state` 的表键路径,core [ref] ③);技能卡**清单**
-     * `boundGrants` 在寄存行上是未经哈希校验的原值,core 只在摘要里「哈希等于摘要」才发布它,校验读口不在 core 的公开导出面上 —— 两者都只能对整只
-     * {@link Checkpoint} 跑 core 的函数(摘要 `summarizeCheckpoint` 一次给两样)。
+     * 运维队列行的**动作事实**({@link QueueActionFacts}:两孪生同一只投影 `buildQueueActionFacts` 对一份停驻行字节答的整份),按令牌交回。
      *
      * 读放大(如实):记忆命中零整行读;未命中的行按令牌**批**读(`IN (…)`,每批 ≤ {@link STORED_ROW_READ_BATCH}),每份字节每个进程一次 ——
-     * 起服后第一次列表把全部待决行读一遍,此后只有字节变了 / 被挤出记忆的行再读(修前:普通卡零整行读,技能卡每次列表都读;`/stream` 每连接每 3 s 一拍)。
-     * 判过的按**读回的那份字节**的摘要入记忆;两次读之间字节变了(批读的摘要 ≠ 主读交来的那一份)⇒ 判过的那一份照入记忆,但**不交回**给这一行 ——
-     * 交回的事实只许出自主读读到的同一份字节(一行一个字节版本;修前按令牌拼,B 的判决与清单配 A 的行),这一行本次不带判决与清单(与「离开待决」同一种缺席),
-     * 下一次列表主读读到新字节即命中记忆。
-     *
-     * 失败方向 = 本店停驻行读者的那一条律({@link SqlCheckpointStore.readStoredRow}):摘要读不动的行(字节解不出 / 体是对象但 core 的摘要读不动)
-     * 判决照给、清单与成因词缺席,计 `server.approvals.park-row-blob-unreadable`,不进记忆(下一次列表重读、再计)。行已离开待决(两次读之间被决 / 过期)⇒ 不在返回里。
-     * `not-text`(读腿漏了投影)与摘要格形不对原样抛(码坏)。授予绑定那一臂(摘要 / 缺席词)不在这里:由 {@link parkRowFacts} 读子树投出。
+     * 起服后第一次列表把全部待决行读一遍,此后只有字节变了 / 被挤出记忆({@link StoredRowProjectionMemo} 的字节 / 条数上界)的行再读。主读每拍只出行址 + 64 字节摘要。
+     * 两次读之间字节变了(批读的摘要 ≠ 主读交来的那一份)⇒ 交回**批读那一版**的整份动作事实(= 此刻续跑会执行的那一版):行的动作事实全部出自这一次解码,
+     * 行址格与字节版本无关(改写不动会话 / scope / 建行时刻 / 截止),不存在一行拼两版。行已离开待决(两次读之间被决 / 过期)⇒ 不在返回里。
+     *
+     * 失败方向 = 本店停驻行读者的那一条律({@link SqlCheckpointStore.readStoredRow}):整行解不出 / 摘要读不动的行交回只带判决的那一份(计
+     * `server.approvals.park-row-blob-unreadable`,不进记忆,下一次列表重读、再计)。`not-text`(读腿漏了投影)与摘要格形不对原样抛(码坏)。
      */
     private storedRowProjections;
-    /** 一行整行读回 → 它的 {@link StoredRowProjection}(摘要读得动的入记忆;失败方向见 {@link SqlCheckpointStore.readStoredRow})。 */
-    private projectStoredRow;
     /**
      * 🔴 **本店停驻行读者的那一条律:一行的字节只坏它自己那一行**(运维队列 / 订阅流的整行读与收件箱 / 任务视图的 `listByScope` 同经这里)。
      *
-     * 一行停驻行的整行读 = `checkpoint` 列那一份字节 → core 判官 `judgeCheckpointRow` 的判决 + (读得动时)core 的摘要 `summarizeCheckpoint`。
-     * 判决**恒在**:判官对任何值都答(core:pure and total),字节读不成一只检查点(JSON 字面 `null` / 标量 / 数组 / 非 JSON)⇒ 交给它的是这一格**原样的文本**
-     * (不是本店编的一行),它答 `damaged`;体是对象而摘要读不动(`{}`、缺 `state` / `pendingAction` / `gate` 的手改行,成员形不对的行)⇒ core 的摘要答它的
-     * 「读不动」那一形({@link isUnreadableSummaryForm}),判决取那一形上的(core:判官的判决,判官答 `ok` 时是「读不动」的固定判决,恒非 `ok`),
-     * 身份由调用方取本店的列组;core 的投影自己抛(它的已知限制:摘要读到成员形表之外的一位)⇒ 判官对这只对象答。
+     * 一行停驻行的整行读 = `checkpoint` 列那一份字节 → core 判官 `judgeCheckpointRow` 的判决 + (读得动时)core 的摘要 `summarizeCheckpoint` → 两孪生同一只投影
+     * `buildQueueActionFacts` 答的动作事实。判决**恒在**:判官对任何值都答(core:pure and total),字节读不成一只检查点(JSON 字面 `null` / 标量 / 数组 / 非 JSON)⇒ 交给它的是这一格
+     * **原样的文本**(不是本店编的一行),它答 `damaged`;体是对象而摘要读不动(`{}`、缺 `state` / `pendingAction` / `gate` 的手改行,成员形不对的行)⇒ core 的摘要答它的
+     * 「读不动」那一形({@link isUnreadableSummaryForm}),判决取那一形上的(core:判官的判决,判官答 `ok` 时是「读不动」的固定判决,恒非 `ok`);
+     * core 的投影自己抛(它的已知限制:摘要读到成员形表之外的一位)⇒ 判官对这只对象答。三形的动作事实都只剩判决(`buildQueueActionFacts` 的「解不出」那一形)。
      * 摘要读不动的几种都计 `server.approvals.park-row-blob-unreadable`(每次列表都计)、不进记忆,core 交给披露座的那一句随之不进风险轴的计数;
-     * **不抛** —— 修前收件箱 / 任务视图对这种行整张拒
-     * (`{}` / 缺 `state` 落 503「请重试」,坏行不修同路径恒失败),运维队列对字节解不出的行不带判决:同一张坏行两个读者两个方向。
+     * **不抛** —— 修前收件箱 / 任务视图对这种行整张拒(`{}` / 缺 `state` 落 503「请重试」,坏行不修同路径恒失败)。
      * 读腿漂(`not-text`:SELECT 没投影这一列)与摘要格形不对照旧原样抛 —— 那是码坏,不是一行数据坏。
      *
-     * 判决按 (这份字节, 引擎构建) 记忆({@link StoredRowProjectionMemo}):命中交给摘要不重判;摘要读得动的那一份由调用方 / 这里记下。
+     * 读得动的行按 (这份字节, 引擎构建) 记忆整份动作事实({@link StoredRowProjectionMemo}):命中交给摘要不重判、不重投。
      */
     private readStoredRow;
     /**
@@ -367,8 +394,8 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * created_at_ms ASC; callers (the inbox/scheduler) sort by severity.
      *
      * 一行读不出摘要(字节解不出 / 体是对象而摘要读不动)⇒ 这一行**照列**,判决非 `ok`(见 {@link SqlCheckpointStore.readStoredRow}),其余几位取本店在字节**之外**握着的事实:
-     * 令牌 / 会话 / scope / 建行时刻 / 截止 / 门型(`gate_kind` 列,与运维队列同一只判官 {@link queueRowGateKind}:读不出 ⇒ 不列、计数)/
-     * `checkpointId` 成员(是串才带;入 wire 前过信任边界由路由判)。失败方向与运维队列同一条律({@link SqlCheckpointStore.readStoredRow})。
+     * 令牌 / 会话 / scope / 建行时刻 / 截止 / 门型(`gate_kind` 列,与运维队列同一只判官 {@link queueRowGateKind}:读不出 ⇒ 不列、计数)。`checkpointId` 只读引擎摘要
+     * (与运维队列行、LOCAL 孪生同一读法)⇒ 这一形缺席。失败方向与运维队列同一条律({@link SqlCheckpointStore.readStoredRow})。
      *
      * LIMIT bounds the fan-out (review w16yqkkxv): a triage view never needs more than a few — 500 is a generous
      * ceiling that still protects memory/latency if a scope ever accumulates pathologically many pending gates.