@sema-agent/server 7.29.0 → 7.30.0

package/dist/plugins/memory-key-guards.js

@@ -1,13 +1,64 @@
-/** R5(车A [3191] 欠账,批γ 落地):memory-engine 键宽写前守卫。
- *  列宽收窄后,模型可控的条目名(slug)超宽此前落裸 SQL 错(PG `value too long`)或非严格 MySQL
- *  静默截断(截断=两个不同 slug 折叠成一行=条目互串,最危险形)。写前响亮拒,错误可分类。
- *  列宽同源门=test/key-width-guards.test.ts(守卫常量 vs 两方言 DDL 逐字对表)。 */
+/** R5(车A [3191] 欠账,批γ 落地;#271 件1 补齐写口):memory 面的键宽写前守卫。
+ *  列宽收窄后,模型/调用方可控的键(条目名 slug、租户盘 scope)超宽此前落裸 SQL 错(PG
+ *  `value too long`)或非严格 MySQL 静默截断(截断=两个不同的键折叠成同一行=**条目互串 / 两个租户
+ *  的盘塌成一个**,最危险形)。写前响亮拒,错误可分类。
+ *  列宽同源门=test/key-width-guards.test.ts(守卫常量 vs 两方言 DDL 逐字对表);写口在场门=同文件
+ *  「#271 件1」组(超宽键一条写语句都不许发出 seam)。
+ *
+ *  **本文件是这两个宽度的唯一属主**(#271 件1):scope 守卫此前住在 `src/memory-scope.ts`,只被
+ *  `memoryScopeFor` 的产出处消费,而 store 写口全无——同一个列宽有两个居所、两半消费面,正是
+ *  「守卫在位≠写口接上」那类缺口的温床。`memory-scope.ts` 现在只**再导出**本文件的这两个符号
+ *  (旧 import 路径逐字不变)。 */
 /** memory-engine entry 表 `slug` 列宽(两方言 VARCHAR(512) 同宽;(scope,slug) UNIQUE 键预算注在 DDL)。 */
 export const MEMORY_SLUG_COLUMN_CHARS = 512;
+/** memory 面 `scope` 列宽(两方言 VARCHAR(190) 同宽:engine 的 entry/cursor 两表 + memory-sync 的
+ *  sync_cursor/push_queue/history)。`formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
+ *  **膨胀**——非 ASCII principal 编码后可超列宽,故产出处与写口两道都要判。 */
+export const MEMORY_SCOPE_COLUMN_CHARS = 190;
+/**
+ * 键宽的**计数口径**(codex 对抗复审 M1,#271 件1 验真后修):两方言的 `VARCHAR(n)` 数的都是
+ * **字符 = Unicode 码点**(PG varchar(n) / MySQL-protocol utf8mb4 VARCHAR(n) 同口径,后者每字符
+ * 最多 4 字节、astral 字符仍算 1)。而 JS 的 `string.length` 数的是 **UTF-16 code unit** —— 一个
+ * emoji 算 2。照 `.length` 判会把「库里只占 96 字符」的 scope 按 192 拒掉:守卫从「防截断」变成
+ * 「误伤合法窄键」,方向反了。
+ *
+ * (孤立代理项这种**不可存**字节不归本函数管——那是 `pgHasUnstorable` 的拒绝式,两条判据各司其职。)
+ */
+function widthChars(v) {
+    return [...v].length;
+}
 export function assertSlugWidth(slug) {
-    if (slug.length > MEMORY_SLUG_COLUMN_CHARS) {
+    const n = widthChars(slug);
+    if (n > MEMORY_SLUG_COLUMN_CHARS) {
         throw new Error(`memory entry slug exceeds ${MEMORY_SLUG_COLUMN_CHARS} characters (the slug column width both SQL dialects pin); ` +
-            `got ${slug.length} — shorten the entry name`);
+            `got ${n} — shorten the entry name`);
+    }
+}
+export function assertMemoryScopeWidth(scope) {
+    const n = widthChars(scope);
+    if (n > MEMORY_SCOPE_COLUMN_CHARS) {
+        throw new Error(`memory scope exceeds ${MEMORY_SCOPE_COLUMN_CHARS} characters after segment encoding (the scope column width ` +
+            `both SQL dialects pin); got ${n} — use a shorter principal/projectId (non-ASCII characters expand ~9x when encoded)`);
+    }
+}
+/**
+ * 一个 entry 写(add / update)的两个键宽一起判 —— 两方言的 `applyOne` 在**任何 I/O 之前**调用它。
+ *
+ * 为什么两条腿共用一个入口而不是各自展开:add 与 update 写的是**同两列**(update 的
+ * `SET scope = …, slug = …` 会改盘也会改名),R5 那批只护住了 add ⇒ 一次改名就能把超宽 slug 送进
+ * DB。一个入口=两条腿不会再各自漂。
+ *
+ * 返回**字符串**而不是抛:两方言的 `applyPatches` 契约是「冲突进 report,不抛」(与
+ * `unstorable_bytes` 的拒绝式同族——后端能力差异诚实暴露,重试恒同答=幂等成立)。`undefined` = 过。
+ */
+export function memoryEntryKeyWidthRefusal(scope, slug) {
+    try {
+        assertMemoryScopeWidth(scope);
+        assertSlugWidth(slug);
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
     }
+    return undefined;
 }
 //# sourceMappingURL=memory-key-guards.js.map

