@sema-agent/server 7.31.0 → 7.32.0

package/dist/http/server.js

@@ -41,6 +41,7 @@ import { handleDiagnostics } from "./routes/diagnostics.js";
 import { handleAdoption } from "./routes/adoption.js";
 import { handleRetention } from "./routes/retention-ops.js";
 import { handleMemoryPolicy } from "./routes/memory-policy.js";
+import { handleMemoryBundle } from "./routes/memory-bundle.js";
 import { handleSharedMemory } from "./routes/shared-memory.js";
 import { handleRules } from "./routes/rules.js";
 import { handleSessionsList } from "./routes/sessions-list.js";
@@ -213,6 +214,7 @@ const ROUTE_DOMAINS = [
     handleAdoption,
     handleRetention,
     handleMemoryPolicy,
+    handleMemoryBundle,
     handleRules,
     handleSharedMemory,
     handleSessionsList,
@@ -704,6 +706,14 @@ export function createHttpServer(rawDeps) {
         // design/158 A9:memory 导出/同步 + /v1/policy 只读面(routes/memory-policy.ts)。
         if (await handleMemoryPolicy(req, res, url, ctx))
             return;
+        // #264 v2-c:治理携出 bundle 的 operator 面(routes/memory-bundle.ts;POST 两口)。
+        // 🔴 位置在 memory-policy **之后**是有意的:`/v1/memory/export` 这条路径上住着两个不同的面 ——
+        // GET = 142-S5 的属主自助条目读(owner 门,零存在性 oracle),POST = 本件的治理包(operator-only)。
+        // 两者按**方法**互斥,谁先谁后都不改判;把既有的 GET 面留在前面,是让新面在任何情况下都不可能
+        // 遮住它(本模块只认 POST,一个字都不碰 GET 的匹配式)。族属上它与 adoption / retention-ops 同类:
+        // 部署级 operator 动作、同一条 explicitOperatorOk 门、同样 billable=false。
+        if (await handleMemoryBundle(req, res, url, ctx))
+            return;
         // #154 车二:CC settings 导入两口(lane=principal,billable=false)。
         if (await handleRules(req, res, url, ctx))
             return;
@@ -3262,13 +3272,32 @@ export function isBillableSubmitPath(url) {
  * 🔴 **方法感知**(codex 对抗复审 R2-[high],验真后修):撤销走的是 `DELETE`,而本门最初只挂在 `POST` 的
  * 合取里 —— 于是一个自称「持久改写」的谓词把爆炸半径最大的那条动词漏在门外,正是 `isDestructiveSessionWrite`
  * 当年被抓到的同一形。签名因此收方法,与那只谓词逐字同形。
- * 🔴 读面不进本表:`GET /v1/adoption/:id` 与 `GET /v1/rules` 各有自己的属主/operator 门,本门只拦写。
- * 行为面钉:`test/rewrite-door-service-token-gate.test.ts`(四扇门各一正一反 + 逃生口格 + 读面负控)。
+ * 🔴 读面**原则上**不进本表:`GET /v1/adoption/:id` 与 `GET /v1/rules` 各有自己的**属主门**兜底,本门只拦写。
+ *
+ * 🔴 **第二个合取项的加宽**(codex 对抗复审 [high],#277 提货批,验真后修)——判据现在是
+ * 「持久改写 **或** 授权唯一输入是 principal 头的**跨租户治理读**」。加宽是为了收进 #264 v2-c 的两口:
+ *  · `POST /v1/memory/import` —— 直接落在**原**判据上,而且是本仓最深的那一种持久改写:它把别处铸的
+ *    条目 / 挑战 / 污染标记 / 托管链落进本部署的记忆平面。伪造一个在册 operator 头 ⇒ 一份**攻击者自制的
+ *    治理史**成为本店的账;而记忆是模型**每次挂载都读**的面,比种一条常驻 allow 规则更深(那条只影响
+ *    ask 会不会问,这条影响模型相信什么)。
+ *  · `POST /v1/memory/export` —— 是**读**,按原措辞本不该进。但被点名豁免的那两条读各有属主门兜底,
+ *    而本条**没有**:它的授权判据就是 `explicitOperatorOk`,过了就是**全库**——一次调用取走每个 scope 的
+ *    条目正文 + 托管链 + 跨会话污染标记 + lineage。把一次全租户记忆外泄留在门外、只为守住「本门只拦写」
+ *    这句措辞,是把措辞看得比它要保护的东西更重。加宽后的判据仍然是**闭**的(不是「写门以外都进」):
+ *    它要求「授权的唯一输入是那个头」∧「一次调用的爆炸半径跨租户」,`GET /v1/rules` 那种属主门读不满足。
+ * 行为面钉:`test/rewrite-door-service-token-gate.test.ts`(六扇门各一正一反 + 逃生口格 + 读面负控)。
  */
 export function isCredentialGatedRewrite(method, url) {
     const m = method.toUpperCase();
-    if (m === "POST")
-        return url === "/v1/adoption" || url.startsWith("/v1/rules/cc-import/");
+    if (m === "POST") {
+        return (url === "/v1/adoption" ||
+            url.startsWith("/v1/rules/cc-import/") ||
+            // #264 v2-c 的两口(codex 对抗复审 [high],验真后修)。判据见上方头注**加宽**的那一段:
+            // import 是本仓最深的持久改写(外来治理史成为本店的账,而记忆是模型每次挂载都读的面);
+            // export 虽是读,但它是**没有属主门兜底**的跨租户治理外泄——两者的授权唯一输入都是那个头。
+            url === "/v1/memory/import" ||
+            url === "/v1/memory/export");
+    }
     if (m === "DELETE")
         return url === "/v1/rules";
     return false;
@@ -3343,7 +3372,13 @@ const ROUTE_LABEL_LITERALS = new Set([
     // 桶会把该桶的 P99 拉爆,运营看不出是谁。批1 建表时漏掉它不是遗忘:fleet 域用 `pathname === …` 判路,
     // 名册门的枚举器当时只认 `url === …`,整条路由对门隐形(枚举器已一并补上)。
     "/v1/fleet/stream",
+    // ⚠️ `/v1/memory/export` 是**两个面**共用的标签(GET=142-S5 属主自助条目读,POST=#264 治理包)——
+    // 标签粒度粗于面的边界,但两面同 billable(false)、同为低频运维/壳读,合桶不会掩盖任何一方的信号。
     "/v1/memory/export", "/v1/sendfile-links",
+    // #264 v2-c:治理包的导入口(operator-only,POST)。低频,但它是**治理写面** —— 它的 4xx/5xx 分布
+    // 是「这批迁移到底成没成」的第一手机器信号,落进 `other` 桶等于迁移现场看不见它。同族纪律:写
+    // **字面量**不引常量(名册门与 billable 申明门都扫源码文本)。
+    "/v1/memory/import",
     // design/177:共享记忆库清单面(具名两条走上面的模式表)。
     "/v1/shared-memory/stores",
     // #154:装配自证读面(operator-only)。低频但**每次都在排障现场被打**,落进 `other` 桶等于排障时看不见。

package/dist/main.js

@@ -29,6 +29,7 @@ import { setRedactionObserver, redactSecrets } from "./trace/redact.js";
 import { RateLimiter } from "./observability/rate-limit.js";
 import { createHttpServer, explicitOperatorOk } from "./http/server.js";
 import { exportMemoryScope } from "./memory-export.js";
+import { createMemoryBundleFaces } from "./memory-bundle-engine.js";
 import { performMemorySync } from "./memory-sync.js";
 import { startOtlpExporter } from "./observability/otel-exporter.js";
 import { HEARTBEAT_MS, backgroundAgentOutput, taskHandleOutput, taskHandleStop } from "./runs.js";
@@ -182,6 +183,11 @@ async function main() {
     // design/183 I6(server 同族):**每副本 boot 必查**收编日志的在飞行 —— 续跑或响亮留痕,禁静默跳过。
     // 位置:store 开完之后(要 backend)、任何路由装配之前(半迁移状态绝不带进服务期)。判据与「为什么
     // 是续跑而不是拒启」见 boot/adoption.ts 顶注。
+    // #264 v2-c:治理携出 bundle 两面(POST /v1/memory/{export,import})的引擎接线。**一次**构造、两口共用
+    // —— 与 orgMemoryDirectory / sharedMemoryStore 同姿势(一个进程对同一件事只有一个实例)。
+    // 引擎为什么在这里现构、以及「这两条路径是店级的、不读挂载树」的亲读依据,全文见 memory-bundle-engine.ts。
+    // 缺席(记忆引擎未接线)⇒ 两口 501 `capability.memory_engine_required`。
+    const memoryBundleFaces = memoryEngine ? createMemoryBundleFaces(memoryEngine) : undefined;
     const adoptionBoot = await runAdoptionBootScan({ backend, logger });
     if (adoptionBoot.scanned > 0 || adoptionBoot.error !== undefined) {
         logger.info("adoption_boot_scan", { ...adoptionBoot });
@@ -1073,6 +1079,16 @@ async function main() {
         memorySync: memoryExportBackend && memorySyncCursors
             ? (scope, syncReq) => performMemorySync(memoryExportBackend, memorySyncCursors, scope, syncReq)
             : undefined,
+        // #264 v2-c(core 5.40.0):治理携出 bundle 的两口 —— POST /v1/memory/export · POST /v1/memory/import。
+        // 数据源是**装配好的记忆引擎本体**(不是 memoryExportBackend 那条 DB entry plane):bundle 是引擎
+        // 的单锁复合面(条目 + 托管链 + 挑战 + lineage + 污染标记同一个 epoch),不是条目读的超集。
+        // 🔴 两口共用一个在场判据,因为它们是同一个引擎面的两半(半挂 = 导得出导不进,而这条产品面的全部
+        // 意义就是那趟往返)。判据是**两项**:引擎在场 ∧ 其后端实现了 bundle 复合面 —— 后者由
+        // createMemoryBundleFaces 在**挂载期**判(返回 undefined ⇒ 两口不挂、能力位翻假、打上去诚实 501),
+        // 而不是照常挂着让每次调用确定性 409(codex 对抗复审 [medium] 驳回的那一版:一个恒假的 yes)。
+        // 绝不在本层为缺面的后端现造替代实现——理由逐字见 routes/memory-bundle.ts 的「能力面的诚实形」。
+        memoryBundleExport: memoryBundleFaces ? memoryBundleFaces.exportScopes : undefined,
+        memoryBundleImport: memoryBundleFaces ? memoryBundleFaces.importBundle : undefined,
         // design/170 件A §7 收编:memory-policy 面的 `org:` 属主门与 core 准入 seam 读**同一个**目录实例
         // (`createOrgMemoryAdmissionWiring` 的产物),两面因此共享 TTL 缓存/退避窗/gen 高水位 —— 一个进程
         // 对「谁属于 org:acme」只有一个答案。缺席(无 center 且无 env 表)⇒ 策略面 `org:` 键仍 operator-only。

package/dist/memory-bundle-engine.d.ts

@@ -0,0 +1,64 @@
+/**
+ * #264 v2-c —— `POST /v1/memory/{export,import}` 两口的**引擎接线**(core 5.40.0 design/178 v2-c)。
+ *
+ * ## 为什么需要这个模块(而不是在 main.ts 里直接 new)
+ *
+ * 本仓**没有**一个长命的 `MemoryEngine` 实例:`boot/stores.ts` 装配出来的 `memoryEngine` 是
+ * `{ backend, root }` 二元组,真正的引擎由 **core 的 Runner 每任务现构**
+ * (`core/runner/prepare-memory.js`),而且构出来的 `memoryDir` 是**按任务的 scope 平面**决定的
+ * (personal / project / dual-root 三形,还要看仓根、项目标记、pinned 目录)。
+ * 也就是说「这个部署的那一个记忆引擎」这个东西**在本仓不存在** —— HTTP 面若要一个引擎,必须自己构。
+ *
+ * ## 为什么自己构是安全的:这两个面是 **backend-scoped**,不碰 `memoryDir`
+ *
+ * 亲读 core 5.40.0 的 `memory-engine/engine.js`(不信 JSDoc,读实现):
+ *  · `exportMemoryScopes` 全身只用 `this.backend.exportSnapshotOf` 与 `this.now()`;
+ *  · `importMemoryBundle` 全身只用 `this.backend.importBundleCommit`(校验段是纯函数 `memoryBundleInvalid`)。
+ * 两条路径**都不读** `memoryDir` / `controlDir` —— 它们是**店级**的单锁复合面(一个 epoch 里把五张
+ * 店面围起来),不是「某个任务挂载的那棵树」上的操作。因此本模块传给构造器的 `memoryDir` 只是**构造器
+ * 的必填座**,对这两条路径无影响。
+ *
+ * 🔴 这条判断是承重的,所以它有**机器钉**而不是只有这段注释:`test/memory-bundle-engine.test.ts` 用一只
+ * 假 backend 断言两条路径确实落到 `exportSnapshotOf` / `importBundleCommit`,且给一个**不存在的**
+ * `memoryDir` 也照样工作。core 哪天让这两条路径去读挂载树,那道钉当场红 —— 而不是在某个部署上静默
+ * 读错一棵树。
+ *
+ * ## 能力缺席在**构造期**判定(不挂一个注定失败的口)
+ *
+ * backend 没有那两个可选面(本仓两只 SQL 记忆孪生就没有)⇒ 本工厂返回 **undefined**,两口整个不挂载,
+ * HTTP 面诚实 501。
+ *
+ * 🔴 首版把这件事当成**运行期**事实(照常挂载,让 core 每次抛 `memory.export_incomplete` / 422),
+ * 被 codex 对抗复审驳倒(#277 提货批 [medium],验真后修):`typeof backend.exportSnapshotOf === "function"`
+ * 是一次**属性检查**,boot 期就判得出;而且它是**永久**缺席(换后端才会变),不是瞬时状态。照旧挂着
+ * 就成了「能力位说 yes、每一次调用都确定性失败」——本仓「says yes ⟺ route works」是结构性承诺,
+ * 一个恒假的 yes 会让壳给用户开出一条走不通的迁移流程。
+ *
+ * ⚠️ 两面是**一个**能力,判据取合取:只有一半也不挂。半挂的形是「导得出、导不进」,而这条产品面的
+ * 全部意义是那趟往返。
+ *
+ * ⚠️ 与**运行期**拒不是一回事,别合并:面齐备但店自陈说不清(chain-degraded)时,core 照样抛
+ * `memory.export_incomplete` —— 那是诚实的运行期拒,附录 A 单列一条。绝不在这里回落到「用通用读面拼
+ * 一个包」:core 明写那正是它拒绝生产的形(a governance-less export is the laundering shape)。
+ */
+import { type MemoryBackend, type MemoryExportBundle, type MemoryImportReport } from "@sema-agent/core";
+/** 两口 HTTP 面消费的窄能力面(`ServiceDeps.memoryBundle{Export,Import}` 的实参来源)。 */
+export interface MemoryBundleFaces {
+    exportScopes: (scopes: readonly string[]) => Promise<MemoryExportBundle>;
+    /** 入参 `unknown`:调用方递交的是未校验的对象,整包判决归 core(理由见 ServiceDeps 同名 seam 的注)。 */
+    importBundle: (bundle: unknown, opts?: {
+        expectedScopes?: readonly string[];
+    }) => Promise<MemoryImportReport>;
+}
+/**
+ * 在**已装配的记忆后端**上建 bundle 两面。命名照 CLAUDE.md 工厂律:返回的是带行为的活对象 ⇒ `create*`。
+ *
+ * `memoryDir` = `boot/stores.ts` 的 `memoryEngine.root`(该部署的记忆工作根)。见文件头:这两条路径
+ * 不读它,传它是为了不发明第二个「引擎根」的概念 —— 万一 core 日后真用上,它拿到的也是本部署唯一的
+ * 那个根,而不是一个本模块凭空编出来的路径。
+ */
+export declare function createMemoryBundleFaces(store: {
+    backend: MemoryBackend;
+    root: string;
+}): MemoryBundleFaces | undefined;
+//# sourceMappingURL=memory-bundle-engine.d.ts.map

package/dist/memory-bundle-engine.js

@@ -0,0 +1,67 @@
+/**
+ * #264 v2-c —— `POST /v1/memory/{export,import}` 两口的**引擎接线**(core 5.40.0 design/178 v2-c)。
+ *
+ * ## 为什么需要这个模块(而不是在 main.ts 里直接 new)
+ *
+ * 本仓**没有**一个长命的 `MemoryEngine` 实例:`boot/stores.ts` 装配出来的 `memoryEngine` 是
+ * `{ backend, root }` 二元组,真正的引擎由 **core 的 Runner 每任务现构**
+ * (`core/runner/prepare-memory.js`),而且构出来的 `memoryDir` 是**按任务的 scope 平面**决定的
+ * (personal / project / dual-root 三形,还要看仓根、项目标记、pinned 目录)。
+ * 也就是说「这个部署的那一个记忆引擎」这个东西**在本仓不存在** —— HTTP 面若要一个引擎,必须自己构。
+ *
+ * ## 为什么自己构是安全的:这两个面是 **backend-scoped**,不碰 `memoryDir`
+ *
+ * 亲读 core 5.40.0 的 `memory-engine/engine.js`(不信 JSDoc,读实现):
+ *  · `exportMemoryScopes` 全身只用 `this.backend.exportSnapshotOf` 与 `this.now()`;
+ *  · `importMemoryBundle` 全身只用 `this.backend.importBundleCommit`(校验段是纯函数 `memoryBundleInvalid`)。
+ * 两条路径**都不读** `memoryDir` / `controlDir` —— 它们是**店级**的单锁复合面(一个 epoch 里把五张
+ * 店面围起来),不是「某个任务挂载的那棵树」上的操作。因此本模块传给构造器的 `memoryDir` 只是**构造器
+ * 的必填座**,对这两条路径无影响。
+ *
+ * 🔴 这条判断是承重的,所以它有**机器钉**而不是只有这段注释:`test/memory-bundle-engine.test.ts` 用一只
+ * 假 backend 断言两条路径确实落到 `exportSnapshotOf` / `importBundleCommit`,且给一个**不存在的**
+ * `memoryDir` 也照样工作。core 哪天让这两条路径去读挂载树,那道钉当场红 —— 而不是在某个部署上静默
+ * 读错一棵树。
+ *
+ * ## 能力缺席在**构造期**判定(不挂一个注定失败的口)
+ *
+ * backend 没有那两个可选面(本仓两只 SQL 记忆孪生就没有)⇒ 本工厂返回 **undefined**,两口整个不挂载,
+ * HTTP 面诚实 501。
+ *
+ * 🔴 首版把这件事当成**运行期**事实(照常挂载,让 core 每次抛 `memory.export_incomplete` / 422),
+ * 被 codex 对抗复审驳倒(#277 提货批 [medium],验真后修):`typeof backend.exportSnapshotOf === "function"`
+ * 是一次**属性检查**,boot 期就判得出;而且它是**永久**缺席(换后端才会变),不是瞬时状态。照旧挂着
+ * 就成了「能力位说 yes、每一次调用都确定性失败」——本仓「says yes ⟺ route works」是结构性承诺,
+ * 一个恒假的 yes 会让壳给用户开出一条走不通的迁移流程。
+ *
+ * ⚠️ 两面是**一个**能力,判据取合取:只有一半也不挂。半挂的形是「导得出、导不进」,而这条产品面的
+ * 全部意义是那趟往返。
+ *
+ * ⚠️ 与**运行期**拒不是一回事,别合并:面齐备但店自陈说不清(chain-degraded)时,core 照样抛
+ * `memory.export_incomplete` —— 那是诚实的运行期拒,附录 A 单列一条。绝不在这里回落到「用通用读面拼
+ * 一个包」:core 明写那正是它拒绝生产的形(a governance-less export is the laundering shape)。
+ */
+import { MemoryEngine } from "@sema-agent/core";
+/**
+ * 在**已装配的记忆后端**上建 bundle 两面。命名照 CLAUDE.md 工厂律:返回的是带行为的活对象 ⇒ `create*`。
+ *
+ * `memoryDir` = `boot/stores.ts` 的 `memoryEngine.root`(该部署的记忆工作根)。见文件头:这两条路径
+ * 不读它,传它是为了不发明第二个「引擎根」的概念 —— 万一 core 日后真用上,它拿到的也是本部署唯一的
+ * 那个根,而不是一个本模块凭空编出来的路径。
+ */
+export function createMemoryBundleFaces(store) {
+    // 构造期能力判定(见文件头):两个可选面缺任一 ⇒ 整个不挂。判据直接读 backend 的面,不看后端方言名
+    // ——「认能力不认实现名」是本仓的既有教训(按部署名判「组件已装」认不出 helm 装的那次)。
+    const b = store.backend;
+    if (typeof b.exportSnapshotOf !== "function" || typeof b.importBundleCommit !== "function")
+        return undefined;
+    const engine = new MemoryEngine({ backend: store.backend, memoryDir: store.root });
+    return {
+        exportScopes: (scopes) => engine.exportMemoryScopes(scopes),
+        // 唯一一次窄化,就发生在**引擎边界上**:core 的 d.ts 要 MemoryExportBundle,而它的实装第一件事
+        // 就是 JSON 深拷 + `memoryBundleInvalid` 整包校验 —— 也就是说这个形参在运行期本就接受任意值,
+        // 由它自己裁。把窄化收在这一行(而不是让它一路污染 HTTP 层的类型)是「谁裁决谁承型」。
+        importBundle: (bundle, opts) => engine.importMemoryBundle(bundle, opts),
+    };
+}
+//# sourceMappingURL=memory-bundle-engine.js.map

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

@@ -0,0 +1,116 @@
+/**
+ * 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";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+export interface ApprovalRow {
+    id: string;
+    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;
+    status: ApprovalStatus;
+    reason: string | null;
+    decidedBy: string | null;
+    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;
+        sessionId?: string | null;
+        owner?: string | null;
+        toolName: string;
+        args: unknown;
+    }): Promise<void>;
+    getStatus(id: string, scope: string | null): Promise<{
+        status: ApprovalStatus;
+        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);
+}
+//# sourceMappingURL=approval-store-sql.d.ts.map

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

@@ -0,0 +1,151 @@
+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,
+     task_id     VARCHAR(64),
+     session_id  VARCHAR(64),
+     owner       VARCHAR(190),
+     -- Single-DB fleet scope guard (tenant isolation). NULLABLE on purpose: a NULL-scope row is an untenanted
+     -- run, and every read/decide path matches it with \`scope IS NOT DISTINCT FROM $n\` (the PG twin of TiDB
+     -- \`<=>\`) so NULL matches only NULL and one tenant's scope NEVER matches another's.
+     scope       VARCHAR(190),
+     tool_name   VARCHAR(190) NOT NULL,
+     args        JSONB,
+     status      VARCHAR(16)  NOT NULL,
+     reason      TEXT,
+     decided_by  VARCHAR(190),
+     created_at  TIMESTAMPTZ(3) NOT NULL,
+     decided_at  TIMESTAMPTZ(3),
+     PRIMARY KEY (id)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_owner_status ON approval (owner, status)`,
+    `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);
+    }
+    async createPending(id, scope, ctx) {
+        await this.db.query(this.q("INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES (?,?,?,?,?,?,?,'pending',?)", "INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,'pending',$8)"), [
+            id,
+            ctx.taskId ?? null,
+            ctx.sessionId ?? null,
+            ctx.owner ?? null,
+            scope,
+            ctx.toolName,
+            ctx.args == null ? null : this.json(ctx.args, "approval args"),
+            new Date(),
+        ]);
+    }
+    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])
+            : await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 ORDER BY created_at ASC"), [scope]);
+        return rows.map(mapRow);
+    }
+    async get(id, scope) {
+        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 = ? " +
+            "WHERE status = 'pending' AND created_at < ?", "UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = $1 " +
+            "WHERE status = 'pending' AND created_at < $2"), [new Date(), cutoff]);
+        return res.affected;
+    }
+}
+/** approval row → {@link ApprovalRow} — shared by BOTH dialects. design/158 S8 归位 / A12 收编. */
+export function mapRow(r) {
+    return {
+        id: String(r.id),
+        taskId: r.task_id ?? null,
+        sessionId: r.session_id ?? null,
+        owner: r.owner ?? null,
+        scope: r.scope ?? null,
+        toolName: String(r.tool_name),
+        args: parseJson(r.args),
+        status: r.status,
+        reason: r.reason ?? null,
+        decidedBy: r.decided_by ?? null,
+        createdAt: iso(r.created_at),
+        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));
+    }
+}
+//# sourceMappingURL=approval-store-sql.js.map

package/dist/plugins/file-workflow-journal-store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
+export { FileWorkflowJournalStore } from "@sema-agent/core";
+//# sourceMappingURL=file-workflow-journal-store.d.ts.map

package/dist/plugins/file-workflow-journal-store.js

@@ -0,0 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
+export { FileWorkflowJournalStore } from "@sema-agent/core";
+//# sourceMappingURL=file-workflow-journal-store.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
+export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, type ApprovalRow, type ApprovalStatus, } from "./approval-store-sql.js";
+//# sourceMappingURL=pg-approval-store.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
+export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, } from "./approval-store-sql.js";
+//# sourceMappingURL=pg-approval-store.js.map

package/dist/plugins/pg-breaker-state.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
+export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
+//# sourceMappingURL=pg-breaker-state.d.ts.map

package/dist/plugins/pg-breaker-state.js

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
+export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
+//# sourceMappingURL=pg-breaker-state.js.map

package/dist/plugins/pg-checkpoint-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
+export { PgCheckpointStore } from "./checkpoint-store-sql.js";
+//# sourceMappingURL=pg-checkpoint-store.d.ts.map

package/dist/plugins/pg-checkpoint-store.js

@@ -0,0 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
+export { PgCheckpointStore } from "./checkpoint-store-sql.js";
+//# sourceMappingURL=pg-checkpoint-store.js.map

package/dist/plugins/pg-file-snapshot-store.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
+export { PgFileSnapshotStore } from "./file-snapshot-store-sql.js";
+//# sourceMappingURL=pg-file-snapshot-store.d.ts.map