@sema-agent/server 7.12.0 → 7.14.0

package/dist/plugins/memory-embedder.d.ts

@@ -0,0 +1,44 @@
+import type { MemoryEmbedderConfig } from "../config-types.js";
+import type { PgEmbedder } from "./pg-query.js";
+/** 工厂入参 = 配置坐标(单一属主 `config-types.ts`)+ 部署腿(观测/注入)。 */
+export interface OpenAiCompatEmbedderOptions extends MemoryEmbedderConfig {
+    /** 注入 fetch(测试/代理场景);缺省全局 `fetch`。 */
+    fetchImpl?: typeof fetch;
+    /**
+     * 失败观测腿(codex 复审 F2,已核真):embed 抛出去之后,`PgMemoryEngineBackend.applyPatches` 的
+     * 外层 catch 会把它折成一条 `io error: …` **冲突**记进 PatchReport(core 的冲突词表把它讲成「并发
+     * 改动」),而 `search` 那腿直接 `.catch(() => null)` 退回词面档 —— 两条路都不会在部署面留下任何
+     * 「向量供应商挂了」的信号。这个 hook 就是那个信号:装配点接 metrics + warn。
+     *
+     * ⚠️ hook 本身不改变结果:抛照抛(不吞、不补零),它只负责让故障**被看见**。
+     */
+    onFailure?: (err: unknown) => void;
+}
+/**
+ * 端点归一:`MEMORY_EMBEDDER_ENDPOINT` 收两种写法 —— OpenAI 兼容**基址**(`https://x/v1`)或**完整**
+ * 端点(`https://x/v1/embeddings`)。两种都是 operator 手上真实存在的抄法,而一律硬拼 `/embeddings`
+ * 会产出 `/v1/embeddings/embeddings`(这条键最常见的手滑形)。归一不是降级:两条路都指向同一个真 URL,
+ * 没有任何一种输入被静默改成**别的**语义。
+ *
+ * ⚠️ 只动 `pathname`(codex 复审 F3,已核真):第一版在**整串**上做 `endsWith`/拼接,于是带 query 的
+ * 端点全错 —— Azure OpenAI 形 `https://h/v1/embeddings?api-version=1` 会被拼成 query 值里带
+ * `1/embeddings`,`https://h/v1?api-version=1` 则永远拿不到 `/embeddings` 路径。两种都过得了启动期的
+ * URL 合法性门,只在运行期炸(而运行期的炸法就是上面那条「写入失败/检索退档」的静默病)。
+ */
+export declare function embeddingsUrl(endpoint: string): string;
+/**
+ * 诊断面用的**脱敏** URL(codex 复审 F4,已核真):端点里可能带 userinfo(`https://user:pass@h/v1`)
+ * 或把凭据放 query(Azure 的 `api-key=`),而错误文本会进日志、进 PatchReport 的 conflict reason。
+ * 主机与路径保留(诊断价值全在这里),userinfo 抹掉、query 值一律换成 `***`(键名保留,便于认形)。
+ */
+export declare function redactEndpointForLog(raw: string): string;
+/** 造一个 OpenAI 兼容的 `PgEmbedder`(工厂命名律:返回带行为的对象 ⇒ `create*`)。 */
+export declare function createOpenAiCompatEmbedder(opts: OpenAiCompatEmbedderOptions): PgEmbedder;
+/**
+ * 装配腿:配置在场 ⇒ 造 embedder,缺席 ⇒ `undefined`(= core 的三档推断落回 lexical)。
+ * 这一层单独存在是为了让「注入真的接上了」可测 —— `openStores` 本身要真 DB 才跑得起来。
+ */
+export declare function memoryEmbedderFor(config: {
+    memoryEmbedder?: MemoryEmbedderConfig;
+}, deps?: Pick<OpenAiCompatEmbedderOptions, "fetchImpl" | "onFailure">): PgEmbedder | undefined;
+//# sourceMappingURL=memory-embedder.d.ts.map

package/dist/plugins/memory-embedder.js

