@sema-agent/server 7.3.0 → 7.4.0

package/dist/observability/fail-open.js

@@ -0,0 +1,216 @@
+/**
+ * #157 fail-open 治理专项 —— 兜底路径的**响亮化**工具(server 半场;跨仓方案见 sema-comms
+ * `audits/failopen-governance-176.md` §2,三仓语义对齐、实现各自)。
+ *
+ * ## 它解决的问题
+ * 「走了兜底」与「一切正常」在外部**同形**——成功回执一样、日志一样、指标一样。于是一个静默降级
+ * 能带病运行数周,只能靠"该发生的事没发生"这种间接症状发现。本模块给每条合法兜底臂一个**登记过的
+ * tag**,走到即留痕三件套:
+ *
+ *  1. **计数(逐次)** —— `fail_open_total{tag,cls}`;
+ *  2. **探针文件(逐次)** —— `SEMA_FAILOPEN_PROBE=<path>` 在场时逐次追加 `fail-open <tag> <detail>`。
+ *     逐次是承重的:同进程多腿时"第二腿起无行"会让「无行=没走兜底」的黑盒断言变成假绿;
+ *  3. **一次性 warn(每进程每 tag 一次)** —— 防刷屏。**只有这一件是一次性的**,计数与探针都逐次。
+ *
+ * ## 它**不**解决的问题(封装不是合法化通道)
+ * 词表的 `cls` 只有 `F` 与 `P-DEBT` 两种,**结构性**地把 P/Z 类挡在外面:
+ *  - **P 保护型**(权限门/判定词表/凭证/车道选择):正解是 fail-closed,不是"留痕后继续放行"。
+ *    确实一时改不动的,才允许以 `P-DEBT` 登记——让债在遥测里显形,而不是让它消失。
+ *  - **Z 计量型**(重试/预算/超时/清理范围):正解是归零 + 自己的节流告警
+ *    (先例:`boot/reapers.ts` 的 `createThrottledReaperCatch`),不走本封装。
+ *
+ * ## 词表是闭集
+ * {@link FailOpenTag} 由 {@link FAIL_OPEN_TAGS} 的键推导,未登记的 tag 是**编译期错误**——
+ * "新 tag 须登记"因此是机器执法的,不靠自觉。新增 tag 同时要在 `docs/FAIL-OPEN-CENSUS.md` 补行。
+ *
+ * ## 进程级而非注入级
+ * 三件套里有两件(一次性 warn、进程计数)天然是**进程**范围的,且真正的兜底臂往往在没有 logger/
+ * metrics 句柄的深处(`question.ts` / `elicitation.ts` 全文零观测通道)。所以对外主口是自由函数
+ * {@link recordFailOpen},装配层用 {@link installFailOpenRecorder} 把 logger/metrics 接上即可;
+ * 装配之前的调用不会丢——探针与 stderr 契约行不依赖注入,计数也照常累加并在装配时继承过去。
+ */
+import { appendFileSync } from "node:fs";
+/** 闭集 tag 词表。形=`<repo>.<domain>.<site>`(跨仓同形,便于三仓遥测并表)。 */
+export const FAIL_OPEN_TAGS = {
+    "server.hitl.frame-undelivered-stream-closed": {
+        cls: "P-DEBT",
+        note: "HITL 的 **open** 帧(question / elicitation)写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,问到 TTL 才按无人应答结算。方向(no-op 而非 throw)是既有的刻意决定,本条只保证它不再无声。",
+    },
+    "server.stream.frame-dropped-stream-closed": {
+        cls: "F",
+        note: "非 HITL-open 的运行流帧写向已断连接 ⇒ 丢弃。连接都没了,这一帧本就无人可看;单独立项是为了不让它挤进上面那条保护型计数。",
+    },
+    "server.question.open-frame-undelivered": {
+        cls: "P-DEBT",
+        note: "AskUserQuestion 的 open 帧投递失败 ⇒ 按 headless 默认结算,模型不问人自己往下判。方向是刻意的产品姿态(绝不把 run 挂死),但一次投递故障确实让人在环这道门被跳过——记债,不当合法兜底。",
+    },
+    "server.elicitation.open-frame-undelivered": {
+        cls: "F",
+        note: "MCP elicitation 的 open 帧投递失败 ⇒ 结算 decline。方向本身是 fail-closed(问不到人就是拒),缺的只是留痕。",
+    },
+    "server.question.complete-breadcrumb-dropped": {
+        cls: "F",
+        note: "question_complete 面包屑(对话框消解提示)持久化失败。答案本身走的是另一条路且早已返回,丢的只是壳里一次收尾渲染。",
+    },
+    "server.elicitation.complete-breadcrumb-dropped": {
+        cls: "F",
+        note: "elicitation_complete 面包屑持久化失败。同上——答案已经在壳手里,丢的是收尾渲染。",
+    },
+    "server.prompts.artifact-cache-write-failed": {
+        cls: "F",
+        note: "已验签的提示词工件回填本地缓存失败。工件本身已返回给调用方;代价是下次同 digest 还要再取一次网络。",
+    },
+};
+/**
+ * 断流丢帧该记哪个 tag —— **按帧型分类**,纯函数(与写流的那条闭包解耦,才单测得动)。
+ *
+ * 一刀切记同一个 tag 是错的:承载 HITL 帧的那条闭包同时驮着完成面包屑与其它运行流帧,于是**一次**
+ * 断连会让保护型计数涨两次(open 一次、complete 又一次),真正的 open 失败率被面包屑的假阳性盖住。
+ * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
+ */
+export function failOpenTagForDroppedFrame(frameType) {
+    switch (frameType) {
+        case "question":
+        case "elicitation":
+            return "server.hitl.frame-undelivered-stream-closed";
+        case "question_complete":
+            return "server.question.complete-breadcrumb-dropped";
+        case "elicitation_complete":
+            return "server.elicitation.complete-breadcrumb-dropped";
+        default:
+            return "server.stream.frame-dropped-stream-closed";
+    }
+}
+/** 探针文件的 env 名(跨仓同名同形:`audits/failopen-governance-176.md` §2-r2,壳/引擎同认)。 */
+export const FAIL_OPEN_PROBE_ENV = "SEMA_FAILOPEN_PROBE";
+/** 计数器名。`cls` 进标签:一眼分得出"合法兜底"与"保护型欠账"两种曲线,后者应当只降不升。 */
+const FAIL_OPEN_COUNTER = "fail_open_total";
+export function createFailOpenRecorder(deps = {}) {
+    const counts = new Map(deps.seedCounts ?? []);
+    const warned = new Set(deps.seedWarned ?? []);
+    const logged = new Set(deps.seedLogged ?? []);
+    const backlog = new Map(deps.seedBacklog ?? []);
+    const probePath = deps.probePath ?? process.env[FAIL_OPEN_PROBE_ENV];
+    const writeStderr = deps.writeStderr ?? ((line) => void process.stderr.write(line));
+    const appendProbe = deps.appendProbe ?? ((path, line) => appendFileSync(path, line));
+    deps.metrics?.counter(FAIL_OPEN_COUNTER, "fallback (fail-open) arms traversed, by registered tag — see docs/FAIL-OPEN-CENSUS.md");
+    // 补账:装配前(无 metrics/无 logger)命中的那几次不能凭空消失——否则 `fail_open_total` 永久
+    // 少算,少的还正是 boot 期兜底。metrics 到场即把欠账一次性灌进去并清零(所以再 install 一次不会重放),
+    // 结构化 warn 同理按 tag 补一条。stderr 契约行**不补**:它在装配前就已经喊过了,一 tag 一次是它的全部价值。
+    // 🔴 记账**后于**投递(codex R2 复审 MEDIUM):先清 backlog / 先 `logged.add` 再投递,等于把一次
+    // 投递失败记成"已送达"——欠账从此无法重放,而它保的正是最需要补的那批 boot 期兜底。
+    if (deps.metrics !== undefined && backlog.size > 0) {
+        for (const [tag, n] of [...backlog]) {
+            try {
+                deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: FAIL_OPEN_TAGS[tag].cls }, n);
+                backlog.delete(tag); // 只有真进了汇才销账
+            }
+            catch {
+                /* 留在 backlog 里,下一次装配再补 */
+            }
+        }
+    }
+    // 补痕的起算集=**观测到的 tag 全集**(`counts`),不是"stderr 喊成功过的那批"(`warned`)——
+    // 后者在"装配前命中 + stderr 正断裂"这条组合路上恒空,那次兜底的结构化痕迹就永久没了(codex R3)。
+    if (deps.logger !== undefined) {
+        for (const tag of counts.keys()) {
+            if (logged.has(tag))
+                continue;
+            try {
+                deps.logger.warn("fail_open", { tag, cls: FAIL_OPEN_TAGS[tag].cls, note: FAIL_OPEN_TAGS[tag].note, backfilled: true });
+                logged.add(tag); // 同上:warn 真发出去才算已报
+            }
+            catch {
+                /* 不记 logged,下一次装配/下一次命中再补 */
+            }
+        }
+    }
+    return {
+        record: (tag, detail) => {
+            // 三件套逐件独立 try:一件的失败(坏路径的探针文件、抛错的 logger 传输)绝不能让**另外两件**
+            // 也丢,更不能让调用方的兜底臂变成抛错——那等于把"降级"换成"故障",正是本模块要消灭的方向。
+            const entry = FAIL_OPEN_TAGS[tag];
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+            if (deps.metrics === undefined) {
+                backlog.set(tag, (backlog.get(tag) ?? 0) + 1); // 记欠账,等 install 补
+            }
+            else {
+                try {
+                    deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: entry.cls });
+                }
+                catch {
+                    // 汇在场但这一次没进去 ⇒ 同样记欠账(而不是蒸发),等下一次装配补。
+                    backlog.set(tag, (backlog.get(tag) ?? 0) + 1);
+                }
+            }
+            if (probePath !== undefined && probePath !== "") {
+                try {
+                    appendProbe(probePath, `fail-open ${tag}${detail !== undefined && detail !== "" ? ` ${detail}` : ""}\n`);
+                }
+                catch {
+                    /* 探针路径不可写(只读盘/权限)⇒ 静默放弃,不牵连本次兜底 */
+                }
+            }
+            // 只有**真发出去**才记进 logged —— 没有 logger 时记了,会让日后 install 的补账把这条当成
+            // "已经报过"而跳过,那正是本轮复审要修的漏账形。
+            if (deps.logger !== undefined && !logged.has(tag)) {
+                try {
+                    deps.logger.warn("fail_open", { tag, cls: entry.cls, note: entry.note, ...(detail !== undefined ? { detail } : {}) });
+                    logged.add(tag); // 记账后于投递:没发出去就不算已报,下一次命中重试
+                }
+                catch {
+                    /* 观测不得成为故障 */
+                }
+            }
+            if (warned.has(tag))
+                return;
+            try {
+                // 跨仓约定的黑盒锚,逐字 `[sema] fail-open: <tag>`。**不依赖** logger 是否装配上——
+                // 评测线的断言打的就是这一行,它在 boot 之前的兜底上也必须成立。
+                writeStderr(`[sema] fail-open: ${tag}\n`);
+                warned.add(tag); // 同上。stderr 永久断裂时代价=每次命中试写一次(有界),不是丢掉这条契约行
+            }
+            catch {
+                /* 断裂的 stderr(EPIPE 族)⇒ 丢这行,不丢进程 */
+            }
+        },
+        counts: () => counts,
+        warnedTags: () => warned,
+        metricsBacklog: () => backlog,
+        loggedTags: () => logged,
+    };
+}
+/** 进程单例。装配前也可用(探针+stderr 契约行照常,计数照常;只是没有结构化 warn/metric)。 */
+let current = createFailOpenRecorder();
+/**
+ * 装配层接线:把 logger/metrics 接到进程单例上。搬四份状态过去,各有各的理由:
+ *  - `seedCounts` —— 逻辑总数续算,不从 0 重来;
+ *  - `seedWarned` —— boot 期已喊过的 stderr 契约行不再喊(「每进程每 tag 一次」是它的全部价值);
+ *  - `seedBacklog` —— 装配**前**命中的次数还没进任何 metrics 汇,交给新实例补账(补完清零,
+ *    所以第二次 install 不会重放);
+ *  - `seedLogged` —— 已真发出去的结构化 warn 不重发;没发过的由新 logger 补一条。
+ */
+export function installFailOpenRecorder(deps) {
+    current = createFailOpenRecorder({
+        ...deps,
+        seedCounts: current.counts(),
+        seedWarned: current.warnedTags(),
+        seedBacklog: current.metricsBacklog(),
+        seedLogged: current.loggedTags(),
+    });
+    return current;
+}
+/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因,不放密钥)。 */
+export function recordFailOpen(tag, detail) {
+    current.record(tag, detail);
+}
+/** 本进程各 tag 累计次数——`/metrics` 之外的进程内读数(测试与自检面用)。 */
+export function failOpenCounts() {
+    return current.counts();
+}
+/** test-only:换一个全新单例(计数与 warn 集合清零),让每个用例都从"第一次"看起。 */
+export function resetFailOpenRecorderForTest(deps = {}) {
+    current = createFailOpenRecorder(deps);
+    return current;
+}
+//# sourceMappingURL=fail-open.js.map

