@sema-agent/server 7.50.0 → 7.52.0

package/dist/plugins/file-run-store.d.ts

@@ -34,6 +34,20 @@ import type { TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
+/**
+ * `RUN_STORE_STRICT_HYDRATE=on` 下 hydrate 列不出 `runs/` 时的**拒启**类型(S-46 件B;codex 对抗复审
+ * R1-[high] 验真后从裸 `Error` 升成具名类型)。
+ *
+ * 🔴 **为什么必须是一个类型而不是一句文案**:`openStoreBackendWithFallback` 对**默认推导**的 local
+ * (`DB_BACKEND` 未设)有一条既有降级臂 —— mkdir / 只读盘那类「这台机器存不了盘」的失败降级到内存继续起。
+ * 本拒启从 `new LocalBackend(...)` 里冒出来,长得和它们一模一样,不给它一个可判别的身份就会被同一个
+ * catch 吞掉:operator 明确要的 **fail-closed 反而变成 fail-open**,而且丢的正是持久 run 账本(这根旋钮
+ * 存在的全部理由)。判据锚在**类型**上,不在文案上 —— 文案会改,类型不会(同文件族先例:`AdoptionError`
+ * 在同一个降级臂里也是按类型无条件重抛)。
+ */
+export declare class RunStoreStrictHydrateError extends Error {
+    readonly name = "RunStoreStrictHydrateError";
+}
 export declare class FileRunStore {
     private readonly runsDir;
     private readonly activeDir;
@@ -55,8 +69,12 @@ export declare class FileRunStore {
     private readonly claimLocks;
     /** 件6(#43 案 [4281]):启动期告警座(可选)。既有调用方不传 ⇒ 只走 fail-open 遥测那一半,不炸。 */
     private readonly logger;
-    constructor(root: string, logger?: {
+    /** S-46 件B(census 第 29 行终局):`RUN_STORE_STRICT_HYDRATE` 的**部署级**表态。
+     *  `true` ⇒ hydrate 的 readdir 失败拒启;缺席/`false` ⇒ 件6 的记债腿,行为字节不变。 */
+    private readonly strictHydrate;
+    constructor(root: string, opts?: {
         error?(msg: string, fields?: Record<string, unknown>): void;
+        strictHydrate?: boolean;
     });
     private runDir;
     private runJsonPath;
@@ -69,6 +87,26 @@ export declare class FileRunStore {
      *  partial-write-safe (run.json via atomicWriteFile can never be half-written; the active file via writeThenLink is
      *  all-or-nothing; events.jsonl via readJsonlRecords drops a crash tail). A corrupt run.json (failed parse) is
      *  skipped — that run is lost, not a poison that fails the boot. */
+    /**
+     * hydrate 期**逐文件**读盘的统一口(S-46 件B / codex 对抗复审 R4-[high])。
+     *
+     * `readJsonlRecords` 对 ENOENT 答 `[]`、对其余读错(EACCES / EIO / EISDIR / ENOTDIR)**抛普通 Error**
+     * (亲验 core `dist/stores/file/fs-atomic.js:110-112`)。那个普通 Error 从构造器冒出去之后,在**默认
+     * 推导**的 local 后端上会被 `openStoreBackendWithFallback` 的降级臂吞成 memory —— 也就是说 strict 开着
+     * 也照样带着残缺账本(或直接换成内存)起动,两处 readdir 门白守。
+     *
+     * ⇒ strict 档:非 ENOENT 的读盘失败一律转成 {@link RunStoreStrictHydrateError}(带路径 + 原文),由
+     * `store-backend.ts` 的按类型重抛穿过降级臂。**strict 关时逐字不变**:原样把那只 Error 抛回去(既不
+     * 吞、也不改形),既有的「坏行跳过、不毒 boot」宽容契约与既有的抛法一起原封保留。
+     */
+    private replay;
+    /**
+     * strict 档下的**存在性判别**(codex R4-[high] 的前半):`existsSync` 对 ENOENT 与 EACCES 同答 false,
+     * 而这两句话在本门下必须分开 —— 前者是常态(`runs/` 下的非目录杂物、还没落盘的目录),后者是「我读
+     * 不出它有没有」。只在 strict 档多付一次 `statSync`;ENOENT/ENOTDIR 一族原样放行(继续跳过),其余
+     * 一律拒启。
+     */
+    private refuseIfUnreadable;
     private hydrate;
     /** Commit a RunRow to disk (whole-file atomic replace) AND the index — the single write path for every status change. */
     private persist;
@@ -103,8 +141,9 @@ export declare class FileRunStore {
     setSuspended(taskId: string): Promise<void>;
     /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     setNeedsReview(taskId: string): Promise<void>;
-    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
-    markResuming(taskId: string): Promise<boolean>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
+     *  S-51(codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
+    markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
@@ -182,7 +221,7 @@ export declare class FileRunStore {
      * probe instead of a SQL JOIN (formerly a NO-OP — one of the five closed doors in the "suspended run locks the
      * session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff ∧ NOT
      * probe.hasPending(session) → failed 'approval expired before decision' / errorCode 'approval.expired' +
-     * release the task_active claim. The NOT-pending clause is the design/80 D-D adversarial-blocker guard
+     * release the task_active claim. The NOT-pending clause is the design/80 D-D blocker guard
      * (SQL 孪生现在的真身:`run-store-sql.ts` 的 `reapSuspended`;`tidb-run-store.ts` 该壳文件已删(5.0.0)): a row whose checkpoint is STILL pending belongs to the checkpoint-state sweeps —
      * time-reaping it would orphan a model leg on a now-unlocked session. Probe absent ⇒ honest NO-OP.
      * MemoryRunStore is the parity oracle (byte-identical predicate; only the persist differs).
@@ -202,7 +241,7 @@ export declare class FileRunStore {
      *
      * 复审 R2 [high]:反过来(索引优先)会在「同进程两只实例、两边索引都热」时出事 —— A 把 park 行
      * `markResuming` 成 running 并消费掉 checkpoint,B 的索引里还留着**旧的 park 对象**;B 于是读不到
-     * 变化、拿自己那份陈旧对象通过复核,把 A 正在跑的行盖成 failed 再放锁。盘是唯一权威,判据只能读盘。
+     * 变化、拿自己那份陈旧对象通过复核,把 A 正在跑的行覆盖为 failed 再放锁。盘是唯一权威,判据只能读盘。
      * 回退内存索引只为「行还没落盘」这一种形(理论上不该出现,留着不让判据凭空缺行)。
      * 代价:只在 EEXIST 争用路径上多一次读文件,常路零开销。
      */

package/dist/plugins/file-run-store.js

@@ -1,6 +1,6 @@
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { join } from "node:path";
-import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -32,6 +32,9 @@ function isPidAlive(pid) {
     }
 }
 const PARK_ORPHAN_SETTLE_MS = 30_000;
+export class RunStoreStrictHydrateError extends Error {
+    name = "RunStoreStrictHydrateError";
+}
 export class FileRunStore {
     runsDir;
     activeDir;
@@ -44,14 +47,27 @@ export class FileRunStore {
     claimOwner = { nonce: randomBytes(12).toString("hex"), ...PROCESS_FACTS };
     claimLocks = new Map();
     logger;
-    constructor(root, logger) {
-        this.logger = logger;
+    strictHydrate;
+    constructor(root, opts) {
+        this.logger = opts;
+        this.strictHydrate = opts?.strictHydrate === true;
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
         this.tmpDir = join(root, "tmp");
-        ensureDir(this.runsDir);
-        ensureDir(this.activeDir);
-        ensureDir(this.tmpDir);
+        try {
+            ensureDir(this.runsDir);
+            ensureDir(this.activeDir);
+            ensureDir(this.tmpDir);
+        }
+        catch (err) {
+            if (!this.strictHydrate)
+                throw err;
+            const detail = err instanceof Error ? err.message : String(err);
+            this.logger?.error?.("file_run_store_dirs_uninitializable", { runsDir: this.runsDir, error: detail, strictHydrate: true });
+            throw new RunStoreStrictHydrateError(`RUN_STORE_STRICT_HYDRATE=on and the file run-store could not initialize its directories under ${this.runsDir}: ${detail}. ` +
+                "Refusing to boot without a run ledger and a single-active claim index (both would be silently empty). " +
+                "Check that runs/ and runs/active/ are directories (not files) and writable, point LOCAL_DATA_ROOT at a usable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
+        }
         this.hydrate();
     }
     runDir(taskId) {
@@ -89,6 +105,36 @@ export class FileRunStore {
             updatedAt: r.updatedAt.toISOString(),
         };
     }
+    replay(path) {
+        try {
+            return readJsonlRecords(path);
+        }
+        catch (err) {
+            if (!this.strictHydrate)
+                throw err;
+            const detail = err instanceof Error ? err.message : String(err);
+            this.logger?.error?.("file_run_store_entry_unreadable", { path, error: detail, strictHydrate: true });
+            throw new RunStoreStrictHydrateError(`RUN_STORE_STRICT_HYDRATE=on and the file run-store could not read ${path}: ${detail}. ` +
+                "Refusing to boot with a PARTIAL run ledger (that row would silently vanish, which reads as 'no such run'). " +
+                "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
+        }
+    }
+    refuseIfUnreadable(jsonPath, dir) {
+        try {
+            statSync(jsonPath);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return;
+            const detail = err instanceof Error ? err.message : String(err);
+            this.logger?.error?.("file_run_store_entry_unreadable", { path: dir, error: detail, strictHydrate: true });
+            throw new RunStoreStrictHydrateError(`RUN_STORE_STRICT_HYDRATE=on and the file run-store could not determine whether ${jsonPath} exists: ${detail}. ` +
+                "Refusing to boot with a PARTIAL run ledger (that run would silently vanish, which reads as 'no such run'). " +
+                "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
+        }
+    }
     hydrate() {
         let entries;
         try {
@@ -99,8 +145,16 @@ export class FileRunStore {
             this.logger?.error?.("file_run_store_hydrate_unreadable", {
                 runsDir: this.runsDir,
                 error: detail,
-                note: "the file run-store booted with an EMPTY ledger because its runs/ directory could not be listed — every getRun will miss until this is fixed. This is NOT 'no such run'; check permissions/mount on the path above.",
+                strictHydrate: this.strictHydrate,
+                note: this.strictHydrate
+                    ? "RUN_STORE_STRICT_HYDRATE=on: the file run-store REFUSES to boot because its runs/ directory could not be listed. Check permissions/mount on the path above."
+                    : "the file run-store booted with an EMPTY ledger because its runs/ directory could not be listed — every getRun will miss until this is fixed. This is NOT 'no such run'; check permissions/mount on the path above.",
             });
+            if (this.strictHydrate) {
+                throw new RunStoreStrictHydrateError(`RUN_STORE_STRICT_HYDRATE=on and the file run-store could not list its runs directory ${this.runsDir}: ${detail}. ` +
+                    "Refusing to boot with an EMPTY run ledger (every getRun would miss, which reads as 'no such run'). " +
+                    "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior — the failure then only shows up as the file_run_store_hydrate_unreadable log line and the server.run-store.file-hydrate-unreadable counter).");
+            }
             recordFailOpen("server.run-store.file-hydrate-unreadable", detail);
             return;
         }
@@ -109,9 +163,12 @@ export class FileRunStore {
                 continue;
             const dir = join(this.runsDir, name);
             const jsonPath = join(dir, "run.json");
-            if (!existsSync(jsonPath))
+            if (!existsSync(jsonPath)) {
+                if (this.strictHydrate)
+                    this.refuseIfUnreadable(jsonPath, dir);
                 continue;
-            const rows = readJsonlRecords(jsonPath);
+            }
+            const rows = this.replay(jsonPath);
             const disk = rows[rows.length - 1];
             if (!disk || typeof disk.taskId !== "string")
                 continue;
@@ -120,7 +177,7 @@ export class FileRunStore {
                 continue;
             this.runs.set(disk.taskId, this.toRow(disk));
             const eventsPath = join(dir, "events.jsonl");
-            const recs = readJsonlRecords(eventsPath);
+            const recs = this.replay(eventsPath);
             if (recs.length) {
                 const list = [];
                 const seen = new Set();
@@ -137,7 +194,21 @@ export class FileRunStore {
         try {
             claims = readdirSync(this.activeDir);
         }
-        catch {
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.logger?.error?.("file_run_store_active_claims_unreadable", {
+                activeDir: this.activeDir,
+                error: detail,
+                strictHydrate: this.strictHydrate,
+                note: this.strictHydrate
+                    ? "RUN_STORE_STRICT_HYDRATE=on: the file run-store REFUSES to boot because its runs/active/ (single-active claim index) could not be listed."
+                    : "the file run-store booted with an EMPTY single-active claim index because runs/active/ could not be listed — getActiveTaskId will report 'no active run' for every session until this is fixed. Check permissions/mount on the path above.",
+            });
+            if (this.strictHydrate) {
+                throw new RunStoreStrictHydrateError(`RUN_STORE_STRICT_HYDRATE=on and the file run-store could not list its active-claim directory ${this.activeDir}: ${detail}. ` +
+                    "Refusing to boot with an EMPTY single-active claim index (every session would look unclaimed, so a delete or a fresh run could race a live/parked one). " +
+                    "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
+            }
             claims = [];
         }
         const nonTerminalBySanitizedSession = new Map();
@@ -153,7 +224,7 @@ export class FileRunStore {
         }
         for (const sanitized of claims) {
             const path = join(this.activeDir, sanitized);
-            const recs = readJsonlRecords(path);
+            const recs = this.replay(path);
             const claim = recs[recs.length - 1];
             if (claim && typeof claim.sessionId === "string" && typeof claim.taskId === "string" && isSafePathComponent(claim.taskId)) {
                 this.active.set(claim.sessionId, claim.taskId);
@@ -328,11 +399,12 @@ export class FileRunStore {
             this.persist(r);
         }
     }
-    async markResuming(taskId) {
+    async markResuming(taskId, instanceId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
             return false;
         r.status = "running";
+        r.instanceId = instanceId;
         r.cancelRequested = false;
         r.preemptRequested = false;
         r.updatedAt = new Date();

package/dist/plugins/fork-routing-session-store.d.ts

@@ -67,7 +67,7 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     forget(sessionId: string): void | Promise<void>;
     pin(sessionId: string): void | Promise<void>;
     unpin(sessionId: string): void | Promise<void>;
-    noteTaskRun(sessionId: string, taskId: string): void | Promise<void>;
+    noteTaskRun(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     list(): Promise<SessionStoreSummary[]>;
     /**
      * [1593] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后

package/dist/plugins/fork-routing-session-store.js

@@ -164,8 +164,8 @@ export class ForkRoutingSessionStore {
         }
         return this.pick(sessionId).unpin?.(sessionId);
     }
-    noteTaskRun(sessionId, taskId) {
-        return this.pick(sessionId).noteTaskRun?.(sessionId, taskId);
+    noteTaskRun(sessionId, taskId, runId) {
+        return this.pick(sessionId).noteTaskRun?.(sessionId, taskId, runId);
     }
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);

package/dist/plugins/leader-run-store-sql.d.ts

@@ -74,7 +74,7 @@ export declare class SqlLeaderRunStore {
     /** 按幂等键读回既有行(dup-key 观察臂;也给集成套件直查)。 */
     getByIdem(idemKey: string): Promise<LeaderRunRecord | undefined>;
     /**
-     * 陈旧 `running` 清算(codex 对抗复审 R1-high②,验真后修)。
+     * 陈旧 `running` 清算(codex 交叉复审 R1-high②,验真后修)。
      *
      * 病:准入(INSERT)与驱动(后台腿)是**两步**,而驱动腿只活在受理它的那个进程里。副本在这两步之间
      * 挂掉、或在一条 24h 的 run 中途挂掉,行就永远停在 `running`:跨副本读面永远显示「在跑」,而没有任何

package/dist/plugins/local-session-store.d.ts

@@ -172,7 +172,15 @@ export declare class LocalSessionStore implements SessionStore {
     }): Promise<SessionSummary[]>;
     /** K-5c (core 1.155 SessionStore seam): core's Runner calls this at runTask START with the run's taskId, so the
      *  latest run surfaces as `lastRunId` on listSessions even while it is still running/suspended (the local backend
-     *  has no runs ledger to derive it from, unlike the TiDB/PG twins). In-memory, last-write-wins per session. */
+     *  has no runs ledger to derive it from, unlike the TiDB/PG twins). In-memory, last-write-wins per session.
+     *  #499(core 5.65 增量批,**有意缓议**):core 的第三参 engine runId 在此**尚未消费**——它唯一的
+     *  合法出口是 listSessions 行上的 `lastTaskRunId`,而 `SessionSummary` 是 canonical spec 的**闭集**
+     *  (sema-sdk spec/openapi.yaml `additionalProperties:false`,producer-contract sessionsList 格咬着),
+     *  加键是跨仓 spec 节拍的事。spec 开键那一批再落:map 值扩成 `{taskId, runId?}` + 两座同动清座语义
+     *  (对齐 core TtlSessionStore.noteTaskRun 的 omit⇒clear,session-store.js 亲读)+ 行投影。
+     *  codex 5.65 增量批 R1-[medium] 曾建议「存储先行、投影另批」——**驳**:本店 runId 的唯一读点就是
+     *  行投影,先写不读=黑盒不可测的死状态(红先律无红可铺);清座语义单独存在也无观察面。存储与投影
+     *  必须同批,债主=sessions 列表 wire 键的 spec 节拍批(本注即债的定位锚)。 */
     noteTaskRun(sessionId: string, taskId: string): void;
     /** Synthesize a session's objective preview = the most-recent USER text message (the objective the run last saw).
      *  Reads the session's entries through the repo; any read error degrades to null (never fails the list). */

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

@@ -49,7 +49,7 @@
  * 3. **门自身失败 = 抛(拒启)**。吞掉 = 元表停留旧值 = 下次 boot 再清一次,把一次性代价变成每次 boot
  *    的代价;且「门在场但没跑成」静默 = fail-open。
  *
- * ## 两条已知残余(codex 对抗复审 R1-F1/R1-F3,均判为真;处置=成文,不落码面)
+ * ## 两条已知残余(codex 交叉复审 R1-F1/R1-F3,均判为真;处置=成文,不落码面)
  *
  * - **跨门回滚**(F1):指纹门**之前**的版本(7.14.x/7.15.x:有 embedder、无本门)照写 `embedding` 列却
  *   不认识元表 ⇒「装本版(元表=B)→ 回滚旧版跑一段(写 A 空间向量)→ 升回本版仍配 B」走完,元表与配置

package/dist/plugins/memory-optout-grant-store-sql.d.ts

@@ -0,0 +1,139 @@
+/**
+ * design/383 §3.1 / S-50 §一(S-49 S-2)—— per-principal **memory-capture opt-out 授权表**
+ * `memory_optout_grant`:`RuntimeCaps.allowMemoryOptOut` 的本地 verdict 源 + operator 管理面的持久层。
+ * SINGLE-FILE DUAL-DIALECT(design/158 A12 形,照 approval-ask-store-sql.ts:一个 `SqlMemoryOptOutGrantStore`
+ * 接 `SqlDriver`,两个薄 ctor 子类落方言绑定)。
+ *
+ * ── 数据形(S-50 §1.1 的施工形;**稿偏离如实记**)────────────────────────────────────────────────
+ * S-50 稿写的是 `PRIMARY KEY (org_id, principal)` + `principal=''` 为 org 级缺省哨兵行。亲读本仓
+ * (侦察 2026-08-30):server **没有 org 身份维** —— 租户维 = 单 `principal`(`gatedPrincipal` 供给),
+ * `org` 只是记忆 scope 目录里的一个词(`org-memory-admission.ts`:授权目录三态,不是 principal 的属性),
+ * 任何 SQL 表都没有 `org_id` 列。给表铸一根没人能填的 `org_id` 就是编数据(「不编」律)。所以:
+ *   · **一台 worker = 一个租户面**,稿中「org 级缺省行」落成**部署级缺省行**(同一哨兵 `principal=''`);
+ *   · 折叠仍是三层:per-principal 行 → 部署缺省行 → 代码缺省 `allow`(governed 姿态「verdict 必答」由此
+ *     结构性满足,新增用户零建行义务 —— 稿 §1.1 F6 折叠律原样保住);
+ *   · 将来 server 长出 principal→org 身份面时,升 (org_id, principal) 复合键是一次 additive 迁移
+ *     (缺省行按 org 复制),不是重设计。
+ *
+ * ── 列 ──────────────────────────────────────────────────────────────────────────────────────────
+ *   principal      VARCHAR(190) PK   '' = 部署缺省哨兵行;宽度与全仓 principal 列同(approval_ask.owner)
+ *   allow          TINYINT(1)/BOOLEAN NOT NULL
+ *   updated_at_ms  BIGINT NOT NULL   审计:何时
+ *   updated_by     VARCHAR(190)      审计:谁改的(operator principal,恒在场 —— 四端点都过 operator 门)
+ *   note           VARCHAR(500) NULL 审计:为何(可缺席,不编)
+ * 审计**行内**,不另建审计表(S-50 §1.3 v1 体量裁定;变更史需求真出现再升 retention 面同族表)。
+ *
+ * ── 方言差异(显式写在调用点,A12 doctrine)──────────────────────────────────────────────────────
+ *   · `?` vs `$n` 占位符;
+ *   · upsert:TiDB `INSERT … ON DUPLICATE KEY UPDATE` vs PG `INSERT … ON CONFLICT (principal) DO UPDATE`;
+ *   · boolean:TiDB `TINYINT(1)` 读回来是 0/1 **number**,PG `BOOLEAN` 读回来是 boolean —— `readAllow`
+ *     两形都认、其余一律 throw(一列存 verdict 的表不许 truthiness 读:`"0"`/`"false"` 串读成 true 正是
+ *     本键最怕的方向)。
+ *
+ * ── 缓存姿态 ────────────────────────────────────────────────────────────────────────────────────
+ * **零缓存直读**(S-50 §1.4 撤销窗:server 只保证 resolver 下一次读到新 verdict)。core 每任务 prepare 调
+ * 一次 resolver;本表两行以内的 PK 点查在任何 SQL 后端都是亚毫秒级,加缓存 = 为不存在的负载引入一致性窗
+ * (若未来实测成压力源,升级形 = TTL ≤ 60s 且写穿,稿已裁)。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import type { PgQueryFn } from "./pg-query.js";
+import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
+import type { MemoryOptOutVerdictSource } from "../runtime-caps-resolver.js";
+export declare const MEMORY_OPTOUT_GRANT_TABLE = "memory_optout_grant";
+/** 部署缺省哨兵行的 principal 值(S-50 §1.1;'' 是**真值**不是缺席 —— NOT NULL PK)。 */
+export declare const MEMORY_OPTOUT_DEFAULT_PRINCIPAL = "";
+/** 一行的读投影(wire 形逐字:S-50 §1.3 的 `{principal, allow, updatedAtMs, updatedBy, note?}`)。 */
+export interface MemoryOptOutGrantRow {
+    principal: string;
+    allow: boolean;
+    updatedAtMs: number;
+    updatedBy: string;
+    /** 只在真有 note 时在场(不铸 `null` 键:缺席=没写理由,不编)。 */
+    note?: string;
+}
+/** 折叠输入 = 表里与本 principal 相关的行(至多两行:缺省行 + 本 principal 行)。 */
+export interface MemoryOptOutGrantFoldRow {
+    principal: string;
+    allow: boolean;
+}
+export type MemoryOptOutVerdictSourceKind = "principal" | "deployment-default" | "code-default";
+/**
+ * S-50 §1.1 **F6 折叠律**(纯函数,`build*`:产纯数据):per-principal 行 → 部署缺省哨兵行 → 代码缺省 allow。
+ * 三层折叠后**恒能给显式 verdict**。`principal` 缺席(匿名/系统 run)只看缺省行 —— 别人的覆盖行绝不算到
+ * 匿名头上。rows 里不相干的 principal 行被忽略(SQL 层已按 `IN (?, '')` 收窄,这里再判一次是让纯函数对
+ * 任意输入都正确,不依赖调用方的查询形)。
+ */
+export declare function buildMemoryOptOutVerdict(rows: readonly MemoryOptOutGrantFoldRow[], principal: string | undefined): {
+    allow: boolean;
+    source: MemoryOptOutVerdictSourceKind;
+};
+/** 管理面(S-50 §1.3 四端点)+ resolver 面(S-1)共用的店接口。 */
+export interface MemoryOptOutGrantStore extends MemoryOptOutVerdictSource {
+    /** 全表读投影:缺省行(缺席 ⇒ null,不编)+ 全部覆盖行(按 principal 升序,稳定)。 */
+    list(): Promise<{
+        deploymentDefault: MemoryOptOutGrantRow | null;
+        overrides: MemoryOptOutGrantRow[];
+    }>;
+    /** 部署缺省行 upsert。 */
+    putDefault(input: {
+        allow: boolean;
+        updatedBy: string;
+        note?: string;
+    }): Promise<MemoryOptOutGrantRow>;
+    /** per-principal 覆盖行 upsert(`principal` 非空:空串是哨兵,走 putDefault —— 调用方先验型,店内再拒一次)。 */
+    putOverride(principal: string, input: {
+        allow: boolean;
+        updatedBy: string;
+        note?: string;
+    }): Promise<MemoryOptOutGrantRow>;
+    /** 撤覆盖(回落部署缺省)。true = 真删了一行;false = 本来就没有(幂等,诚实)。哨兵串恒拒。 */
+    deleteOverride(principal: string): Promise<boolean>;
+}
+/**
+ * principal 的**字节形状法**(店与路由共用一只谓词;返回问题句,`undefined` = 合形)。
+ *
+ * 🔴 codex R1-[high](第二份,验真后修):TiDB/MySQL 的 `utf8mb4_bin` 是 **PAD SPACE** 语义 —— `'alice'` 与
+ * `'alice '`(尾空格)在 PK 比较上**相等**,PG 的 `COLLATE "C"` 则字节精确。一个带尾空格的 principal 在 TiDB 上会
+ * 撞进别人的行(PUT 改了别人的 verdict、DELETE 删了别人的覆盖),在 PG 上则是另一条行 —— 双方言分叉,而且方向是
+ * 授权面上的串台。不改 collation(TiDB 对 NO PAD 排序规则的支持随版本走,且存量表要迁移);改在**边界**:任何
+ * 首尾空白 / 控制字符的 principal 一律拒(合法身份从不长这样 —— `verifiedPrincipal` 铸的 principal 是 header/JWT
+ * sub 的裁剪值),于是 PAD SPACE 永远碰不到两条只差空白的键。同时拒内部哨兵(`RESERVED_PRINCIPALS`,security.ts
+ * 的单一登记表)与超列宽。
+ */
+export declare function memoryOptOutPrincipalShapeProblem(principal: string): string | undefined;
+/** 入口断言(店内第二道墙;路由已用同一只谓词答 400):哨兵串不许经覆盖面进出;形状法见上。 */
+export declare function assertOverridePrincipal(principal: string): void;
+/** 双方言 MemoryOptOutGrantStore。见文件头的姿态 + 方言差异账。 */
+export declare class SqlMemoryOptOutGrantStore implements MemoryOptOutGrantStore {
+    private readonly driver;
+    private readonly dialect;
+    private readonly now;
+    constructor(driver: SqlDriver, dialect: SqlDialect, now?: () => number);
+    resolveAllow(principal: string | undefined): Promise<boolean>;
+    list(): Promise<{
+        deploymentDefault: MemoryOptOutGrantRow | null;
+        overrides: MemoryOptOutGrantRow[];
+    }>;
+    putDefault(input: {
+        allow: boolean;
+        updatedBy: string;
+        note?: string;
+    }): Promise<MemoryOptOutGrantRow>;
+    putOverride(principal: string, input: {
+        allow: boolean;
+        updatedBy: string;
+        note?: string;
+    }): Promise<MemoryOptOutGrantRow>;
+    deleteOverride(principal: string): Promise<boolean>;
+    private upsert;
+}
+export declare class TiDBMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
+    constructor(pool: MySqlPool, now?: () => number);
+}
+export declare class PgMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
+    constructor(pool: PgPool, now?: () => number);
+}
+export declare const TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS: readonly string[];
+export declare function ensurePgMemoryOptOutGrantSchema(q: PgQueryFn): Promise<void>;
+//# sourceMappingURL=memory-optout-grant-store-sql.d.ts.map

package/dist/plugins/memory-optout-grant-store-sql.js

@@ -0,0 +1,157 @@
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { RESERVED_PRINCIPALS, RESERVED_PRINCIPAL_PREFIXES } from "../security.js";
+export const MEMORY_OPTOUT_GRANT_TABLE = "memory_optout_grant";
+export const MEMORY_OPTOUT_DEFAULT_PRINCIPAL = "";
+export function buildMemoryOptOutVerdict(rows, principal) {
+    if (principal !== undefined && principal !== MEMORY_OPTOUT_DEFAULT_PRINCIPAL) {
+        const own = rows.find((r) => r.principal === principal);
+        if (own !== undefined)
+            return { allow: own.allow, source: "principal" };
+    }
+    const dflt = rows.find((r) => r.principal === MEMORY_OPTOUT_DEFAULT_PRINCIPAL);
+    if (dflt !== undefined)
+        return { allow: dflt.allow, source: "deployment-default" };
+    return { allow: true, source: "code-default" };
+}
+export function memoryOptOutPrincipalShapeProblem(principal) {
+    if (principal.length === 0)
+        return "principal is empty (the empty string is the deployment-default sentinel row, not an addressable principal)";
+    if (principal.length > 190)
+        return "principal exceeds the 190-char column width";
+    if (/^\s|\s$/u.test(principal))
+        return "principal has leading/trailing whitespace (rejected at the boundary: MySQL-protocol PAD SPACE collation would fold it onto another principal's row)";
+    if (/[\u0000-\u001f\u007f]/u.test(principal))
+        return "principal contains control characters";
+    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
+        return "principal is a reserved internal scope sentinel";
+    return undefined;
+}
+export function assertOverridePrincipal(principal) {
+    if (principal === MEMORY_OPTOUT_DEFAULT_PRINCIPAL)
+        throw new Error("memory opt-out grant: the empty principal is the deployment-default sentinel row — use the default face, not the override face");
+    const problem = memoryOptOutPrincipalShapeProblem(principal);
+    if (problem !== undefined)
+        throw new Error(`memory opt-out grant: ${problem}`);
+}
+function ph(dialect, n) {
+    return dialect === "pg" ? `$${n}` : "?";
+}
+function readAllow(v) {
+    if (typeof v === "boolean")
+        return v;
+    if (v === 1 || v === 0)
+        return v === 1;
+    throw new Error(`memory_optout_grant.allow read back as ${typeof v} (${String(v)}) — refusing to truthiness-read a verdict column`);
+}
+function readNum(v, col) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string" && /^\d+$/.test(v))
+        return Number(v);
+    if (typeof v === "bigint")
+        return Number(v);
+    throw new Error(`memory_optout_grant.${col} read back as ${typeof v} — not a number`);
+}
+function toRow(r) {
+    const note = r.note;
+    return {
+        principal: String(r.principal),
+        allow: readAllow(r.allow),
+        updatedAtMs: readNum(r.updated_at_ms, "updated_at_ms"),
+        updatedBy: String(r.updated_by),
+        ...(typeof note === "string" && note.length > 0 ? { note } : {}),
+    };
+}
+export class SqlMemoryOptOutGrantStore {
+    driver;
+    dialect;
+    now;
+    constructor(driver, dialect, now = () => Date.now()) {
+        this.driver = driver;
+        this.dialect = dialect;
+        this.now = now;
+    }
+    async resolveAllow(principal) {
+        const d = this.dialect;
+        if (principal !== undefined && principal !== MEMORY_OPTOUT_DEFAULT_PRINCIPAL) {
+            const problem = memoryOptOutPrincipalShapeProblem(principal);
+            if (problem !== undefined)
+                throw new Error(`memory opt-out grant: cannot resolve a verdict for a malformed principal — ${problem}`);
+        }
+        const res = principal !== undefined && principal !== MEMORY_OPTOUT_DEFAULT_PRINCIPAL
+            ? await this.driver.query(`SELECT principal, allow FROM ${MEMORY_OPTOUT_GRANT_TABLE} WHERE principal IN (${ph(d, 1)}, ${ph(d, 2)})`, [principal, MEMORY_OPTOUT_DEFAULT_PRINCIPAL])
+            : await this.driver.query(`SELECT principal, allow FROM ${MEMORY_OPTOUT_GRANT_TABLE} WHERE principal = ${ph(d, 1)}`, [MEMORY_OPTOUT_DEFAULT_PRINCIPAL]);
+        const rows = res.rows.map((r) => ({ principal: String(r.principal), allow: readAllow(r.allow) }));
+        return buildMemoryOptOutVerdict(rows, principal).allow;
+    }
+    async list() {
+        const res = await this.driver.query(`SELECT principal, allow, updated_at_ms, updated_by, note FROM ${MEMORY_OPTOUT_GRANT_TABLE} ORDER BY principal ASC`);
+        let deploymentDefault = null;
+        const overrides = [];
+        for (const r of res.rows) {
+            const row = toRow(r);
+            if (row.principal === MEMORY_OPTOUT_DEFAULT_PRINCIPAL)
+                deploymentDefault = row;
+            else
+                overrides.push(row);
+        }
+        return { deploymentDefault, overrides };
+    }
+    putDefault(input) {
+        return this.upsert(MEMORY_OPTOUT_DEFAULT_PRINCIPAL, input);
+    }
+    async putOverride(principal, input) {
+        assertOverridePrincipal(principal);
+        return this.upsert(principal, input);
+    }
+    async deleteOverride(principal) {
+        assertOverridePrincipal(principal);
+        const res = await this.driver.query(`DELETE FROM ${MEMORY_OPTOUT_GRANT_TABLE} WHERE principal = ${ph(this.dialect, 1)}`, [principal]);
+        return res.affected === 1;
+    }
+    async upsert(principal, input) {
+        const at = this.now();
+        const note = input.note !== undefined && input.note.length > 0 ? input.note : null;
+        const allowParam = this.dialect === "pg" ? input.allow : input.allow ? 1 : 0;
+        if (this.dialect === "pg") {
+            await this.driver.query(`INSERT INTO ${MEMORY_OPTOUT_GRANT_TABLE} (principal, allow, updated_at_ms, updated_by, note) VALUES ($1, $2, $3, $4, $5)
+         ON CONFLICT (principal) DO UPDATE SET allow = EXCLUDED.allow, updated_at_ms = EXCLUDED.updated_at_ms, updated_by = EXCLUDED.updated_by, note = EXCLUDED.note`, [principal, allowParam, at, input.updatedBy, note]);
+        }
+        else {
+            await this.driver.query(`INSERT INTO ${MEMORY_OPTOUT_GRANT_TABLE} (principal, allow, updated_at_ms, updated_by, note) VALUES (?, ?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE allow = VALUES(allow), updated_at_ms = VALUES(updated_at_ms), updated_by = VALUES(updated_by), note = VALUES(note)`, [principal, allowParam, at, input.updatedBy, note]);
+        }
+        return { principal, allow: input.allow, updatedAtMs: at, updatedBy: input.updatedBy, ...(note !== null ? { note } : {}) };
+    }
+}
+export class TiDBMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
+    constructor(pool, now) {
+        super(mysqlDriver(pool), "tidb", now);
+    }
+}
+export class PgMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
+    constructor(pool, now) {
+        super(pgDriver(pool), "pg", now);
+    }
+}
+export const TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${MEMORY_OPTOUT_GRANT_TABLE} (
+    principal VARCHAR(190) NOT NULL,
+    allow TINYINT(1) NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    updated_by VARCHAR(190) NOT NULL,
+    note VARCHAR(500) NULL,
+    PRIMARY KEY (principal)
+  ) COLLATE utf8mb4_bin`,
+];
+export async function ensurePgMemoryOptOutGrantSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${MEMORY_OPTOUT_GRANT_TABLE} (
+    principal VARCHAR(190) COLLATE "C" NOT NULL,
+    allow BOOLEAN NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    updated_by VARCHAR(190) COLLATE "C" NOT NULL,
+    note VARCHAR(500) COLLATE "C",
+    PRIMARY KEY (principal)
+  )`);
+}
+//# sourceMappingURL=memory-optout-grant-store-sql.js.map

package/dist/plugins/memory-origin-law.d.ts

@@ -29,7 +29,7 @@
  *
  * ① **判据本身**({@link originWhitewashRefusal}):`committedOriginOf` / `originEquals` 都用 core 的
  *    导出实现,**不重写** —— 它们要处理 `frontmatter.origin` 与「保留在 `extra` 里的 origin 形字节块」
- *    两种承载形(legacy / 外来),自己写一份近似的等于给洗白留一条后门。
+ *    两种承载形(legacy / 外来),自己写一份近似的等于给洗白留一条旁路。
  * ② **批次基线**({@link rememberBatchOrigin}):两支 SQL 后端逐条 patch 直打真库(没有 File backend
  *    那种「先规划整批再落盘」的阶段),所以同批 `delete` 之后再 `add` 时,库里已经没有那一行了 ——
  *    只看当下的库会把它误判成合法新生命。基线 map 按**本批第一次触碰**记下该 id 的已提交 origin,
@@ -58,7 +58,7 @@ import { type MemoryEntryFrontmatter, type MemoryEntryHeader } from "@sema-agent
  * ## 判据禁手抄
  *
  * 谓词一律用 core 导出的 {@link ambiguousOriginRepresentation}:它要解 `extra` 里的 origin 形块
- * (跨块字段组合、解析期块重排都算歧义),自己写一份近似的等于给洗白开后门 —— 这条在 #307 就写死过。
+ * (跨块字段组合、解析期块重排都算歧义),自己写一份近似的等于给洗白开口子 —— 这条在 #307 就写死过。
  * core 5.47.0 起该谓词进公开导出面([4698] 请托兑现),本仓的「撤除条件钉」也因此在 5.47 提货当天
  * 准时翻红,本批就是那条钉指定的兑现动作。
  *