@@ -0,0 +1,173 @@
+/**
+ * #228 —— OpenAI 兼容的 embedder(黑板 [3590] 裁②:core 只留了 `PgEmbedder` 这个**纯接口**
+ * (`{ embed(text) → number[]; dimensions }`),没有任何现成实现件;部署半场归本仓)。
+ *
+ * ## 形
+ *
+ * `POST {endpoint}/embeddings`,body `{ model, input }`,读 `data[0].embedding` —— OpenAI /
+ * DashScope / TEI / vllm / ollama 的 `/v1` 面同形。auth 可选(自托管端点通常没有 key)。
+ *
+ * ## 为什么校验做得这么硬
+ *
+ * 向量列写错维度是**静默毒库**形([3606] 裁③):错长度向量既不会让 DB 报错(本仓 pg 记忆表的
+ * embedding 列是 `jsonb`,无维度约束),也不会让检索报错(维度不匹配的行只是悄悄退回词面档)——
+ * 于是「向量面开着」这句话变成一句谎,而且没有任何一层会说出来。所以:
+ *  · 响应形用 zod 校验(`data[0].embedding` 必须是 `number[]`),不符 = 抛带上下文的错;
+ *  · 长度与声明维度不等 = 抛,**绝不截断 / 补零**(那正是把毒喂进库的两种手法);
+ *  · 非 2xx / 非 JSON = 抛(status + body 前 200 字节,memory-sync transport 同款诊断姿势)。
+ *
+ * 抛出去之后由调用方处置:`PgMemoryEngineBackend.embeddingParam` 的长度门会让该行退回词面档,
+ * `search` 的词面腿 `.catch(() => null)` 会让检索继续跑 —— 即「embedder 坏了 = 退回 lexical」,
+ * 而不是「embedder 坏了 = 写坏向量」。
+ *
+ * ## 超时
+ *
+ * `AbortSignal.timeout(timeoutMs)`(缺省 30s,`MEMORY_EMBEDDER_TIMEOUT_MS` 覆盖,越界/坏值拒启)。
+ * 记忆写入路径是同步等 embed 的,挂死的端点会把整条 harvest 吊住(undici 默认 headers 超时 300s 太钝)。
+ */
+import { z } from "zod";
+/** OpenAI `/v1/embeddings` 响应的**最小**契约:只读第一条向量,其余键(usage/object/model)不关心。 */
+const EmbeddingsResponse = z.object({
+    data: z.array(z.object({ embedding: z.array(z.number()) })).min(1),
+});
+/**
+ * 端点归一:`MEMORY_EMBEDDER_ENDPOINT` 收两种写法 —— OpenAI 兼容**基址**(`https://x/v1`)或**完整**
+ * 端点(`https://x/v1/embeddings`)。两种都是 operator 手上真实存在的抄法,而一律硬拼 `/embeddings`
+ * 会产出 `/v1/embeddings/embeddings`(这条键最常见的手滑形)。归一不是降级:两条路都指向同一个真 URL,
+ * 没有任何一种输入被静默改成**别的**语义。
+ *
+ * ⚠️ 只动 `pathname`(codex 复审 F3,已核真):第一版在**整串**上做 `endsWith`/拼接,于是带 query 的
+ * 端点全错 —— Azure OpenAI 形 `https://h/v1/embeddings?api-version=1` 会被拼成 query 值里带
+ * `1/embeddings`,`https://h/v1?api-version=1` 则永远拿不到 `/embeddings` 路径。两种都过得了启动期的
+ * URL 合法性门,只在运行期炸(而运行期的炸法就是上面那条「写入失败/检索退档」的静默病)。
+ */
+export function embeddingsUrl(endpoint) {
+    const u = new URL(endpoint); // config 层已校验;直调工厂时坏 URL 在这里响亮抛
+    u.hash = ""; // fragment 对服务端无意义,带上只会污染日志
+    const path = u.pathname.replace(/\/+$/, "");
+    // 「已经带尾巴了吗」按**解码后**的末段判(codex 二轮 F3,已核真):`/v1/%65mbeddings` 与
+    // `/v1/embeddings` 是同一条路径,只比对序列化文本会给前者再叠一层。只解 unreserved 转义
+    // (RFC 3986 的 `A-Za-z0-9-._~`)—— 其余转义原样保留,decodeURIComponent 的坏 `%` 抛错面也一并避开。
+    u.pathname = decodeUnreservedEscapes(path).endsWith("/embeddings") ? path : `${path}/embeddings`;
+    return u.toString();
+}
+/** 只把 unreserved 字符的百分号转义解回来(不抛、不改变其它转义)。 */
+function decodeUnreservedEscapes(s) {
+    return s.replace(/%([0-9A-Fa-f]{2})/g, (whole, hex) => {
+        const c = String.fromCharCode(Number.parseInt(hex, 16));
+        return /[A-Za-z0-9\-._~]/.test(c) ? c : whole;
+    });
+}
+/**
+ * 诊断面用的**脱敏** URL(codex 复审 F4,已核真):端点里可能带 userinfo(`https://user:pass@h/v1`)
+ * 或把凭据放 query(Azure 的 `api-key=`),而错误文本会进日志、进 PatchReport 的 conflict reason。
+ * 主机与路径保留(诊断价值全在这里),userinfo 抹掉、query 值一律换成 `***`(键名保留,便于认形)。
+ */
+export function redactEndpointForLog(raw) {
+    if (!URL.canParse(raw))
+        return "<invalid-url>"; // 谓词先行,不用 catch 兜(#191 静默降级门:catch 回默认值是被数的形)
+    const u = new URL(raw);
+    u.username = "";
+    u.password = "";
+    for (const k of [...u.searchParams.keys()])
+        u.searchParams.set(k, "***");
+    return u.toString();
+}
+/** 端点 query 上的**值**(Azure 形把 key 放 query;这些字面量要从任何诊断文本里洗掉)。 */
+function credentialsInQuery(endpoint) {
+    if (!URL.canParse(endpoint))
+        return [];
+    return [...new URL(endpoint).searchParams.values()].filter((v) => v.length > 0);
+}
+/** 造一个 OpenAI 兼容的 `PgEmbedder`(工厂命名律:返回带行为的对象 ⇒ `create*`)。 */
+export function createOpenAiCompatEmbedder(opts) {
+    const url = embeddingsUrl(opts.endpoint);
+    const shownUrl = redactEndpointForLog(url);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const { model, dimensions, timeoutMs, apiKey, onFailure } = opts;
+    // 洗白名单 = 本部署已知的**全部**凭据字面量:apiKey + 端点 query 上的值(Azure 形把 key 放 query;
+    // codex 二轮 F1)。userinfo 在 config 层就被拒了,这里不再单列。
+    const secrets = [...(apiKey !== undefined ? [apiKey] : []), ...credentialsInQuery(opts.endpoint)];
+    /** 供应商 body / 传输层错误进诊断文本前先洗一遍:回显自家凭据的代理/网关是真实存在的形。 */
+    const scrub = (raw) => secrets.reduce((acc, s) => acc.replaceAll(s, "***"), raw);
+    const safeSlice = (raw) => scrub(raw).slice(0, 200);
+    const call = async (text) => {
+        // 传输层失败(DNS/连不上/超时)也要走脱敏形(codex 二轮 F1):undici 的错误链里可能带上完整 URL,
+        // 而这条错会进 warn 日志与 PatchReport 的 conflict reason。**刻意不挂 cause**:挂上等于把没洗过的
+        // 原始文本从后门放回诊断面(打印错误链的人一样看得见),这里只带洗过的文本。
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(apiKey !== undefined ? { authorization: `Bearer ${apiKey}` } : {}),
+                },
+                body: JSON.stringify({ model, input: text }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (transportErr) {
+            throw new Error(`memory embedder POST ${shownUrl}: transport failure — ${safeSlice(String(transportErr))}`);
+        }
+        const raw = await res.text().catch((readErr) => {
+            throw new Error(`memory embedder POST ${shownUrl}: response body unreadable — ${safeSlice(String(readErr))}`);
+        });
+        // 诊断面纪律:回显 status + body 前缀(端点的 typed error body 就是最好的线索),但 URL 走脱敏形、
+        // body 先洗掉全部已知凭据字面量 —— 错误文本会进日志与 PatchReport 的 conflict reason。
+        if (!res.ok)
+            throw new Error(`memory embedder POST ${shownUrl}: HTTP ${res.status} ${safeSlice(raw)}`);
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`memory embedder POST ${shownUrl}: response is not JSON — ${safeSlice(raw)}`);
+        }
+        const parsed = EmbeddingsResponse.safeParse(json);
+        if (!parsed.success) {
+            throw new Error(`memory embedder POST ${shownUrl}: not an OpenAI-compatible embeddings response (${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}) — body ${safeSlice(raw)}`);
+        }
+        const vector = parsed.data.data[0].embedding;
+        if (vector.length !== dimensions) {
+            throw new Error(`memory embedder model "${model}" returned ${vector.length} dimensions but MEMORY_EMBEDDER_DIM=${dimensions} — refusing to truncate or pad (a wrong-length vector in the memory embedding column is silent corruption: neither the DB nor retrieval reports it). Fix MEMORY_EMBEDDER_DIM to match the model, or point MEMORY_EMBEDDER_MODEL at the model you sized for.`);
+        }
+        return vector;
+    };
+    return {
+        dimensions,
+        async embed(text) {
+            try {
+                return await call(text);
+            }
+            catch (err) {
+                // 先让部署面看见,再**原样**抛(观测腿绝不改变结果,连真错的属性都不碰)
+                try {
+                    onFailure?.(err);
+                }
+                catch (hookErr) {
+                    // 观测腿自己坏了:①不许顶替真故障(拿监控的病盖住业务的病是最坏的一种交换);②不许改动真错
+                    // ——第一版往 err.cause 上挂,冻结/不可写的 err 会让**赋值本身**抛,于是 TypeError 顶替了
+                    //   真错(codex 二轮 F2,已核真);③也不许无声 —— 走 process.emitWarning,不碰真错分毫。
+                    process.emitWarning(`memory embedder onFailure hook threw: ${String(hookErr)}`, "MemoryEmbedderObservabilityWarning");
+                }
+                throw err; // 原对象原样抛出(identity 不变)
+            }
+        },
+    };
+}
+/**
+ * 装配腿:配置在场 ⇒ 造 embedder,缺席 ⇒ `undefined`(= core 的三档推断落回 lexical)。
+ * 这一层单独存在是为了让「注入真的接上了」可测 —— `openStores` 本身要真 DB 才跑得起来。
+ */
+export function memoryEmbedderFor(config, deps = {}) {
+    const cfg = config.memoryEmbedder;
+    if (cfg === undefined)
+        return undefined;
+    return createOpenAiCompatEmbedder({
+        ...cfg,
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+        ...(deps.onFailure !== undefined ? { onFailure: deps.onFailure } : {}),
+    });
+}
+//# sourceMappingURL=memory-embedder.js.map

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -232,6 +232,35 @@ export declare class SqlRuleImportTicketStore {
     release(ticketId: string, principal: string, mustRemainValidMs?: number): Promise<boolean>;
     private readRow;
 }
