@sema-agent/server 1.323.0 → 2.0.1

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

@@ -1,3 +1,37 @@
+/**
+ * Durable approval store for the human-in-the-loop write gate (F4) — SINGLE-FILE DUAL-DIALECT
+ * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBApprovalStore` /
+ * `PgApprovalStore` class names survive as thin ctor subclasses so every consumer (store-backend.ts,
+ * src/index.ts, the approval/audit/security-coverage suites) is untouched.
+ *
+ * When a gated tool call is about to run, a `pending` row is recorded here; the instance running the
+ * task polls it for a decision. Because the row is durable and shared, an operator's approve/deny can
+ * land on ANY instance — critical under async runs + a load balancer, where the deciding request and
+ * the waiting run are usually on different instances.
+ *
+ * Unlike the run/checkpoint PG store (whose schema is owned centrally by pg-pool.ts), this file also
+ * exports a self-contained PG schema (`PG_APPROVAL_SCHEMA` + `ensureSchema`) — the `approval` table is
+ * DISJOINT from the other PG stores' tables, so a CREATE IF NOT EXISTS here shadows nothing. Central
+ * aggregation into pg-pool.ts composes it alongside the others. Kept in lock-step with the TiDB store
+ * by the shared real-DB integration suite (test/pg-approval-store-integration.test.ts).
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - null-safe scope compare: `<=>` vs `IS NOT DISTINCT FROM` (a NULL scope row — legacy/untenanted
+ *     run — is matched by a NULL scope arg; one tenant's scope NEVER matches another's — the
+ *     single-DB fleet read guard, defense-in-depth)
+ *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgProtocolJsonStringify` (codex R4-H2: the
+ *     persisted approval `args` is the operator's REVIEW surface and must agree byte-for-byte with the
+ *     policy-executed args — a lossy/rewriting envelope would let an operator approve one payload while
+ *     a different one runs)
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - schema ownership: TiDB DDL lives in tidb-pool.ts SCHEMA_STATEMENTS; PG DDL is this file's own
+ *     self-contained `PG_APPROVAL_SCHEMA` (see the PG twin's original header — unlike the other PG
+ *     stores, `approval` is NOT centrally owned by pg-pool.ts's DDL array, only aggregated into its
+ *     `ensureSchema` composition).
+ *   - `getStatus` result shape: `RowDataPacket[]` (mysql2 typed query) vs a plain-record `pg` query —
+ *     normalized to `SqlRow` by the shared driver, so both arms read the same field names.
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
@@ -7,6 +41,7 @@ export interface ApprovalRow {
     taskId: string | null;
     sessionId: string | null;
     owner: string | null;
+    /** Single-DB fleet scope guard (defense-in-depth): the run's tenant identity, owner-sourced. Reads filter on it. */
     scope: string | null;
     toolName: string;
     args: unknown;
@@ -16,12 +51,23 @@ export interface ApprovalRow {
     createdAt: string;
     decidedAt: string | null;
 }
+/** PG translation of the `approval` DDL in tidb-pool.ts SCHEMA_STATEMENTS (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  inline KEY→separate CREATE INDEX).
+ *
+ *  SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ *  drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead. */
 export declare const PG_APPROVAL_SCHEMA: string[];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+/** Dual-dialect durable approval store. See the file header for the dialect-delta ledger. */
 export declare class SqlApprovalStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