package/dist/plugins/memory-sync-store-pg.js

@@ -1,4 +1,5 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { assertMemoryScopeWidth } from "./memory-key-guards.js"; // #271 件1:scope 列宽写前守卫(engine 两表同守)
 /** Table names (single source). SAME names as the TiDB twin (the two dialects never share one DB). */
 export const PG_MEMORY_SYNC_TABLES = {
     syncCursor: "agent_memory_engine_sync_cursor",
@@ -63,6 +64,9 @@ export class PgMemorySyncStore {
         };
     }
     async putCursor(cursor) {
+        // #271 件1:scope 是 PK 的一半(varchar(190))——超宽此前落不可分类的裸 22001,而 MySQL-protocol
+        // twin 上同一份数据会**静默截断**成另一个盘的基线。两方言同点、同文案拒(engine 两表同守)。
+        assertMemoryScopeWidth(cursor.scope);
         // PK (scope,peer) is the table's ONLY unique key ⇒ ON CONFLICT has exactly one target, no
         // hijack face (纪律:the entries-table ban on blind upserts does NOT apply here).
         await this.query(`INSERT INTO ${PG_MEMORY_SYNC_TABLES.syncCursor} (scope, peer, base_revs, updated_at_ms)
@@ -74,6 +78,7 @@ export class PgMemorySyncStore {
     }
     // ── push queue ─────────────────────────────────────────────────────────────
     async enqueue(item) {
+        assertMemoryScopeWidth(item.scope); // #271 件1:出站队列行的 scope 截断 = 推给对端时说错了盘
         // Plain INSERT, fail-loud on a duplicate id: the caller mints uuidv7 per enqueue, so a dup is a
         // caller bug (or a replay the caller must decide about) — never silently absorbed here.
         await this.query(`INSERT INTO ${PG_MEMORY_SYNC_TABLES.pushQueue} (id, scope, entry_id, payload, attempts, next_attempt_at_ms, last_error)

package/dist/plugins/memory-sync-store-tidb.js

@@ -1,4 +1,5 @@
 import { historyRowFrom } from "./memory-sync-store-pg.js";
+import { assertMemoryScopeWidth } from "./memory-key-guards.js"; // #271 件1:scope 列宽写前守卫(engine 两表同守)
 /** Table names (single source) — SAME names as PG_MEMORY_SYNC_TABLES (the two dialects never share
  *  one database). */
 export const TIDB_MEMORY_SYNC_TABLES = {
@@ -64,6 +65,9 @@ export class TiDBMemorySyncStore {
         };
     }
     async putCursor(cursor) {
+        // #271 件1:scope 是 PK 的一半(VARCHAR(190))——非严格 MySQL 的静默截断会把两个盘的同步基线
+        // 折叠成一行(对账基线互串),写前响亮拒(engine 两表同守;Pg twin 同注)。
+        assertMemoryScopeWidth(cursor.scope);
         // The table's ONLY unique key is PK(scope,peer) ⇒ ON DUPLICATE KEY UPDATE has exactly one
         // possible trigger — no hijack face (the entries-table ban does NOT apply; see header).
         await this.pool.query(`INSERT INTO ${TIDB_MEMORY_SYNC_TABLES.syncCursor} (scope, peer, base_revs, updated_at_ms)
@@ -72,6 +76,7 @@ export class TiDBMemorySyncStore {
     }
     // ── push queue ─────────────────────────────────────────────────────────────
     async enqueue(item) {
+        assertMemoryScopeWidth(item.scope); // #271 件1:出站队列行的 scope 截断 = 推给对端时说错了盘
         // Plain INSERT, fail-loud on a duplicate id (ER_DUP_ENTRY 1062) — caller mints uuidv7 per
         // enqueue, a dup is a caller bug, never silently absorbed. Same posture as the PG twin.
         await this.pool.query(`INSERT INTO ${TIDB_MEMORY_SYNC_TABLES.pushQueue} (id, scope, entry_id, payload, attempts, next_attempt_at_ms, last_error)

package/dist/plugins/pg-pool.js

@@ -39,6 +39,7 @@ import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
+import { ensurePgRetentionSchema } from "./retention-store-sql.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -397,6 +398,9 @@ export async function ensurePgSchema(pool) {
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         // #193 车4 件1:durable leader-run 登记表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。同上绑法。
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));
+        // #270 车1:托管留存执行面四表(审计/hold/sweep 租约/墓碑;MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS
+        // 展开)。同上绑法 —— DDL 跑在**同一条** client 上,advisory lock 的 session 语义不受影响。
+        await ensurePgRetentionSchema((text, params) => client.query(text, params));
     }
     finally {
         if (locked) {

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

@@ -48,6 +48,8 @@ export declare class PgSessionStorage extends BaseSessionStorage {
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
+    /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    readonly retention: import("@sema-agent/core").RetentionDeclaration;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);

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

@@ -27,6 +27,7 @@ import { contentForkRelation, fastForwardSharedContentDiverged } from "../sessio
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注)
  } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
+import { MANAGED_RETENTION } from "./retention-store-sql.js";
 /** 判据属主 = `sql-errors.ts`(A-032 P1-①)。 */
 const isDupKey = isPgUniqueViolation;
 /** node-pg parses jsonb → object already; only strings need JSON.parse, everything else passes through. */
@@ -207,6 +208,8 @@ export class PgSessionStorage extends BaseSessionStorage {
  */
 export class PgSessionStore {
     pool;
+    /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    retention = MANAGED_RETENTION;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -0,0 +1,254 @@
+/**
+ * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT(design/158 A12;先例 =
+ * `retention-store-sql.ts` 本身)。#270 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
+ *
+ * ── 为什么与车1 的 `retention-store-sql.ts` 分家(而不是往那只店上再挂三组方法)────────────────────
+ * 车1 那只店是 core `ManagedRetentionCapability` 的**实现体**:它的每一个公开方法都是一次**破坏性**
+ * 事务(hold 锁读 → 变更+墓碑 → 审计行,同 commit 同 rollback)。本文件三组口全部是**非破坏**的:
+ *   · sweep 租约(§3):互斥机制,一行 CAS,与任何业务表无关;
+ *   · legal-hold 的**放置/解除**(§5):operator 路由的写点,只改 `retention_hold.held` 一列;
+ *   · 审计表的**读**(§6 查询面)与**非破坏行的写**(`audit_only`/`skipped_legal_hold`/`failed`/`hold_*`
+ *     —— 属主是 lane 与路由,它们没有「删了没记」的窗口)。
+ * 三者的消费者也不同(lane / operator 路由),而车1 那只店的每个方法都**必须**由 lane 带着审计上下文调。
+ * 混进同一只对象会让「拿到这只店 = 能删数据」这条读法失真 —— 审计读面与 hold 路由拿到的应当是一把
+ * **删不了任何东西**的钥匙。
+ *
+ * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
+ *   - `?` 占位符 vs `$n`;
+ *   - 幂等插入:`INSERT IGNORE` vs `ON CONFLICT (…) DO NOTHING`;
+ *   - upsert:`ON DUPLICATE KEY UPDATE col = VALUES(col)` vs `ON CONFLICT (…) DO UPDATE SET col = EXCLUDED.col`;
+ *   - 条件自增:`IF(cond, 0, 1)` vs `CASE WHEN cond THEN 0 ELSE 1 END`(本文件不用 —— 见 `acquire` 顶注:
+ *     自增判据在**应用层**算,因为它同时要产出返回给调用方的 token);
+ *   - 事务动词:平凡 `begin()`(理由逐字见车1 `SqlRetentionStore.tx` 的头注:`BEGIN PESSIMISTIC` 是 TiDB
+ *     专有语法,发到普通 MySQL 上是语法错,而发车门的 canonical `TIDB_TEST_URL` 指向的正是普通 MySQL)。
+ *   - schema 属主:**四张表全部由车1 的 `retention-store-sql.ts` 建**(`TIDB_RETENTION_STATEMENTS` /
+ *     `PG_RETENTION_SCHEMA`)。本文件一条 DDL 都不发 —— 「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
+ *     的实测结论:第二个属主的 `IF NOT EXISTS` 会静默吞掉列/索引差异)。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver, type SqlExec } from "./sql-driver.js";
+import { type RetentionAuditAction } from "./retention-store-sql.js";
+/** 审计读面的单页上界(与 roster 名册窗同姿势:读面要有界)。 */
+export declare const RETENTION_AUDIT_MAX_LIMIT = 200;
+/** 审计读面的缺省页大小。 */
+export declare const RETENTION_AUDIT_DEFAULT_LIMIT = 50;
+/** 一次抢/续租的结果。`held:false` = 本 tick 由别人持租(零写,静默跳过 —— 不是错误)。 */
+export type RetentionLeaseClaim = {
+    held: true;
+    fencingToken: number;
+    holder: string;
+} | {
+    held: false;
+    holder: string;
+    expiresAtMs: number;
+};
+/** 一行审计(读面投影;列名→驼峰,BIGINT 统一 `Number`)。 */
+export interface RetentionAuditRow {
+    id: number;
+    domain: string;
+    action: RetentionAuditAction;
+    mode: string;
+    policyDays: number;
+    fencingToken: number | null;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+    executedAtMs: number;
+    error: string | null;
+}
+/** 非破坏性审计行的写入形(破坏性三词由车1 的店在删除同事务内写 —— 见文件头)。 */
+export interface RetentionAuditAppend {
+    domain: string;
+    action: Extract<RetentionAuditAction, "audit_only" | "skipped_legal_hold" | "failed" | "hold_placed" | "hold_released">;
+    mode: string;
+    policyDays: number;
+    fencingToken: number | null;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+    error?: string;
+}
+/**
+ * 执行面非破坏性三组口的**公开面**(消费方 —— boot 的 lane、operator 路由、`StoreBackend` 座席 —— 一律
+ * 依赖本接口,不依赖下面那只类)。
+ *
+ * 🔴 为什么值得单列一个接口:类身上带 `protected db`,于是它在 TS 里是**名义**类型 —— 任何结构等价的
+ * 实现(测试假店、将来的第二种后端)都满足不了它,只能靠 `as unknown as` 走私进去,而那种双重断言把
+ * 字段检查整段关灯(`type-hygiene-gate` 数的正是它)。接口一列,假店就是**真的**满足同一份契约:
+ * 接口加一个方法,假店当场编译红。
+ */
+export interface RetentionLaneStore {
+    acquire(holder: string, ttlMs: number, nowMs: number): Promise<RetentionLeaseClaim>;
+    renew(holder: string, fencingToken: number, ttlMs: number, nowMs: number): Promise<boolean>;
+    release(holder: string): Promise<void>;
+    setHold(input: {
+        domain: string;
+        held: boolean;
+        placedBy?: string;
+        note?: string;
+        nowMs: number;
+    }): Promise<void>;
+    /** 状态变更 + 治理审计行,**同一个事务**(理由见实现顶注)。operator 路由**只许**走这一只。 */
+    setHoldAudited(input: {
+        domain: string;
+        held: boolean;
+        placedBy?: string;
+        note?: string;
+        nowMs: number;
+        audit: RetentionAuditAppend;
+    }): Promise<void>;
+    holdInForce(domain: string): Promise<boolean>;
+    appendAudit(row: RetentionAuditAppend, nowMs: number): Promise<void>;
+    listAudit(input: {
+        domain?: string;
+        limit: number;
+        beforeId?: number;
+    }): Promise<RetentionAuditRow[]>;
+}
+/**
+ * 执行面的非破坏性 SQL 三组口(双方言;绑定类在文件底部)。
+ *
+ * 🔴 本类**删不掉任何业务数据** —— 它写的只有 `retention_lease` 的一行、`retention_hold` 的一列、
+ * 与 `retention_audit` 的追加行。破坏性的三条腿在车1 的 `SqlRetentionStore` 上,拿本对象够不着。
+ */
+export declare class SqlRetentionLaneStore implements RetentionLaneStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    /** 方言取文(两条语句都写在调用点;A12 判据)。 */
+    protected q(tidb: string, pg: string): string;
+    /**
+     * 抢/续租一次(单行 CAS)。抢到 ⇒ `{held:true, fencingToken}`;别人正持着 ⇒ `{held:false}`,调用方
+     * **本 tick 零写静默跳过**。
+     *
+     * 事务三步,一步不能省:
+     *  ① `INSERT IGNORE`(PG:`ON CONFLICT DO NOTHING`)一条 `expires_at_ms = 0` 的**哨兵行** —— 它永远
+     *     不会改写一条既存租约(两方言的这两个动词都只在缺行时写);
+     *  ② `SELECT … FOR UPDATE` —— 行现在必定存在,锁真的拿得到;
+     *  ③ 判 + `UPDATE`,同事务提交。
+     *
+     * 🔴 为什么必须先造行、而不是「一条 `UPDATE … WHERE expires_at_ms < now OR holder = self`」了事
+     * (设计稿 §3 写的正是那条裸 UPDATE,本实现是它的**收口**,与车1 hold 哨兵是同一条教训):裸 UPDATE
+     * 在**空表**上影响 0 行 —— 于是首启的两个副本都读到「没抢到」,lane 在一个从没跑过的部署上**永远不
+     * 起**(静默,读数是"每 tick 跳过",看上去像"别人在跑")。补一条无条件 INSERT 又会在两副本同拍首启时
+     * 撞 PK。哨兵 + 行锁把两件事一次解决,并且顺带让 fencing token 的自增判据可以在应用层算。
+     *
+     * 🔴 fencing token 只在**抢租**(holder 变了)时自增,续租不动它:token 的语义是「第几轮**执行权**」,
+     * 一个持续持租的副本跑的是同一段连续执行,给它每 tick 换号会让审计上「同一轮的行」看起来跨了很多轮。
+     *
+     * @param holder 本副本的身份(instanceId);同一 holder 再来 = 续租。
+     * @param ttlMs  租约时长 = 2× sweep 间隔(§3)。
+     */
+    acquire(holder: string, ttlMs: number, nowMs: number): Promise<RetentionLeaseClaim>;
+    /**
+     * 「这一轮的执行权还在我手上吗」**并同时续租** —— 每 domain 处理前调一次(§3 丢租即停)。
+     * 返回 `false` = 不再属于我 ⇒ 调用方当场中止本轮。
+     *
+     * 判据三合取写进**一条 CAS 的 WHERE**:holder 是我 ∧ fencing token 还是本轮那个 ∧ **尚未过期**。
+     *  · 第三项是承重的:租约过期而 holder 还写着我,必须读成**不再属于我**(fail-closed)——另一个副本
+     *    随时可能抢走,两个副本同时跑三方法是这条腿最不能出的事。
+     *  · 「复核」与「续租」合成一条语句而不是先读后写(codex 对抗复审 R1-[high],验真后改):
+     *    ① 读+写两条语句之间有窗口,而 CAS 的谓词与更新在引擎里是原子的;
+     *    ② 更要紧的是**续租本身**:`startRetentionLane` 的重入守卫会跳过下一 tick,于是一轮的续租机会
+     *       只有轮首那一次 —— 一轮跑满 2×interval 之后租约自己到期,而本副本毫不知情、继续删下去。
+     *       轮子转多久租约就跟着延多久,那个窗口才真正关上。
+     *
+     * ⚠️ **如实登记的残余**(设计稿 §3 已成文接受,本实现不假装消灭):本调用返回 true 之后、本 domain 的
+     * 破坏性事务提交之前,仍有一个「租约在这中间被别人接管」的理论窗口 —— 关它需要把 fencing token 的
+     * 校验下推进**每一个破坏性事务的 WHERE**(车1 的三只方法),那是跨车的契约改动。补偿按设计稿:
+     * 每条破坏性审计行都带 fencing token,旧轮的写因此**可判别**(§6 的那一列正是为此存在)。
+     * 续租之后,这个窗口的宽度从「一整轮」缩到「一个 domain 的耗时」,且要求租约恰在这段内到期。
+     */
+    renew(holder: string, fencingToken: number, ttlMs: number, nowMs: number): Promise<boolean>;
+    /**
+     * 主动让租(优雅停机)——把到期时间归零,**保留 holder 与 token**(它们是审计线索,不是锁本身)。
+     * 谓词带 `holder = ?`:一个已经丢了租的副本在退出时不许把**别人**的租约推倒。
+     */
+    release(holder: string): Promise<void>;
+    /**
+     * 放置或解除一个域的 legal hold —— **同一 PK 的 upsert 改 `held` 列,绝不 INSERT/DELETE 行**
+     * (车1 交接件②,逐字)。
+     *
+     * 🔴 为什么删行是**拆锁**而不是"解除":`retention_hold` 的行同时是**域级互斥哨兵** —— 车1 的三条破坏性
+     * 事务首步就是锁读这一行(`INSERT IGNORE` 补哨兵 → `SELECT … FOR UPDATE`),而 `FOR UPDATE`
+     * **锁不住一条不存在的行**(TiDB 无 gap lock;PG READ COMMITTED 同病)。删掉行 = 下一个 PUT 与一条
+     * 在飞的删除事务又可以同时读到"没有 hold",于是 operator 拿到成功回执之后数据仍被删 —— 那正是 §5 F2
+     * 要消灭的那件事。upsert 让两者抢**同一把行锁**,「PUT 提交完成 ⇒ 其后每个破坏性事务的首读必见
+     * held=1」这句承诺才成立。
+     *
+     * 解除时把 `placed_by/placed_at_ms/note` 一并清空:这张表存的是**当前状态**不是历史,历史在
+     * `retention_audit` 的 `hold_placed`/`hold_released` 行上(追加不更新)。留一个「谁放的」在一条
+     * held=0 的行上,读它的人分不清那是"现在冻结着"还是"上次谁冻过"。
+     */
+    setHold(input: {
+        domain: string;
+        held: boolean;
+        placedBy?: string;
+        note?: string;
+        nowMs: number;
+    }): Promise<void>;
+    /** upsert 的**唯一** SQL 文本(自动提交口与事务口共用;见 {@link setHoldAudited} 的头注)。 */
+    protected setHoldOn(exec: SqlExec, input: {
+        domain: string;
+        held: boolean;
+        placedBy?: string;
+        note?: string;
+        nowMs: number;
+    }): Promise<void>;
+    /**
+     * 放置/解除 **+ 治理审计行,同一个事务**(codex 对抗复审 R1-[high],验真后加)。
+     *
+     * 🔴 为什么必须原子(与 §6 F5 的「删除与审计同事务」是同一条判据,只是换了一张表):两次独立提交下,
+     * 第二步失败会留下一次**无审计的状态变更**。PUT 那一支是「冻结了但账上没有」;**DELETE 那一支更重**
+     * —— 冻结已经解除、sweep 从下一拍起就能删这个域的数据,而审计里没有任何 `hold_released` 行说明是谁
+     * 在什么时候解的;客户端只看到一个 500,重试之前发生的删除再也无法从账本上追溯回那次释放。
+     * 一张表两条语句、同库同连接 ⇒ 原子性零分布式代价,没有不做的理由。
+     *
+     * `protected` 的两条私有腿(`setHoldOn` / `appendAuditOn`)让本方法与 {@link setHold} /
+     * {@link appendAudit} 共用**同一份 SQL 文本** —— 两处手抄一份 upsert,迟早只改一处。
+     */
+    setHoldAudited(input: {
+        domain: string;
+        held: boolean;
+        placedBy?: string;
+        note?: string;
+        nowMs: number;
+        audit: RetentionAuditAppend;
+    }): Promise<void>;
+    /** 「这个域现在冻结着吗」—— lane 的**省调**预检(§5 v1.3:降级为优化,**不承重**;承重判在车1 的
+     *  店事务内)。零写。 */
+    holdInForce(domain: string): Promise<boolean>;
+    /** 非破坏性审计行的追加(属主 = lane / 路由)。破坏性三词由车1 的店在删除同事务内写。 */
+    appendAudit(row: RetentionAuditAppend, nowMs: number): Promise<void>;
+    /** 追加的**唯一** SQL 文本(同上)。 */
+    protected appendAuditOn(exec: SqlExec, row: RetentionAuditAppend, nowMs: number): Promise<void>;
+    /**
+     * 审计读面(keyset 分页,`id` 降序)。
+     *
+     * 排序键 = **自增 `id` 单列**,而不是 roster 那样的 `(时间戳, 次键)` 二元组:`id` 本身就是全序且唯一,
+     * 二元组存在的全部理由(同毫秒兄弟行无 tiebreak ⇒ 漏页/重页)在这里结构上不存在。索引
+     * `idx_retention_audit_domain (domain, id)` 正是为这条查询建的。
+     *
+     * `before` = 上一页最后一行的 `id`(严格小于)。
+     *
+     * 🔴 读上限是 `MAX_LIMIT + 1` 而不是 `MAX_LIMIT`(codex 对抗复审 R1-[medium],验真属实):调用方要判
+     * 「还有没有下一页」就得多取一行,而**页**的上限是 `MAX_LIMIT`。旧形把 limit 无条件夹到 `MAX_LIMIT`
+     * ⇒ 请求 `limit=200` 时 scanned 恒 ≤ 200 ⇒ `hasMore` 恒 false ⇒ **第 201 行之后的审计对这条分页链
+     * 永久不可达**。这一格是「窗的上限」与「探路的那一行」两个不同的数被写成同一个数造成的,
+     * 修法是让它们各是各的:页 ≤ MAX_LIMIT(路由侧保证),读 ≤ MAX_LIMIT+1(本方法)。
+     */
+    listAudit(input: {
+        domain?: string;
+        limit: number;
+        beforeId?: number;
+    }): Promise<RetentionAuditRow[]>;
+}
+/** MySQL-protocol (TiDB) binding。 */
+export declare class TiDBRetentionLaneStore extends SqlRetentionLaneStore {
+    constructor(pool: MySqlPool);
+}
+/** PostgreSQL binding。 */
+export declare class PgRetentionLaneStore extends SqlRetentionLaneStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=retention-lane-store-sql.d.ts.map