+/**
+ * 孤儿 pending 审批记录的保留期(A-010.17)。
+ *
+ * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
+ * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
+ * 要么要拿一张导入票 —— 而票自铸起最多活 {@link RULE_IMPORT_TICKET_TTL_MS}(10 分钟,`consume` 的
+ * `expires_at_ms > now` 是硬条件)。所以创建时刻早于「now − 票 TTL」的 pending 记录**再也不可能**
+ * 被兑付。24 小时是在这条上界之上再压两个数量级的余量,留给运维「昨天那次导入怎么没成」的排查窗。
+ *
+ * 🔴 **只收 pending**。`approved` / `redeemed` 是一次真人同意的**审计事实**(与 `discardPendingRecord`
+ * 的 `WHERE state = 'pending'` 同一条硬约束,也与收编把这张表判成 D2「史实不改写」同源)——
+ * 保留期策略动不到它们,本腿一行都不碰。
+ */
+export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
+/**
+ * 保留期腿**每轮**最多删多少行(codex R2 [high])。
+ *
+ * 为什么必须有界:`permission_rule_approval` 按设计**永久**留 approved/redeemed 的审计事实(收编把它
+ * 判成 D2「史实不改写」,`discardPendingRecord` 的 `WHERE state='pending'` 也是同一条硬约束)——
+ * 也就是说这张表**只增不减**。一条无界 DELETE 在首次开清扫、或一次长期没跑的部署上,会在一个事务里
+ * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
+ * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
+ *
+ * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
+ * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
+ * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
+ * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
+ */
+export declare const RULE_REAP_BATCH = 500;
 /** 三个 SQL 店的一次性装配束(one driver, three faces)。 */
 export interface PermissionRuleStores {
     provider: SqlPermissionRuleStoreProvider;
@@ -244,6 +273,22 @@ export interface PermissionRuleStores {
      *  代价不划算。桶数回答的正是审计要问的那个问题(「这台部署上有没有既有的规则状态」),而且是一次
      *  索引级 `COUNT(*)`。消费点(`boot/permission-rules-audit.ts`)的文案因此逐字说的是 bucket,不是 rule。 */
     countBuckets(): Promise<number>;
+    /**
+     * 保留期腿(A-010.17)。返回删掉的**总行数**(两张表合计),给 reaper 的 `reapCount` 用。
+     *
+     * 病:这两张表此前**没有任何 retention 腿**,而它们都是只进不出的:
+     *  · `permission_rule_ticket` —— 每一次 `POST /v1/rules/cc-import/prepare` 落一行,不管有没有人去
+     *    兑付。而普查门把它登记成「过期即死」—— 那句话描述的是**语义**(过期票 `consume` 必拒),
+     *    库里那一行从来没有人删。一个把 CC settings 导来导去的部署,这张表每次预览都长一行,永久。
+     *  · `permission_rule_approval` 的 **pending** 行 —— core 在**返回预览之前**就落记录,于是「看了预览
+     *    没按确认」这条最常见的人类路径,每走一次留一条永远没人要的行(`discardPendingRecord` 只收
+     *    「超帽当场拒」那一条路,不收「人改主意了」)。
+     *
+     * 两条谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
+     *  · 票:`expires_at_ms <= now` —— `consume` 的硬条件是 `expires_at_ms > now`,过期票已不可兑付;
+     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`。
+     */
+    reapExpired(nowMs: number): Promise<number>;
 }
 export declare function createSqlPermissionRuleStores(db: SqlDriver, now?: () => number): PermissionRuleStores;
 //# sourceMappingURL=permission-rule-store-sql.d.ts.map

package/dist/plugins/permission-rule-store-sql.js

@@ -190,7 +190,12 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     created_at_ms BIGINT NOT NULL,
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (record_id),
-    KEY idx_permission_rule_approval_owner (owner_key)
+    KEY idx_permission_rule_approval_owner (owner_key),
+    -- 保留期腿的**支撑索引**(A-010.17 / codex R2 [high])。这张表按设计**永久**留着 approved/redeemed
+    -- 的审计事实,所以它只增不减 ⇒ 一条没有索引的 WHERE state='pending' AND created_at_ms < ? 谓词
+    -- 是一次随审计史无限增长的全表扫,而且每 tick 一次。(state, created_at_ms) 复合序把清扫收敛成
+    -- 一次窄区间扫:pending 段本来就短命,超期的那几行紧挨着。
+    KEY idx_permission_rule_approval_sweep (state, created_at_ms)
   ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) NOT NULL,