package/dist/observability/prompt-manifest.d.ts

@@ -31,6 +31,12 @@ export interface PromptManifestRecord {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
+    /** core 5.15.0(#181):deferred 披露策略自证三键(诊断值,零内容)。缺席=core <5.15 或无 deferred。 */
+    toolDisclosure?: {
+        deferredTools: number;
+        strategy: string;
+        source: string;
+    };
     totalChars: number;
 }
 /** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
@@ -61,6 +67,13 @@ export declare function promptManifestRecordOf(e: {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
+    /** core 5.15.0(#181,[2872] 提货②):deferred 工具的披露策略自证——{deferredTools(数), strategy
+     *  ("static"|"swap"), source(四值:spec/env/api-default/default)}。诊断三键(数+两闭集词,零内容)。 */
+    toolDisclosure?: {
+        deferredTools: number;
+        strategy: string;
+        source: string;
+    };
     totalChars: number;
 }): PromptManifestRecord;
 /**

package/dist/observability/prompt-manifest.js

@@ -14,6 +14,14 @@ export function promptManifestRecordOf(e) {
         ...(Array.isArray(e.tools)
             ? { tools: e.tools.map((t) => ({ wireName: String(t.wireName), aliases: (Array.isArray(t.aliases) ? t.aliases : []).map(String), contractId: String(t.contractId), implementationRevision: String(t.implementationRevision), cardId: String(t.cardId), shapeDigest: String(t.shapeDigest), wireSchemaDigest: String(t.wireSchemaDigest) })) }
             : {}),
+        // toolDisclosure(core 5.15.0 #181,[2872] 提货②):三键逐挑——数值有限、两词字符串非空才铸;
+        // 畸形按缺席(不铸假值,与 sections/tools 的 additive 同规)。
+        ...(typeof e.toolDisclosure === "object" && e.toolDisclosure !== null &&
+            typeof e.toolDisclosure.deferredTools === "number" && Number.isFinite(e.toolDisclosure.deferredTools) &&
+            typeof e.toolDisclosure.strategy === "string" && e.toolDisclosure.strategy.length > 0 &&
+            typeof e.toolDisclosure.source === "string" && e.toolDisclosure.source.length > 0
+            ? { toolDisclosure: { deferredTools: e.toolDisclosure.deferredTools, strategy: e.toolDisclosure.strategy, source: e.toolDisclosure.source } }
+            : {}),
         totalChars: e.totalChars,
     };
 }

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

package/dist/plugins/pg-file-snapshot-store.js

@@ -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.js.map