+     *  (codex R4-H2 — the approval `args` is the operator's review surface and must agree with the
+     *  policy-executed args at the NUL position). */
     private json;
     createPending(id: string, scope: string | null, ctx: {
         taskId?: string | null;
@@ -35,17 +81,35 @@ export declare class SqlApprovalStore {
         reason: string | null;
         decidedBy: string | null;
     } | undefined>;
+    /** Apply a terminal decision, but only to a still-pending row (CAS). Returns whether it applied. The scope
+     *  guard (null-safe) is carried on the operator path too for consistency with the read paths. */
     decide(id: string, scope: string | null, decision: "approved" | "denied" | "expired", reason: string | null, decidedBy: string | null): Promise<boolean>;
+    /** Pending approvals (operator queue), scoped to one tenant (single-DB fleet read guard, null-safe), optionally
+     *  further filtered to one owner. */
     listPending(scope: string | null, owner?: string): Promise<ApprovalRow[]>;
     get(id: string, scope: string | null): Promise<ApprovalRow | undefined>;
+    /** Operator-only CROSS-tenant by-id read (no scope filter). The F4 operator queue serves/decides across
+     *  tenants by design; the HTTP layer gates this to an operator and then re-binds decide() to the row's OWN
+     *  scope. Tenants NEVER reach this — they use the scope-bound {@link get}. */
     getById(id: string): Promise<ApprovalRow | undefined>;
+    /** Operator-only CROSS-tenant pending list (no scope filter) — the unfiltered operator queue across all
+     *  tenants. Tenants use the scope-bound {@link listPending}; this is HTTP-gated to an operator.
+     *  🔴 identical SQL text on both dialects (no placeholders, nothing dialect-specific) — kept as ONE literal
+     *  rather than a `q()` pair so a reader isn't misled into looking for a divergence that isn't there. */
     listPendingAll(): Promise<ApprovalRow[]>;
+    /** Expire pending approvals older than `olderThanMs` (a never-answered operator request). Deliberately GLOBAL
+     *  (NOT scope-filtered): staleness expiry is fleet-level maintenance that protects the worker regardless of
+     *  tenant — a stale row in any scope must be reaped. Scope isolation applies to the per-tenant READ paths, not
+     *  to this maintenance sweep. */
     expireStale(olderThanMs: number): Promise<number>;
 }
+/** approval row → {@link ApprovalRow} — shared by BOTH dialects. design/158 S8 归位 / A12 收编. */
 export declare function mapRow(r: Record<string, unknown>): ApprovalRow;
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBApprovalStore extends SqlApprovalStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgApprovalStore extends SqlApprovalStore {
     constructor(pool: PgPool);
 }

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

@@ -1,6 +1,11 @@
 import { parseJsonStrict as parseJson, toIsoOrNull as iso } from "./sql-row-helpers.js";
 import { pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** PG translation of the `approval` DDL in tidb-pool.ts SCHEMA_STATEMENTS (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  inline KEY→separate CREATE INDEX).
+ *
+ *  SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ *  drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead. */
 export const PG_APPROVAL_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS approval (
      id          VARCHAR(64)  NOT NULL,
@@ -24,18 +29,24 @@ export const PG_APPROVAL_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_approval_status ON approval (status)`,
     `CREATE INDEX IF NOT EXISTS idx_approval_scope_status ON approval (scope, status)`,
 ];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_APPROVAL_SCHEMA)
         await pool.query(stmt);
 }
+/** Dual-dialect durable approval store. See the file header for the dialect-delta ledger. */
 export class SqlApprovalStore {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
+     *  (codex R4-H2 — the approval `args` is the operator's review surface and must agree with the
+     *  policy-executed args at the NUL position). */
     json(value, label) {
         return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
     }
@@ -54,16 +65,23 @@ export class SqlApprovalStore {
         ]);
     }
     async getStatus(id, scope) {
+        // null-safe scope match (`<=>` / `IS NOT DISTINCT FROM`): a NULL scope row (legacy / untenanted run) is
+        // matched by a NULL scope arg, and a tenant's scope NEVER matches another tenant's — the single-DB fleet
+        // read guard (defense-in-depth).
         const { rows } = await this.db.query(this.q("SELECT status, reason, decided_by FROM approval WHERE id = ? AND scope <=> ?", "SELECT status, reason, decided_by FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
         const r = rows[0];
         if (!r)
             return undefined;
         return { status: r.status, reason: r.reason ?? null, decidedBy: r.decided_by ?? null };
     }
+    /** Apply a terminal decision, but only to a still-pending row (CAS). Returns whether it applied. The scope
+     *  guard (null-safe) is carried on the operator path too for consistency with the read paths. */
     async decide(id, scope, decision, reason, decidedBy) {
         const res = await this.db.query(this.q("UPDATE approval SET status = ?, reason = ?, decided_by = ?, decided_at = ? WHERE id = ? AND scope <=> ? AND status = 'pending'", "UPDATE approval SET status = $1, reason = $2, decided_by = $3, decided_at = $4 WHERE id = $5 AND scope IS NOT DISTINCT FROM $6 AND status = 'pending'"), [decision, reason, decidedBy, new Date(), id, scope]);
         return res.affected === 1;
     }
+    /** Pending approvals (operator queue), scoped to one tenant (single-DB fleet read guard, null-safe), optionally
+     *  further filtered to one owner. */
     async listPending(scope, owner) {
         const { rows } = owner
             ? await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? AND owner = ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 AND owner = $2 ORDER BY created_at ASC"), [scope, owner])
@@ -74,14 +92,25 @@ export class SqlApprovalStore {
         const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ? AND scope <=> ?", "SELECT * FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
         return rows[0] ? mapRow(rows[0]) : undefined;
     }
+    /** Operator-only CROSS-tenant by-id read (no scope filter). The F4 operator queue serves/decides across
+     *  tenants by design; the HTTP layer gates this to an operator and then re-binds decide() to the row's OWN
+     *  scope. Tenants NEVER reach this — they use the scope-bound {@link get}. */
     async getById(id) {
         const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ?", "SELECT * FROM approval WHERE id = $1"), [id]);
         return rows[0] ? mapRow(rows[0]) : undefined;
     }
+    /** Operator-only CROSS-tenant pending list (no scope filter) — the unfiltered operator queue across all
+     *  tenants. Tenants use the scope-bound {@link listPending}; this is HTTP-gated to an operator.
+     *  🔴 identical SQL text on both dialects (no placeholders, nothing dialect-specific) — kept as ONE literal
+     *  rather than a `q()` pair so a reader isn't misled into looking for a divergence that isn't there. */
     async listPendingAll() {
         const { rows } = await this.db.query("SELECT * FROM approval WHERE status = 'pending' ORDER BY created_at ASC");
         return rows.map(mapRow);
     }
+    /** Expire pending approvals older than `olderThanMs` (a never-answered operator request). Deliberately GLOBAL
+     *  (NOT scope-filtered): staleness expiry is fleet-level maintenance that protects the worker regardless of
+     *  tenant — a stale row in any scope must be reaped. Scope isolation applies to the per-tenant READ paths, not
+     *  to this maintenance sweep. */
     async expireStale(olderThanMs) {
         const cutoff = new Date(Date.now() - olderThanMs);
         const res = await this.db.query(this.q("UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = ? " +
@@ -90,6 +119,7 @@ export class SqlApprovalStore {
         return res.affected;
     }
 }
+/** approval row → {@link ApprovalRow} — shared by BOTH dialects. design/158 S8 归位 / A12 收编. */
 export function mapRow(r) {
     return {
         id: String(r.id),
@@ -106,11 +136,13 @@ export function mapRow(r) {
         decidedAt: iso(r.decided_at),
     };
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBApprovalStore extends SqlApprovalStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgApprovalStore extends SqlApprovalStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/background-agent-store-sql.d.ts

@@ -1,3 +1,34 @@
+/**
+ * BackgroundAgentStore SQL twins(design/151 S1 server 半场,[1503] 提货单②)——core
+ * `RunnerDeps.backgroundAgentStore` / `SubagentToolOptions.background.agentStore` 的 TiDB/PG
+ * 双方言实现:每个后台子代(`a*` 句柄)一行 durable 执行记录。
+ *
+ * 语义对齐真源 = core `InMemoryBackgroundAgentStore`(dist/core/background-agent-store.js),
+ * 契约四条([1503] 必守):
+ *  1. `put` create-once:重复 (scope, handle) 键 → `BackgroundAgentStoreError("agent_record.already_exists")`
+ *     (唯一键原子,多副本安全);scope 缺席/空串拒收(与 core 同文案——default-deny 谓词下无 scope 的
+ *     行会经 fallback 面变成公共可读)。
+ *  2. `update` rev-CAS:整行替换,`WHERE … AND rev = expect.rev`,命中即 `rev = expect.rev + 1`;
+ *     未命中 false(心跳静默主体在 core 调用侧,store 侧诚实——同 roster 语义条 3,绝不吞成假成功)。
+ *  3. `listBySession`/`listByScope` content-free:只 SELECT 摘要列(绝不拉 record_json——finalOutput/
+ *     recentSteps 可能是大 blob);session 锚 = `sessionScoped ? owner : parentSessionId`,写入时物化为
+ *     `session_anchor` 列(anchor 为 NULL 的行 `= ?` 恒假 = core `anchor !== sessionId` 同义)。
+ *  4. `delete` 条件删(可选 rev CAS);`reap` 三策略与 core 逐条同形(staleRunning 翻 failed 走
+ *     rev-CAS 逐行,竞态输了跳过不计;terminal maxAge/keep 按 spawnedAt DESC)。[1522] LOW6 记账:裸
+ *     `reap` 的批删 IN 无上界、stale 臂全量拉 record_json——server 自己的 retention 只走
+ *     reapDurableAgents(core 编排,不触这两条);第三方直调超大 scope 时自行分批。
+ *
+ * 行形:`record_json` = 全量真源(get 逐位读回);查询/谓词列全是投影,写入时从 record 物化
+ * (展示列 name/agent_type 截到列宽 + PG 侧过 lossy 清洗——真源仍在 record_json;身份键列
+ * scope/handle/owner/session 锚**不清洗不截断**:改写身份键会让行与 engine 查询键错位,含不可存
+ * 字节的身份键=写入失败 fail-loud,与 [1439] 协议数据拒绝式同向)。
+ * PG unstorable bytes([1439] 三层定谳):record/usage 走 `pgSafeJsonStringify`(观测/内容面 lossy
+ * U+FFFD,与 run 行/journal 同族;终报含真 NUL 的病态输入换替换标记,内容面不失行);TiDB TEXT 存 verbatim。
+ *
+ * 键列 = 字节等价(TiDB VARBINARY / PG COLLATE "C"——roster F2 同案:PAD SPACE/大小写近撞不得穿过
+ * scope 隔离键)。`listReapScopes()` 是 server 侧扩展(非 core 接口)——reaper 的 DISTINCT-scope 枚举,
+ * 与 workflow-run store 的 reapAllScopes 同姿势。
+ */
 import type { Pool } from "mysql2/promise";
 import { type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentStore } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
@@ -21,6 +52,9 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
+    /** core 1.383([1565] 提货单)REQUIRED 新方法——原子守卫 CAS(claim 的 reservation/rollback/finalize
+     *  绑定字段态非仅 rev:rev 可因无关写移动而字段义已变)。语义逐字对齐 core InMemoryBackgroundAgentStore
+     *  ({@link parkGuardConditions} 顶注)。 */
     updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
         status?: BackgroundAgentRecord["status"];
@@ -32,7 +66,22 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     delete(handle: string, scope: string, expect?: {
         rev: number;
     }): Promise<boolean>;
+    /** 🔴 返回值语义 = **受影响的不同行数**,不是「翻转数 + 删除数」的和(core 1.411 起)。
+     *
+     *  core 1.411 把自己 InMemory 的 `return touched + doomed.size` 改成
+     *  `return new Set([...flippedKeys, ...doomed]).size` —— 因为一行可能在**同一轮** reap 里既被翻转
+     *  (stale running → failed)、又因为翻转后变成终态而落进 maxAge/keep 的删除集,旧写法把它算了两次。
+     *  这条被真双库对拆套件当场抓到(升 core 1.411 后 `tidb: reaped 计数: expected 4 to be 3`,core 1.404
+     *  下同文件全绿 —— A/B 判明是 core 的语义修,我们跟上)。
+     *
+     *  ⚠️ 两个引擎**机制不同但语义一致**:PG 有 `DELETE … RETURNING handle`,可以单语句拿到真被删的 handle
+     *  直接并入同一个 Set;TiDB/MySQL **没有 RETURNING**,`affectedRows` 只给数量不给身份,所以按「是否已在
+     *  翻转集里」把 doomed 拆两批删 —— 重叠那批照样真删、只是不再计数。两边都不能用「doomed.size 当删除数」
+     *  近似:并发写者(真心跳复活)会让 `status <> 'running'` 守卫少删几行,那时 doomed.size 会虚高。 */
     reap(scope: string, now: number, opts?: ReapOpts): Promise<number>;
+    /** core 1.368([1516]②)可选接口成员落位(原 server 扩展 listReapScopes 更名对齐):当前持行
+     *  scope 枚举——reaper 的 per-scope 联合 reap 入口。JS 侧 sort 与 core InMemory 逐字节同序
+     *  (SQL ORDER BY 按 collation,非码元序)。 */
     listScopes(): Promise<string[]>;
 }
 export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
@@ -43,6 +92,8 @@ export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
+    /** core 1.383([1565] 提货单)REQUIRED 新方法(TiDB twin 同案注释)。PG 侧占位符是显式编号 `$N`
+     *  (不像 TiDB `?` 靠数组顺序)——`n` 是跑动计数器,只在真正消耗一个占位符(非 IS NULL 分支)时前增。 */
     updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
         status?: BackgroundAgentRecord["status"];
@@ -54,7 +105,11 @@ export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
     delete(handle: string, scope: string, expect?: {
         rev: number;
     }): Promise<boolean>;
+    /** 返回值 = 受影响的**不同行数**(core 1.411 语义;TiDB twin 的方法头注写了完整由来 + A/B 取证)。
+     *  PG 这半有 `DELETE … RETURNING handle`,所以真被删的 handle 直接并进同一个 Set —— 不需要 TiDB 那边的
+     *  「拆两批发」变通,但两边的**结果**必须逐个相等(真双库对拆套件按 core InMemory 的计数逐字比)。 */
     reap(scope: string, now: number, opts?: ReapOpts): Promise<number>;
+    /** core 1.368 可选接口成员(TiDB twin 同案注释)。 */
     listScopes(): Promise<string[]>;
 }
 export {};

package/dist/plugins/background-agent-store-sql.js

@@ -2,16 +2,28 @@ import { BackgroundAgentStoreError, } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 export const BACKGROUND_AGENT_TABLE = "background_agents";
 const SUMMARY_COLS = "handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json";
+/** put/update 共用的投影列(scope_key/handle 键列另拼;record_json 恒最后)。core 1.383([1565] 提货单)
+ *  `updateIf` 的 CAS 守卫需要 `parked_checkpoint_token`/`park_claim_id` 是**专用列**——守卫条件必须在
+ *  数据库层面对当前行状态原子求值,不能只靠 record_json 这个 blob(那要求先读后写,读写之间就是
+ *  CAS 本要堵的竞态窗)。`writerEpoch` 不在此列:updateIf 的 guard 参数集里没有它([1565] 原文/core
+ *  类型签名逐字核对过),只是 record_json 全量对象序列化里随手带上的普通字段,不需要专用列——
+ *  record_json 的写法是 `json(stored)`(stored = `{...record, handle, scope, rev}` 整个对象展开),
+ *  任何 record 上有的字段(含 writerEpoch)天然随之落盘/读回,无需逐字段维护投影列表。 */
 const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, record_json";
-const PROJ_N = PROJ_COLS.split(", ").length;
+const PROJ_N = PROJ_COLS.split(", ").length; // F5: WHERE 占位符序号从列数派生,列序变更单点同步
 function assertScope(record) {
     if (record.scope === undefined || record.scope === "") {
+        // core InMemory 同文案(default-deny 谓词下无 scope 行=经 fallback 面公共可读,写入即拒)
         throw new Error("BackgroundAgentStore.put: refusing a row without a scope (world-readable through the fallback)");
     }
 }
+/** stored 形归一(core put/update 语义:handle/scope/rev 以参数为准,record_json 存归一后的整行)。 */
 function storedForm(record, handle, scope, rev) {
     return { ...record, handle, scope, rev };
 }
+/** 投影参数(键列除外,与 PROJ_COLS 同序)。json 序列化器/展示文本清洗器按方言注入([1439]:PG
+ *  lossy 标记,TiDB verbatim)。展示列截到列宽(#3:超长 name 不该让整行 durable 写失败——真源在
+ *  record_json,摘要投影截断是诚实形)。 */
 function projParams(stored, json, text) {
     return [
         stored.scope,
@@ -34,6 +46,7 @@ function projParams(stored, json, text) {
         json(stored),
     ];
 }
+/** 摘要行 → core BackgroundAgentRowSummary(缺席键省略,core toSummary 形逐字;usage 从 usage_json)。 */
 function rowToSummary(r) {
     return {
         handle: String(r.handle),
@@ -53,6 +66,7 @@ function rowToSummary(r) {
             : {}),
     };
 }
+/** core reap 的 staleRunning 翻转形(逐字段照抄 InMemory:summary 只在缺席时补默认句)。 */
 function flippedForm(live, now) {
     return {
         ...live,
@@ -63,6 +77,7 @@ function flippedForm(live, now) {
         updatedAt: now,
     };
 }
+/** terminal doomed 集合(core reap 的 maxAge + keep 两策略;rows 已按 spawnedAt DESC)。 */
 function doomedHandles(rows, now, opts) {
     const doomed = new Set();
     if (opts.maxAgeMs !== undefined) {
@@ -77,6 +92,11 @@ function doomedHandles(rows, now, opts) {
     }
     return doomed;
 }
+/** core 1.383([1565] 提货单,design/153 件3a)`updateIf` 的三个可选守卫条件——dialect-neutral 描述,
+ *  各方言自行渲染成 `?`(TiDB)或 `$N`(PG)占位符。core InMemoryBackgroundAgentStore.updateIf 逐字同源
+ *  (background-agent-store.js:175-187)语义:`value === null` = 该列当前**必须缺席**(SQL `IS NULL`,
+ *  对应 core `live.X !== undefined` 的取反);`value` 是字符串 = 必须**字面相等**;字段整体缺席
+ *  (expect.X === undefined,不在返回数组里)= 不设该条守卫,与该列当前值无关。 */
 function parkGuardConditions(expect) {
     const out = [];
     if (expect.status !== undefined)
@@ -91,12 +111,38 @@ function reapInert(opts) {
     return !opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined);
 }
 function limitClause(limit) {
+    // #2 病态边界与 core slice 语义对齐:Infinity=全量(无 LIMIT),NaN/-Infinity=空(LIMIT 0)
     if (limit === undefined || limit === Infinity)
         return "";
     const n = Math.floor(limit);
     return ` LIMIT ${Number.isFinite(n) ? Math.max(0, n) : 0}`;
 }
+/* ┌─ 历史:曾经的运行期 ADD COLUMN 迁移腿(已折进 CREATE,2026-07-26 clay 裁「删库重建」)──────────┐
+ * 两个 ensure 曾在每次 boot 给 `background_agents` 补三列;现已全部折叠为 CREATE TABLE 里的列定义。
+ * 保留由来,因为它解释了这些列**为什么存在**,以及当年为什么 TiDB 腿用探针而不是 `IF NOT EXISTS`:
+ *
+ * ① root_session_id(core 1.367 δ,additive):1.248 建的存量表没有这列,靠迁移补。
+ * ② parked_checkpoint_token / park_claim_id(core 1.383,[1565] 提货单 / design/153 件3a,ε,additive):
+ *    1.382 前建的表没有这两列。它们**必须是专用列**(不能只躺在 record_json 里)的理由见 {@link PROJ_COLS}
+ *    顶注:`updateIf` 的 CAS 守卫要在数据库层面对当前行状态原子求值。
+ *
+ * ③ 为什么 TiDB 腿曾是 `information_schema.COLUMNS` **探针 + ALTER** 两步,而不是一条
+ *    `ADD COLUMN IF NOT EXISTS`(复审 F2):**MySQL 8 没有该语法**(TiDB/MariaDB 才有),而本仓
+ *    MySQL-protocol 口径要求可移植——tidb-pool.ts COLUMN_MIGRATIONS 同姿势。PG 腿则本来就用 IF NOT EXISTS。
+ *    ⚠️ 这个探针姿势有一个真实缺陷([1522] LOW5,当年如实记并判定可接受):探针→ALTER **不是原子的**,
+ *    多副本并发首 boot 存在竞态窗——两个副本双双探到缺列、一方 ALTER 赢、另一方 ALTER 撞
+ *    「column exists」砖**当次** boot;下次 boot 探到列在即自愈。
+ *    → 折叠后该窗**消失**:新库列由 CREATE TABLE 一次建全,不存在「探到缺列再补」的第二步;
+ *      `CREATE TABLE IF NOT EXISTS` 本身在服务端是单条原子 DDL,并发首 boot 只有「建了」/「已存在」两态。
+ *
+ * ④ 语义位:当年 `root_session_id IS NULL` 兼有「pre-δ 行」一义。删库重建后**不再产生**这类行——NULL
+ *    只剩「该记录没有 root 锚」一义。读侧因此**仍然可达**、一律不动:{@link rowToSummary} 的
+ *    root_session_id 条件展开、listBySession 的 `root_session_id = ?` 第二臂(NULL 行恒不命中)、
+ *    以及 parked 两列的 `IS NULL` 守卫({@link parkGuardConditions}:那是 core 的 CAS 语义,不是迁移遗留)。
+ * └────────────────────────────────────────────────────────────────────────────────────────────┘ */
 export async function ensureTiDBBackgroundAgentSchema(pool) {
+    // VARBINARY 键列(roster F2 同案):scope/handle 的 '=' 必须是纯字节——utf8mb4_bin 仍 PAD SPACE,
+    // 'x' 与 'x ' 会同键。record_json LONGTEXT:终报快照(finalOutput/recentSteps)可超 64K TEXT。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
     handle VARBINARY(190) NOT NULL,
@@ -127,6 +173,7 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
   ) COLLATE utf8mb4_bin`);
 }
 export async function ensurePgBackgroundAgentSchema(q) {
+    // COLLATE "C"(roster F2 双方言对齐):隔离键列的 '=' 必须字节等价。
     await q(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
     scope_key VARCHAR(190) COLLATE "C" NOT NULL,
     handle VARCHAR(190) COLLATE "C" NOT NULL,
@@ -183,6 +230,9 @@ export class TiDBBackgroundAgentStore {
        WHERE scope_key = ? AND handle = ? AND rev = ?`, [...projParams(stored, JSON.stringify, (t) => t), scope, handle, expect.rev]));
         return res.affectedRows === 1;
     }
+    /** core 1.383([1565] 提货单)REQUIRED 新方法——原子守卫 CAS(claim 的 reservation/rollback/finalize
+     *  绑定字段态非仅 rev:rev 可因无关写移动而字段义已变)。语义逐字对齐 core InMemoryBackgroundAgentStore
+     *  ({@link parkGuardConditions} 顶注)。 */
     async updateIf(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
         const guards = parkGuardConditions(expect);
@@ -206,6 +256,18 @@ export class TiDBBackgroundAgentStore {
         const [res] = (await this.pool.query(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?${expect !== undefined ? " AND rev = ?" : ""}`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]));
         return res.affectedRows === 1;
     }