@@ -209,7 +214,9 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     consumed_at_ms BIGINT NULL,
     created_at_ms BIGINT NOT NULL,
     PRIMARY KEY (ticket_id),
-    KEY idx_permission_rule_ticket_owner (owner_key)
+    KEY idx_permission_rule_ticket_owner (owner_key),
+    -- 保留期腿的支撑索引(同上):WHERE expires_at_ms <= ? 是每 tick 一次的区间扫。
+    KEY idx_permission_rule_ticket_expires (expires_at_ms)
   ) COLLATE utf8mb4_bin`,
 ];
 /** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
@@ -255,6 +262,10 @@ export async function ensurePgPermissionRuleSchema(q) {
     PRIMARY KEY (record_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_owner ON ${PERMISSION_RULE_APPROVAL_TABLE} (owner_key)`);
+    // 保留期腿的支撑索引(MySQL 孪生的行内注写了理由:这张表按设计永久留审计事实,无索引的清扫谓词
+    // 是一次随史增长的全表扫)。PG 侧是独立 CREATE INDEX —— 存量库上 `IF NOT EXISTS` 会**真的补建**,
+    // 与 MySQL 侧「索引写在 CREATE TABLE 里、存量表拿不到」的不对称如实登记在 reapExpired 的注里。
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_sweep ON ${PERMISSION_RULE_APPROVAL_TABLE} (state, created_at_ms)`);
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) COLLATE "C" NOT NULL,
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -268,6 +279,7 @@ export async function ensurePgPermissionRuleSchema(q) {
     PRIMARY KEY (ticket_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_expires ON ${PERMISSION_RULE_TICKET_TABLE} (expires_at_ms)`);
 }
 // ─────────────────────────────────────────────────────────────────────────────────────────────────
 // 纯函数(桶键 / 摘要 / delta 折叠)
@@ -807,11 +819,57 @@ export class SqlRuleImportTicketStore {
         };
     }
 }
+/**
+ * 孤儿 pending 审批记录的保留期(A-010.17)。
+ *
+ * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
+ * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
+ * 要么要拿一张导入票 —— 而票自铸起最多活 {@link RULE_IMPORT_TICKET_TTL_MS}(10 分钟,`consume` 的
+ * `expires_at_ms > now` 是硬条件)。所以创建时刻早于「now − 票 TTL」的 pending 记录**再也不可能**
+ * 被兑付。24 小时是在这条上界之上再压两个数量级的余量,留给运维「昨天那次导入怎么没成」的排查窗。
+ *
+ * 🔴 **只收 pending**。`approved` / `redeemed` 是一次真人同意的**审计事实**(与 `discardPendingRecord`
+ * 的 `WHERE state = 'pending'` 同一条硬约束,也与收编把这张表判成 D2「史实不改写」同源)——
+ * 保留期策略动不到它们,本腿一行都不碰。
+ */
+export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
+/**
+ * 保留期腿**每轮**最多删多少行(codex R2 [high])。
+ *
+ * 为什么必须有界:`permission_rule_approval` 按设计**永久**留 approved/redeemed 的审计事实(收编把它
+ * 判成 D2「史实不改写」,`discardPendingRecord` 的 `WHERE state='pending'` 也是同一条硬约束)——
+ * 也就是说这张表**只增不减**。一条无界 DELETE 在首次开清扫、或一次长期没跑的部署上,会在一个事务里
+ * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
+ * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
+ *
+ * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
+ * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
+ * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
+ * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
+ */
+export const RULE_REAP_BATCH = 500;
 export function createSqlPermissionRuleStores(db, now) {
+    const q = (tidb, pg) => (db.dialect === "tidb" ? tidb : pg);
     return {
         provider: new SqlPermissionRuleStoreProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db, now),
+        reapExpired: async (nowMs) => {
+            // 两条 DELETE **不包事务**:它们互相独立、各自幂等,一条失败不该把另一条已删的行回滚回来
+            // (维护腿的既有姿势 —— 邻居 reaper 腿全是独立语句)。
+            //
+            // 🔴 **每 tick 有界**(codex 对抗复审 R2 [high],验真后修):第一版是两条**无界** DELETE。
+            // 首次开清扫(或一次长时间没跑的部署)会在**一个事务**里删掉整个积压 —— 一条能跑很久、锁很多行、
+            // 把 binlog/WAL 顶起来的语句;而调用点当时又没有重入守卫,一旦耗时越过 tick 间隔,下一轮就叠上来。
+            // 收成每轮 {@link RULE_REAP_BATCH} 行:积压按轮**渐进**清空(每轮都是完整语义,不留半干净状态),
+            // 单条语句的最坏时长与库大小脱钩。调用侧另配了 in-flight 守卫(`boot/reapers.ts`)。
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= ? LIMIT ${RULE_REAP_BATCH}`, 
+            // PG 的 DELETE 没有 LIMIT ⇒ 用 ctid 子查询限行(PG 侧的标准写法;`ctid` 是物理行号,
+            // 子查询里带 LIMIT 才是被支持的那一形)。两方言的**语义**相同:本轮最多删这么多行。
+            `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs]);
+            const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
+            return deadTickets.affected + orphanPending.affected;
+        },
         // 两个方言逐字同形(`COUNT(*)` 无方言差),所以刻意**不**走 `q(tidb, pg)` 的双串姿势 —— 那会造出
         // 两份可以各自漂的同一句 SQL。参数空数组:本语句没有绑定位。
         countBuckets: async () => {

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -154,10 +154,15 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
         signal?: AbortSignal;
     }): Promise<SharedMemorySnapshot>;
     /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。方言差异显式:
-     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
-     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
-     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
+     *
+     * 🔴 A-010.11(两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
+     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
+     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
+     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
+     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
+     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
+     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
      */
     private readBinding;
     private readerFor;
@@ -194,12 +199,21 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
      *    与插入之间穿过去,留下一行孤儿文档 —— 被删的内容在 id 复用时复活。
      */
     putDocument(record: SharedMemoryDocumentRecord): Promise<void>;
-    /** Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
-     *  successor tenant's library). Returns whether a row was actually there. */
+    /**
+     * Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
+     * successor tenant's library). Returns whether a row was actually there.
+     *
+     * 🔴 A-010.14(验真后修):此前围栏是**两条独立语句** —— `assertOwnedBy()` 先查一次登记表,然后另
+     * 起一条 DELETE。它自称与 `putDocument` 对齐,但 `putDocument` 的检查与写是**同事务同行锁**
+     * (`FOR UPDATE`),而这里的两条语句之间有一道真窗:登记检查通过之后、DELETE 发出之前,另一个 org
+     * 完成 `deleteStore` + `putStore` 的 id 复用,这条 DELETE 就落进**继任租户**的库里删掉他们的文档。
+     * 那正是 `putDocument` 的注里写明要挡住的那一形。现在逐字照它:同一事务、对登记行 `FOR UPDATE`、
+     * 拿到锁之后再删。
+     *
+     * 「未登记 ⇒ 响亮抛」与「登记了但没这条文档 ⇒ 回 false」两件事仍然分家(调用方据此分支),所以
+     * 不能收成一条 `DELETE … WHERE EXISTS(…)`:那样 `affected === 0` 会把两种结局压成同一个读数。
+     */
     deleteDocument(storeId: string, scopeKey: string, path: string): Promise<boolean>;
-    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
-     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
-    private assertOwnedBy;
     /**
      * De-register a store AND its documents, ATOMICALLY.
      *

package/dist/plugins/shared-memory-store-sql.js

@@ -215,17 +215,20 @@ export class SqlSharedMemoryStore {
         };
     }
     /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。方言差异显式:
-     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
-     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
-     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
+     *
+     * 🔴 A-010.11(两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
+     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
+     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
+     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
+     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
+     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
+     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
      */
     async readBinding(scopes) {
         const conn = await this.db.connect();
         try {
-            await conn.begin();
-            if (this.db.dialect === "pg")
-                await conn.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+            await conn.beginRepeatableRead();
             const scopeRows = await conn.query(this.q(`SELECT scope_key, state, message FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")})`, `SELECT scope_key, state, message FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${i + 1}`).join(", ")})`), [...scopes]);
             const storeRows = await conn.query(this.q(`SELECT store_id, scope_key, description, writable FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")}) ORDER BY store_id`, `SELECT store_id, scope_key, description, writable FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${i + 1}`).join(", ")}) ORDER BY store_id`), [...scopes]);
             await conn.commit();
@@ -444,23 +447,57 @@ export class SqlSharedMemoryStore {
             throw new Error(`shared-memory store ${JSON.stringify(record.storeId)} is not registered under ${JSON.stringify(record.scopeKey)} — either it was never created, or the id has since been recycled by another org (call putStore() first; a stale retry must NOT land in the new tenant's library)`);
         }
     }
-    /** Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
-     *  successor tenant's library). Returns whether a row was actually there. */
+    /**
+     * Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
+     * successor tenant's library). Returns whether a row was actually there.
+     *
+     * 🔴 A-010.14(验真后修):此前围栏是**两条独立语句** —— `assertOwnedBy()` 先查一次登记表,然后另
+     * 起一条 DELETE。它自称与 `putDocument` 对齐,但 `putDocument` 的检查与写是**同事务同行锁**
+     * (`FOR UPDATE`),而这里的两条语句之间有一道真窗:登记检查通过之后、DELETE 发出之前,另一个 org
+     * 完成 `deleteStore` + `putStore` 的 id 复用,这条 DELETE 就落进**继任租户**的库里删掉他们的文档。
+     * 那正是 `putDocument` 的注里写明要挡住的那一形。现在逐字照它:同一事务、对登记行 `FOR UPDATE`、
+     * 拿到锁之后再删。
+     *
+     * 「未登记 ⇒ 响亮抛」与「登记了但没这条文档 ⇒ 回 false」两件事仍然分家(调用方据此分支),所以
+     * 不能收成一条 `DELETE … WHERE EXISTS(…)`:那样 `affected === 0` 会把两种结局压成同一个读数。
+     */
     async deleteDocument(storeId, scopeKey, path) {
-        await this.assertOwnedBy(storeId, scopeKey);
-        const res = await this.db.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ? AND path = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1 AND path = $2`), [storeId, path]);
-        return res.affected > 0;
-    }
-    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
-     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
-    async assertOwnedBy(storeId, scopeKey) {
         assertStoreId(storeId);
         assertScopeKey(scopeKey);
-        const res = await this.db.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ?`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2`), [storeId, scopeKey]);
-        if (res.rows.length === 0) {
+        let unregistered = false;
+        let deleted = false;
+        const conn = await this.db.connect();
+        try {
+            await conn.begin(); // 为什么不是 beginPessimistic:见本类头注的"事务与锁"段(与 putDocument 同判)
+            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (registered.rows.length === 0) {
+                unregistered = true;
+                await conn.rollback();
+            }
+            else {
+                const res = await conn.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ? AND path = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1 AND path = $2`), [storeId, path]);
+                deleted = res.affected > 0;
+                await conn.commit();
+            }
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        if (unregistered) {
+            // 文案逐字同 assertOwnedBy(调用方/测试按它对表);围栏的**执行面**改了,拒绝的**说法**没改。
             throw new Error(`shared-memory store ${JSON.stringify(storeId)} is not registered under ${JSON.stringify(scopeKey)} — either it does not exist, or the id has since been recycled by another org`);
         }