+    /** 🔴 返回值语义 = **受影响的不同行数**,不是「翻转数 + 删除数」的和(core 1.411 起)。
+     *
+     *  core 1.411 把自己 InMemory 的 `return touched + doomed.size` 改成
+     *  `return new Set([...flippedKeys, ...doomed]).size` —— 因为一行可能在**同一轮** reap 里既被翻转
+     *  (stale running → failed)、又因为翻转后变成终态而落进 maxAge/keep 的删除集,旧写法把它算了两次。
+     *  这条被真双库对拆套件当场抓到(升 core 1.411 后 `tidb: reaped 计数: expected 4 to be 3`,core 1.404
+     *  下同文件全绿 —— A/B 判明是 core 的语义修,我们跟上)。
+     *
+     *  ⚠️ 两个引擎**机制不同但语义一致**:PG 有 `DELETE … RETURNING handle`,可以单语句拿到真被删的 handle
+     *  直接并入同一个 Set;TiDB/MySQL **没有 RETURNING**,`affectedRows` 只给数量不给身份,所以按「是否已在
+     *  翻转集里」把 doomed 拆两批删 —— 重叠那批照样真删、只是不再计数。两边都不能用「doomed.size 当删除数」
+     *  近似:并发写者(真心跳复活)会让 `status <> 'running'` 守卫少删几行,那时 doomed.size 会虚高。 */
     async reap(scope, now, opts) {
         if (reapInert(opts))
             return 0;
@@ -214,14 +276,22 @@ export class TiDBBackgroundAgentStore {
             const [stale] = (await this.pool.query(`SELECT handle, record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
                 const live = JSON.parse(String(row.record_json));
+                // rev-CAS 翻转:并发写者(真心跳复活/别副本先翻)赢了就跳过不计——core 单进程无此窗,SQL 侧诚实
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     flipped.add(String(row.handle));
             }
         }
+        // core 1.382([1561] 提货单③;InMemoryBackgroundAgentStore.reap 逐字同源,background-agent-store.js:206
+        // `r.status !== "running" && r.status !== "parked"`):doomed 候选池排除 parked——parked 是非活非终态
+        // (durably suspended pending approval),`doomedHandles` 只按 spawnedAt/settledAt 判定年龄/keep 排名,
+        // 完全不看 status,所以排除必须在这条 SQL WHERE 里做到,不能指望 JS 侧再筛一次(它收到的行里根本
+        // 没带 status 字段)。
         const [term] = (await this.pool.query(`SELECT handle, spawned_at_ms, settled_at_ms FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status <> 'running' AND status <> 'parked' ORDER BY spawned_at_ms DESC, handle DESC`, [scope]));
         const doomed = doomedHandles(term.map((r) => ({ handle: String(r.handle), spawnedAt: Number(r.spawned_at_ms), settledAt: r.settled_at_ms === null ? null : Number(r.settled_at_ms) })), now, opts);
         if (doomed.size === 0)
             return flipped.size;
+        // 去重(见方法头注):本轮已翻转过的 handle 若同时落进 doomed,删它但**不再计数**。
+        // 无 RETURNING ⇒ 拆两批发,靠「哪一批」而不是靠返回的身份来分辨。
         const alreadyCounted = [...doomed].filter((h) => flipped.has(h));
         const newlyAffected = [...doomed].filter((h) => !flipped.has(h));
         const del = async (handles) => {
@@ -230,10 +300,16 @@ export class TiDBBackgroundAgentStore {
         };
         const deletedNew = newlyAffected.length > 0 ? await del(newlyAffected) : 0;
         if (alreadyCounted.length > 0)
-            await del(alreadyCounted);
+            await del(alreadyCounted); // 真删,计数已由 flipped 承担
         return flipped.size + deletedNew;
     }
+    /** core 1.368([1516]②)可选接口成员落位(原 server 扩展 listReapScopes 更名对齐):当前持行
+     *  scope 枚举——reaper 的 per-scope 联合 reap 入口。JS 侧 sort 与 core InMemory 逐字节同序
+     *  (SQL ORDER BY 按 collation,非码元序)。 */
     async listScopes() {
+        // [1522] MED1(两路复审撞车坐实):枚举必须走 **scope_key 字节列**——utf8mb4_bin 的 VARCHAR DISTINCT
+        // 仍 PAD SPACE,尾空格近撞 scope 被塌缩成一个,塌缩掉的分区永不被 reap(行/转录无界)。键纪律
+        // 贯彻到枚举面;VARBINARY 读回 Buffer → utf8 归一。
         const [rows] = (await this.pool.query(`SELECT DISTINCT scope_key FROM ${BACKGROUND_AGENT_TABLE}`));
         return rows.map((r) => (Buffer.isBuffer(r.scope_key) ? r.scope_key.toString("utf8") : String(r.scope_key))).sort();
     }
@@ -246,6 +322,8 @@ export class PgBackgroundAgentStore {
     async put(record) {
         assertScope(record);
         const stored = storedForm(record, record.handle, record.scope, record.rev ?? 0);
+        // create-once:ON CONFLICT DO NOTHING + RETURNING——空 rows = 键已存在(PgQueryFn 无 rowCount,
+        // RETURNING 是双方言里 PG 侧的 affected 判别;错误码路径留给真障碍)。
         const { rows } = await this.q(`INSERT INTO ${BACKGROUND_AGENT_TABLE} (scope_key, handle, ${PROJ_COLS})
        VALUES (${Array.from({ length: PROJ_N + 2 }, (_, i) => `$${i + 1}`).join(", ")})
        ON CONFLICT (scope_key, handle) DO NOTHING RETURNING handle`, [stored.scope, stored.handle, ...projParams(stored, pgSafeJsonStringify, pgSanitizeText)]);
@@ -263,11 +341,13 @@ export class PgBackgroundAgentStore {
        WHERE scope_key = $${PROJ_N + 1} AND handle = $${PROJ_N + 2} AND rev = $${PROJ_N + 3} RETURNING handle`, [...projParams(stored, pgSafeJsonStringify, pgSanitizeText), scope, handle, expect.rev]);
         return rows.length === 1;
     }
+    /** core 1.383([1565] 提货单)REQUIRED 新方法(TiDB twin 同案注释)。PG 侧占位符是显式编号 `$N`
+     *  (不像 TiDB `?` 靠数组顺序)——`n` 是跑动计数器,只在真正消耗一个占位符(非 IS NULL 分支)时前增。 */
     async updateIf(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
         const setParams = projParams(stored, pgSafeJsonStringify, pgSanitizeText);
         const guards = parkGuardConditions(expect);
-        let n = setParams.length + 3;
+        let n = setParams.length + 3; // + scope_key/handle/rev,三条基础守卫已固定占用 setParams.length+1..+3
         const guardSql = guards.map((g) => (g.value === null ? `${g.column} IS NULL` : `${g.column} = $${++n}`)).join(" AND ");
         const guardParams = guards.filter((g) => g.value !== null).map((g) => g.value);
         const { rows } = await this.q(`UPDATE ${BACKGROUND_AGENT_TABLE} SET ${PROJ_COLS.split(", ").map((c, i) => `${c} = $${i + 1}`).join(", ")}
@@ -288,6 +368,9 @@ export class PgBackgroundAgentStore {
         const { rows } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2${expect !== undefined ? " AND rev = $3" : ""} RETURNING handle`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]);
         return rows.length === 1;
     }
+    /** 返回值 = 受影响的**不同行数**(core 1.411 语义;TiDB twin 的方法头注写了完整由来 + A/B 取证)。
+     *  PG 这半有 `DELETE … RETURNING handle`,所以真被删的 handle 直接并进同一个 Set —— 不需要 TiDB 那边的
+     *  「拆两批发」变通,但两边的**结果**必须逐个相等(真双库对拆套件按 core InMemory 的计数逐字比)。 */
     async reap(scope, now, opts) {
         if (reapInert(opts))
             return 0;
@@ -300,16 +383,20 @@ export class PgBackgroundAgentStore {
                     affected.add(String(row.handle));
             }
         }
+        // core 1.382([1561] 提货单③;TiDB twin 同案注释)——doomed 候选池排除 parked。
         const { rows: term } = await this.q(`SELECT handle, spawned_at_ms, settled_at_ms FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status <> 'running' AND status <> 'parked' ORDER BY spawned_at_ms DESC, handle DESC`, [scope]);
         const doomed = doomedHandles(term.map((r) => ({ handle: String(r.handle), spawnedAt: Number(r.spawned_at_ms), settledAt: r.settled_at_ms === null ? null : Number(r.settled_at_ms) })), now, opts);
         if (doomed.size === 0)
             return affected.size;
         const { rows: deleted } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status <> 'running' AND status <> 'parked' AND handle IN (${[...doomed].map((_, i) => `$${i + 2}`).join(", ")}) RETURNING handle`, [scope, ...doomed]);
         for (const r of deleted)
-            affected.add(String(r.handle));
+            affected.add(String(r.handle)); // 同一 Set ⇒ 翻转+删除的同一行只算一次
         return affected.size;
     }
+    /** core 1.368 可选接口成员(TiDB twin 同案注释)。 */
     async listScopes() {
+        // [1522] MED1(TiDB twin 同案注):枚举走 COLLATE "C" 的 scope_key 键列——非确定性缺省 collation
+        // 部署下 VARCHAR DISTINCT 同构塌缩,键列字节确定。
         const { rows } = await this.q(`SELECT DISTINCT scope_key FROM ${BACKGROUND_AGENT_TABLE}`);
         return rows.map((r) => String(r.scope_key)).sort();
     }