+        return deleted;
     }
+    // 属主围栏的共用断言 `assertOwnedBy()` 曾住在这里(轮3 F1)。A-010.14 把它**唯一**的消费者
+    // (`deleteDocument`)改成「同事务 + FOR UPDATE」之后它就没有调用点了 —— 留着一个自带围栏语义却
+    // 无人调用的私有方法,下一个人会以为「围栏在这儿,照着调就行」,而它恰恰是被判定为不够强的那一版。
+    // 边界的如实说明随之搬进 `deleteDocument` / `putDocument`:两者**都不**覆盖同一个 org 内的
+    // "删了又建"代际重用 —— 那不是跨租户面,真要挡住需要一枚不可变的 generation token。
     /**
      * De-register a store AND its documents, ATOMICALLY.
      *

package/dist/plugins/sql-driver.d.ts

@@ -91,6 +91,25 @@ export interface SqlTxConn extends SqlExec {
     begin(): Promise<void>;
     /** TiDB: `BEGIN PESSIMISTIC` (current-read txn). PG: plain `BEGIN`. */
     beginPessimistic(): Promise<void>;
+    /**
+     * Open a transaction whose reads are pinned to ONE snapshot (A-010.11).
+     *
+     * 🔴 Why this is a named verb and not "just `begin()` — MySQL defaults to REPEATABLE READ anyway":
+     * a *server default* is not a structural guarantee. `transaction_isolation` is a settable
+     * server/session variable; a deployment (or a proxy, or a managed-MySQL vendor default) that runs
+     * READ COMMITTED silently turns "one transaction one snapshot" into "each statement its own
+     * snapshot" — and the caller that relied on it (`shared-memory-store-sql.ts` readBinding) goes on
+     * reading a torn scope/store pair with no error anywhere. The PG arm was already explicit; the
+     * MySQL arm was leaning on the default. Both arms now PIN it.
+     *
+     * The two arms diverge in WHERE the statement goes, and that is not cosmetic:
+     *  · MySQL/TiDB — `SET TRANSACTION ISOLATION LEVEL …` with no scope keyword applies to the **next**
+     *    transaction, and issuing it *inside* an open transaction is an ERROR
+     *    (`ER_CANT_CHANGE_TX_CHARACTERISTICS`). So it must precede `beginTransaction()`.
+     *  · PG — the same statement must be issued *inside* the transaction, before its first query.
+     * Writing one "portable" form would be wrong on one of the two engines; hence one verb, two texts.
+     */
+    beginRepeatableRead(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
     release(): void;

package/dist/plugins/sql-driver.js

@@ -24,6 +24,12 @@ export function mysqlDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN PESSIMISTIC");
                 },
+                // Scope-less `SET TRANSACTION …` = next-transaction only, so it goes BEFORE the BEGIN and
+                // leaves the pooled connection's session default untouched for whoever gets it next.
+                beginRepeatableRead: async () => {
+                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+                    await c.beginTransaction();
+                },
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
                 release: () => c.release(),
@@ -50,6 +56,12 @@ export function pgDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN");
                 },
+                // PG takes it INSIDE the transaction (and only before its first query) — the mirror image of
+                // the MySQL arm above. Same verb, deliberately different placement.
+                beginRepeatableRead: async () => {
+                    await c.query("BEGIN");
+                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+                },
                 commit: async () => {
                     await c.query("COMMIT");
                 },

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

@@ -93,7 +93,9 @@ export type ToolResultStoreFull = ToolResultStore & {
     /** TTL sweep (SQL twins only): purge rows older than the cutoff. Local file store omits it (CC posture:
      *  a single user's tool-result files persist like transcripts; bounded by being text previews). */
     reapOlderThan?(cutoffMs: number): Promise<number>;
-    /** E21 purge (SQL twins only): delete `tr_<sessionId>_%` refs when a session is purged. */
+    /** E21 purge (SQL twins only): delete this session's refs when a session is purged. core 5.26.0 (#119)
+     *  changed the mint from `tr_<sid>_<call>` to `tr_<sid>~<call>~<content>`, so the twin matches BOTH prefixes —
+     *  see `deleteBySession` in tool-result-store-sql.ts for why dropping either one is a silent purge failure. */
     deleteBySession?(sessionId: string): Promise<number>;
 };
 /** Cross-replica counter twins expose the write-behind lifecycle (startRefresh/stop) main.ts drives. */

package/dist/plugins/store-backend.js

@@ -222,7 +222,30 @@ class LocalBackend {
         // adoptLocalDataRoot 到完成,或修 adoption.json」的出路),我们没有更好的话可说,包一层只会更差。
         // 包装只留给真正的 boot-lock 类失败(那句文案的适用条件)。
         try {
-            this.fileBackend = new FileStorageBackend({ root, ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}) }); // REWIND_SNAPSHOT_MAX_MB
+            this.fileBackend = new FileStorageBackend({
+                root,
+                ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}), // REWIND_SNAPSHOT_MAX_MB
+                // 🔴 腐读披露座(交接件④,与 `run-local.ts` 的同座同形、同 warn 名 `file_store_corrupt_read`)。
+                // core 对**读不出来的**持久文件是 documented fail-open —— 当作「缺席」继续跑(抛会让整条任务死,
+                // 也会自锁修复写)。这条 fail-open 是 core 的裁定,本仓不改它;但它**不许无声**(#157 安全轴纪律)。
+                // 此前 HTTP 服务的 local 车道**根本没接这个座**:同一份坏字节,run-local 上打一行、服务上一个字
+                // 都没有 —— 而服务形恰恰是没人盯着终端的那一个。
+                //
+                // ⚠️ 文案按脸分列后果、**不下统一结论**(run-local 那次 codex R2-medium 的教训一并吸收):一个座
+                // 覆盖 core 转发的三张脸,后果各不相同 —— 把「少了会话规则这一层」写成「整个任务无约束」会误导
+                // 事故定级,而且对另外两张脸根本不成立。共同事实只有一句:一次持久读被当成了缺席。
+                // ENOENT 不触发(那是真缺席,不是腐读)。
+                onCorruptRead: (info) => this.onWarn?.("file_store_corrupt_read", {
+                    path: info.path,
+                    reason: info.reason,
+                    ...(info.sessionId !== undefined ? { sessionId: info.sessionId } : {}),
+                    ...(info.principal !== undefined ? { principal: info.principal } : {}),
+                    note: "a durable read was treated as ABSENT because the bytes were unreadable (never a plain ENOENT). " +
+                        "Consequence depends on which store read it: session-policy = that run lost its SUBTRACTIVE session-rule " +
+                        "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
+                        "rows; file-snapshot = a snapshot or scope read as missing. Inspect the named path before deciding.",
+                }),
+            });
         }
         catch (e) {
             if (e instanceof AdoptionError)