@sema-agent/server 7.37.0 → 7.38.0-rc.1

package/dist/plugins/memory-engine-pg.js

@@ -25,7 +25,7 @@ import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js"; // R5 批γ + #271 件1:scope/slug 写前宽守卫
 // #307 件6(core 5.46.0 design/336 §2.3-2):external-origin 不可变律 —— 两支 SQL 孪生共用**一份**判据。
-import { createBatchOriginBaseline, originWhitewashRefusal, rememberBatchOrigin, unknownPatchOpRefusal } from "./memory-origin-law.js";
+import { ambiguousOriginRefusal, createBatchOriginBaseline, exposureBandOf, exposureCarriage, originMarkedSqlPredicate, originWhitewashRefusal, rememberBatchOrigin, unknownPatchOpRefusal, } from "./memory-origin-law.js";
 /** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
  *  the retired MemoryStore plane and this entry plane must never cross-write. */
 export const PG_MEMORY_ENGINE_TABLES = {
@@ -133,6 +133,9 @@ export class PgMemoryEngineBackend {
             mtimeMs: Number(r.mtime_ms),
             rev: r.rev,
             sizeBytes: Number(r.size_bytes),
+            // #319(design/336 §5.2):committed external-origin 事实随**每一个**头面(listHeaders + search)。
+            // 归一化只有一份(memory-origin-law.exposureCarriage → core 的 committedOriginOf),两支方言同源。
+            ...exposureCarriage(fm),
         };
     }
     entryFromRow(r) {
@@ -163,6 +166,11 @@ export class PgMemoryEngineBackend {
         return res.rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
     }
     async search(query, scopes, opts) {
+        // #319(design/336 §5.2):两带序 —— 未标记先、已标记后,**带序在截断之前**(理由见
+        // memory-origin-law.exposureBandOf 的顶注)。缺席/false ⇒ 单带序,与本方法 pre-336 形逐字节同。
+        const bands = opts?.exposureBands === true;
+        /** 契约序:(带号 ‖ 缺席时恒 0) → score 升 → id。三档共用一只比较器,谁都别自己写一份。 */
+        const contractOrder = (a, b) => (bands ? exposureBandOf(a) - exposureBandOf(b) : 0) || a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
         // Normalize the limit ONCE for all three rungs — `Math.floor`
         // makes a fractional limit (0.5) behave like File's `slice` (→ 0 → empty), `!(lim > 0)` also
         // rejects NaN (NaN > 0 is false — it previously reached the native rung's interpolated LIMIT as
@@ -182,12 +190,23 @@ export class PgMemoryEngineBackend {
             const qv = await this.embedder.embed(query);
             if (Array.isArray(qv) && qv.length === this.embedder.dimensions) {
                 const vecParam = scopes.length + 1;
+                // #319:本档的排序**和截断都在 SQL 里**,所以两带序也必须进 ORDER BY —— 在进程里对一页
+                // 已截断的结果重排是排不出来的(那正是契约要拒的「干净条目被饿死」)。带号谓词=不可变律
+                // 模块里那条 `committedOriginOf` 的下推形(逐元素跑 core 的行首正则,与 JS 判据机器对表;
+                // 为什么不能图省事写成 LIKE,见 originMarkedSqlPredicate 的顶注)。
+                const bandExpr = bands ? `(CASE WHEN ${originMarkedSqlPredicate("frontmatter")} THEN 1 ELSE 0 END) ASC, ` : "";
                 const res = await this.query(`SELECT id, scope, slug, frontmatter, rev, mtime_ms, size_bytes, embedding <=> $${vecParam}::vector AS dist
              FROM ${PG_MEMORY_ENGINE_TABLES.entry}
             WHERE scope IN (${inPlaceholders(1, scopes.length)}) AND embedding IS NOT NULL
-            ORDER BY embedding <=> $${vecParam}::vector ASC
+            ORDER BY ${bandExpr}embedding <=> $${vecParam}::vector ASC, id ASC
             LIMIT ${Math.min(limit, 100_000)}`, [...scopes, vectorLiteral(qv)]);
-                return res.rows.map((r) => ({ ...this.headerFromRow(r), score: Number(r.dist) }));
+                // ⚠️ `id ASC` 必须写在 SQL 的 ORDER BY 里、也就是 LIMIT **之前**(codex 对抗复审 R1-[medium]):
+                // 同分(同一条向量距离)超过 limit 条时,决定「谁被截掉」的是这一句;缺了它,留下哪几条由执行
+                // 计划随机决定,页内怎么重排都换不回被截掉的那条。列是 `text COLLATE "C"` ⇒ 字节序,与下面
+                // 进程内比较器的定序同向。
+                const hits = res.rows.map((r) => ({ ...this.headerFromRow(r), score: Number(r.dist) }));
+                // 页内再排一次:契约序的最终裁决在进程侧(单带时是恒等重排)。
+                return hits.sort(contractOrder);
             }
             // Wrong-dimension query vector (transient embedder fault) — fall open to the in-process path.
         }
@@ -214,7 +233,8 @@ export class PgMemoryEngineBackend {
         }
         // opus 审 C4: deterministic id tie-break — tied scores must not order by row-arrival accident
         // (the cross-backend equivalence assertion compares ordered projections; File mirrors this).
-        scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        // #319:整档在进程内排完**再**切片 ⇒ 两带序天然落在截断之前(SQL 侧无 LIMIT 可绕过)。
+        scored.sort(contractOrder);
         return scored.slice(0, limit);
     }
     async applyPatches(patches) {
@@ -293,6 +313,16 @@ export class PgMemoryEngineBackend {
                 return;
             }
         }
+        // #319 增量([4768] 勘误 + core `1a5ebaa1`):**歧义 origin 表示**零写拒。判位与 File 的 planOne
+        // 逐字同 —— 表示合法性先于状态比较:排在键形守卫之后、add/update 两支的 guard/跨 scope/白洗/CAS
+        // 之前,且在任何 I/O 之前。判据用 core 导出的谓词(禁手抄),文案照抄 File(跨后端同一输入同一答复)。
+        if (patch.op !== "delete" && patch.entry !== undefined) {
+            const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
+            if (refusal !== undefined) {
+                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
+                return;
+            }
+        }
         if (patch.op === "add") {
             const rawEntry = patch.entry;
             if (!rawEntry) {

package/dist/plugins/memory-engine-tidb.d.ts

@@ -51,6 +51,7 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
+        exposureBands?: boolean;
     }): Promise<ScoredMemoryEntry[]>;
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private applyOne;

package/dist/plugins/memory-engine-tidb.js

@@ -26,7 +26,7 @@ import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js"; // R5 批γ + #271 件1:scope/slug 写前宽守卫
 // #307 件6(core 5.46.0 design/336 §2.3-2):external-origin 不可变律 —— 与 Pg 孪生共用**一份**判据。
-import { createBatchOriginBaseline, originWhitewashRefusal, rememberBatchOrigin, unknownPatchOpRefusal } from "./memory-origin-law.js";
+import { ambiguousOriginRefusal, createBatchOriginBaseline, exposureBandOf, exposureCarriage, originWhitewashRefusal, rememberBatchOrigin, unknownPatchOpRefusal, } from "./memory-origin-law.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 /** Table names (single source) — SAME names as PG_MEMORY_ENGINE_TABLES (the two dialects never share
  *  one database), deliberately DISJOINT from the legacy `agent_memory*` MemoryStore plane. */
@@ -117,6 +117,8 @@ export class TiDBMemoryEngineBackend {
             mtimeMs: Number(r.mtime_ms),
             rev: r.rev,
             sizeBytes: Number(r.size_bytes),
+            // #319(design/336 §5.2,Pg 孪生同注):committed external-origin 事实随每一个头面;归一化同源。
+            ...exposureCarriage(fm),
         };
     }
     entryFromRow(r) {
@@ -146,6 +148,9 @@ export class TiDBMemoryEngineBackend {
         return rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
     }
     async search(query, scopes, opts) {
+        // #319(design/336 §5.2,Pg 孪生同注):两带序 —— 未标记先,**带序在截断之前**。本方言只有词面档,
+        // 整档在进程内排完再切片,所以「带序先于截断」天然成立(无 SQL LIMIT 可绕过)。
+        const bands = opts?.exposureBands === true;
         // Limit normalization mirrors the Pg twin verbatim (floor semantics; NaN rejected; Infinity = no cap).
         const rawLimit = opts?.limit ?? 20;
         const limit = Number.isFinite(rawLimit) ? Math.floor(rawLimit) : rawLimit;
@@ -168,7 +173,7 @@ export class TiDBMemoryEngineBackend {
         }
         // Deterministic id tie-break (opus 审 C4,Pg 版同注): tied scores must not order by row-arrival
         // accident — the cross-backend equivalence assertion compares ordered projections.
-        scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        scored.sort((a, b) => (bands ? exposureBandOf(a) - exposureBandOf(b) : 0) || a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         return scored.slice(0, limit);
     }
     async applyPatches(patches) {
@@ -242,6 +247,16 @@ export class TiDBMemoryEngineBackend {
                 return;
             }
         }
+        // #319 增量([4768] 勘误 + core `1a5ebaa1`,Pg 孪生同注):**歧义 origin 表示**零写拒。判位与
+        // File 的 planOne 逐字同(表示合法性先于状态比较,且在任何 I/O 之前);判据用 core 导出的谓词
+        // (禁手抄——解 extra 里的 origin 形块那只解析器一旦解得比 core 宽松,就是给洗白开后门)。
+        if (patch.op !== "delete" && patch.entry !== undefined) {
+            const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
+            if (refusal !== undefined) {
+                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
+                return;
+            }
+        }
         if (patch.op === "add") {
             const entry = patch.entry;
             if (!entry) {

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

@@ -37,6 +37,75 @@
  *    (core 契约逐字要求的那条)才成立。
  */
 import { type MemoryEntryFrontmatter, type MemoryEntryOrigin } from "@sema-agent/core";
+/**
+ * #319 增量(sema-comms [4768] 勘误 + core 仓 `1a5ebaa1`,conformance 30→31)—— **歧义 origin 表示**
+ * 的拒绝门,与不可变律同批、同一个写路径上。
+ *
+ * ## 病
+ *
+ * 同一条目**同时**携带 typed `frontmatter.origin` 与一个**冲突的** origin 形 `extra` 块(或多个彼此
+ * 冲突的 extra 块)时:不可变律的比较器走 `committedOriginOf`,而它在 typed 在场时优先读 typed ——
+ * 于是那枚 typed 满足「标记原样带下去」,冲突的块却照样进了存储。任何一次**重解析**(File 的投影
+ * 往返 / sync 对拍 / bundle 校验)都可能答出**另一枚**标记 ⇒ 成员改写的载具。不可变律本身没漏,
+ * 漏的是「根本不该收下这种表示」这一步。
+ *
+ * ## 钥匙在 DISAGREEMENT,不在载体数
+ *
+ * 载体彼此**一致**的多载形(typed 旁边一个逐成员相等的 extra 形)是合法的 legacy 承载,必须照收 ——
+ * 那正是序列化闭合(同一条记录在 File 投影里往返一圈就长这样)。「见到 extra 就拒」会把正常的
+ * legacy 条目全部打死。
+ *
+ * ## 判据禁手抄
+ *
+ * 谓词一律用 core 导出的 {@link ambiguousOriginRepresentation}:它要解 `extra` 里的 origin 形块
+ * (跨块字段组合、解析期块重排都算歧义),自己写一份近似的等于给洗白开后门 —— 这条在 #307 就写死过。
+ * core 5.47.0 起该谓词进公开导出面([4698] 请托兑现),本仓的「撤除条件钉」也因此在 5.47 提货当天
+ * 准时翻红,本批就是那条钉指定的兑现动作。
+ *
+ * ## 文案与 File 逐字同
+ *
+ * 拒绝文案照抄 core `file-backend.ts` 的 `planOne`(亲读 `1a5ebaa1` 前后两版确认未变),因为
+ * 契约按 `/representation conflict|malformed patch refused/` 匹配,而**跨后端同一输入必须同一答复**
+ * —— 消费方按 reason 分类处置,两支方言各写各的文案就等于让同一件事在不同部署上分叉。
+ *
+ * ## 判位
+ *
+ * 与 File 同precedence:**表示合法性先于状态比较** —— 排在 id/键形守卫之后、add/update 分支
+ * (guard 算术、跨 scope 拒、白洗判据、rev CAS)之前,且在**任何 I/O 之前**(零写拒)。
+ */
+export declare function ambiguousOriginRefusal(fm: MemoryEntryFrontmatter): string | undefined;
+/**
+ * #319(core 5.47/5.48 契约冻结面,design/336 §5.2)—— **头面 exposure 事实**的同一份归一化。
+ *
+ * 契约逐字:`listHeaders` 与 `search` 两个头面都要携带 `exposure`,且**同一条归一化**
+ * (`committedOriginOf`:typed `frontmatter.origin` 与 legacy 的 `extra` origin 形字节块两种承载,
+ * 一次判、两面同答)。这是**数据事实**不是模式:后端恒报库里存着什么,读侧怎么处置(不透明句柄/
+ * 横幅/两带序)归引擎层的 provenance 模式。缺席 ⇔ 没标记(不等于「证明干净」)。
+ *
+ * 为什么与不可变律同住一个模块:两者读的是**同一个** committed origin。判据(白洗拒)与事实
+ * (exposure 携带)分家写,迟早在某一支方言上一边认得 extra 形、另一边只认 typed 形 —— 那时
+ * 「洗不掉的标记」在检索面**看不见**,而两支后端谁都不会报错。
+ */
+export declare function exposureCarriage(fm: MemoryEntryFrontmatter): {
+    exposure?: "external";
+};
+/**
+ * 两带序的带号:未标记 = 0(**先**),已标记 = 1。
+ *
+ * 契约的载荷理由(core r1-9,逐字转述):两带序必须落在**截断之前** —— 一页 limit 全是带标条目时,
+ * 排在 limit+1 位的干净条目会被饿死,而工具层**无法**从一页已截断的结果里把它捞回来。
+ * `exposureBands` 缺席/false ⇒ 单带序,与 pre-336 逐字节同(`provenance:"off"` 的读面)。
+ */
+export declare function exposureBandOf(header: {
+    exposure?: "external";
+}): 0 | 1;
+/** core `/^\s*origin\s*:/`(`extraOriginCarriers` 的开块判据)的 SQL 孪生。 */
+export declare const ORIGIN_CARRIER_LINE_SQL_REGEX = "^[\\u0009\\u000a\\u000b\\u000c\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*origin[\\u0009\\u000a\\u000b\\u000c\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*:";
+/**
+ * 「这一行带 committed origin 标记」的 SQL 布尔式(两种承载形同判,与 {@link exposureCarriage} 同源)。
+ * `column` = 该表 frontmatter 列的表达式(调用方自己保证它是列名/限定名,**不接受外来串**)。
+ */
+export declare function originMarkedSqlPredicate(column: string): string;
 /** 本批次的「已提交 origin」基线:id → 本批**第一次**触碰它时库里那一份(无行 ⇒ `undefined`)。 */
 export type BatchOriginBaseline = Map<string, MemoryEntryOrigin | undefined>;
 /** 新建一只批次基线(每次 `applyPatches` 一只;跨批次**不得**复用 —— 已提交的墓碑正是靠「换批清零」放行)。 */

package/dist/plugins/memory-origin-law.js

@@ -36,7 +36,124 @@
  *    之后同批的任何 op 都按那一份判。⇒「同批 delete+re-add 拒 / 已提交墓碑后 add 放」这条分界
  *    (core 契约逐字要求的那条)才成立。
  */
-import { committedOriginOf, originEquals } from "@sema-agent/core";
+import { ambiguousOriginRepresentation, committedOriginOf, originEquals } from "@sema-agent/core";
+/**
+ * #319 增量(sema-comms [4768] 勘误 + core 仓 `1a5ebaa1`,conformance 30→31)—— **歧义 origin 表示**
+ * 的拒绝门,与不可变律同批、同一个写路径上。
+ *
+ * ## 病
+ *
+ * 同一条目**同时**携带 typed `frontmatter.origin` 与一个**冲突的** origin 形 `extra` 块(或多个彼此
+ * 冲突的 extra 块)时:不可变律的比较器走 `committedOriginOf`,而它在 typed 在场时优先读 typed ——
+ * 于是那枚 typed 满足「标记原样带下去」,冲突的块却照样进了存储。任何一次**重解析**(File 的投影
+ * 往返 / sync 对拍 / bundle 校验)都可能答出**另一枚**标记 ⇒ 成员改写的载具。不可变律本身没漏,
+ * 漏的是「根本不该收下这种表示」这一步。
+ *
+ * ## 钥匙在 DISAGREEMENT,不在载体数
+ *
+ * 载体彼此**一致**的多载形(typed 旁边一个逐成员相等的 extra 形)是合法的 legacy 承载,必须照收 ——
+ * 那正是序列化闭合(同一条记录在 File 投影里往返一圈就长这样)。「见到 extra 就拒」会把正常的
+ * legacy 条目全部打死。
+ *
+ * ## 判据禁手抄
+ *
+ * 谓词一律用 core 导出的 {@link ambiguousOriginRepresentation}:它要解 `extra` 里的 origin 形块
+ * (跨块字段组合、解析期块重排都算歧义),自己写一份近似的等于给洗白开后门 —— 这条在 #307 就写死过。
+ * core 5.47.0 起该谓词进公开导出面([4698] 请托兑现),本仓的「撤除条件钉」也因此在 5.47 提货当天
+ * 准时翻红,本批就是那条钉指定的兑现动作。
+ *
+ * ## 文案与 File 逐字同
+ *
+ * 拒绝文案照抄 core `file-backend.ts` 的 `planOne`(亲读 `1a5ebaa1` 前后两版确认未变),因为
+ * 契约按 `/representation conflict|malformed patch refused/` 匹配,而**跨后端同一输入必须同一答复**
+ * —— 消费方按 reason 分类处置,两支方言各写各的文案就等于让同一件事在不同部署上分叉。
+ *
+ * ## 判位
+ *
+ * 与 File 同precedence:**表示合法性先于状态比较** —— 排在 id/键形守卫之后、add/update 分支
+ * (guard 算术、跨 scope 拒、白洗判据、rev CAS)之前,且在**任何 I/O 之前**(零写拒)。
+ */
+export function ambiguousOriginRefusal(fm) {
+    if (!ambiguousOriginRepresentation(fm))
+        return undefined;
+    return "external-origin marker representation conflict: the entry carries conflicting or duplicated origin representations (malformed patch refused)";
+}
+/**
+ * #319(core 5.47/5.48 契约冻结面,design/336 §5.2)—— **头面 exposure 事实**的同一份归一化。
+ *
+ * 契约逐字:`listHeaders` 与 `search` 两个头面都要携带 `exposure`,且**同一条归一化**
+ * (`committedOriginOf`:typed `frontmatter.origin` 与 legacy 的 `extra` origin 形字节块两种承载,
+ * 一次判、两面同答)。这是**数据事实**不是模式:后端恒报库里存着什么,读侧怎么处置(不透明句柄/
+ * 横幅/两带序)归引擎层的 provenance 模式。缺席 ⇔ 没标记(不等于「证明干净」)。
+ *
+ * 为什么与不可变律同住一个模块:两者读的是**同一个** committed origin。判据(白洗拒)与事实
+ * (exposure 携带)分家写,迟早在某一支方言上一边认得 extra 形、另一边只认 typed 形 —— 那时
+ * 「洗不掉的标记」在检索面**看不见**,而两支后端谁都不会报错。
+ */
+export function exposureCarriage(fm) {
+    return committedOriginOf(fm) !== undefined ? { exposure: "external" } : {};
+}
+/**
+ * 两带序的带号:未标记 = 0(**先**),已标记 = 1。
+ *
+ * 契约的载荷理由(core r1-9,逐字转述):两带序必须落在**截断之前** —— 一页 limit 全是带标条目时,
+ * 排在 limit+1 位的干净条目会被饿死,而工具层**无法**从一页已截断的结果里把它捞回来。
+ * `exposureBands` 缺席/false ⇒ 单带序,与 pre-336 逐字节同(`provenance:"off"` 的读面)。
+ */
+export function exposureBandOf(header) {
+    return header.exposure === "external" ? 1 : 0;
+}
+/**
+ * `committedOriginOf` 的**下推形**:同一条判据的 SQL 写法,给「排序与截断都发生在 SQL 里」的那一档
+ * (Pg 的原生 pgvector 档)用。
+ *
+ * ## 为什么非要下推(不能只在进程里排)
+ *
+ * 原生档 `ORDER BY … LIMIT n` 是**库里**排完就截断的:进程拿到的已经是一页 n 行,被截掉的那条干净
+ * 条目在页里根本不存在,重排救不回来 —— 而「带序必须先于截断」正是这条契约的载荷所在。所以带号
+ * 必须进 ORDER BY,也就必须有一份 SQL 侧的判据。
+ *
+ * ## 为什么写成逐元素的行首正则(codex 对抗复审 R1-[high] 的直接产物)
+ *
+ * 初版图省事写的是 `frontmatter->>'extra' LIKE '%origin:%'`,自称「只多认不漏认」。**错了**,两个方向
+ * 都不成立:`['origin :']`(冒号前有空格)是 core 认的合法承载形,而 LIKE 漏掉它 —— 一条**带标记**的
+ * 条目被排进干净带,占掉的正是干净条目的位置;反过来 `['prefix origin: suffix']` 被 LIKE 误认,一条
+ * **干净**条目沉进后带、可能被截断饿死。两个方向的结局是同一个:干净条目被饿死,而这正是本条款要拒的。
+ *
+ * 现形逐元素跑 core 那条行首正则(`/^\s*origin\s*:/`)。真库实测 10 种拼写(裸 / 冒号前空格 / 前导
+ * 空格 / 制表 / 全角空格 U+3000 / 行中出现 / originx: / 非 origin 行 …)与 JS 判据**逐条同答**。
+ *
+ * ## 这份「第二实现」的同步义务
+ *
+ * 两份实现同表一个语义 = 本仓明令的危险形,所以它带**机器对表**:
+ * `test/memory-engine-db-integration.test.ts` 的钉6 拿同一组拼写在**真 PG** 上让本谓词与
+ * `committedOriginOf` 逐条对答,不一致当场红(离线格做不了这件事:被测的正是 PG 自己的正则引擎)。
+ * core 改那条正则时,红的是对表格 —— 不是某台部署上悄悄跑偏的排序。
+ *
+ * ## 字符类为什么是**穷举码点**而不是 `[[:space:]]`(codex 第二轮 R2-[medium],采纳)
+ *
+ * PG 的 POSIX 字符类**跟着数据库 LC_CTYPE 走**:同一条 SQL 在 C locale 与某个 UTF-8 locale 下认的
+ * 空白集合可以不一样(例如 U+0085 NEL —— JS 的 `\s` **不**含它)。而本谓词的正确性判据是「与 JS 的
+ * `\s` 逐字同」,一条依赖部署 locale 的判据等于把同一条记忆在两台机器上排进不同的带 —— 而带号错了
+ * 就会在 LIMIT 那一刀上不可恢复地截掉本该入页的干净条目。所以这里**不用**任何 locale 敏感构造,把
+ * ECMAScript `\s` 的码点逐个写死(PG 的 ARE 支持 `\uXXXX` 转义,已在真库上验过);对表格里同时钉了
+ * U+0085 这条**反例**(JS 不认 ⇒ SQL 也必须不认),locale 一旦重新混进来它当场红。
+ */
+/** ⚠️ 本常量**只准写 ASCII**:那些 unicode 空白必须以 `\\uXXXX` 的**字面反斜杠形**交给 PG 的 ARE
+ *  自己解析(已在真库上验过)。把真字符敲进源码会同时踩两条线 —— 源码卫生门(不可见字节)与
+ *  U+2028/U+2029(它们在 JS 源码里就是换行，会把这一行劈开)。 */
+const SQL_JS_WHITESPACE_CLASS = "[\\u0009\\u000a\\u000b\\u000c\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]";
+/** core `/^\s*origin\s*:/`(`extraOriginCarriers` 的开块判据)的 SQL 孪生。 */
+export const ORIGIN_CARRIER_LINE_SQL_REGEX = `^${SQL_JS_WHITESPACE_CLASS}*origin${SQL_JS_WHITESPACE_CLASS}*:`;
+/**
+ * 「这一行带 committed origin 标记」的 SQL 布尔式(两种承载形同判,与 {@link exposureCarriage} 同源)。
+ * `column` = 该表 frontmatter 列的表达式(调用方自己保证它是列名/限定名,**不接受外来串**)。
+ */
+export function originMarkedSqlPredicate(column) {
+    return (`(${column}->'origin' IS NOT NULL OR (jsonb_typeof(${column}->'extra') = 'array' AND EXISTS (` +
+        `SELECT 1 FROM jsonb_array_elements_text(${column}->'extra') AS origin_line(line) ` +
+        `WHERE origin_line.line ~ '${ORIGIN_CARRIER_LINE_SQL_REGEX}')))`);
+}
 /** 新建一只批次基线(每次 `applyPatches` 一只;跨批次**不得**复用 —— 已提交的墓碑正是靠「换批清零」放行)。 */
 export function createBatchOriginBaseline() {
     return new Map();

package/dist/plugins/pg-cost-quota.d.ts

@@ -12,12 +12,17 @@
  * and branched THERE. Only the table binding lives here.
  */
 import type { Pool, PoolClient } from "pg";
-import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
+import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgCostQuota implements QuotaTracker {
-    private readonly limitMicroUsd;
     private readonly counter;
+    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
+    private limitMicroUsd;
+    private refreshRequested;
+    private refreshIntervalMs;
     constructor(pool: Pool, limitMicroUsd: number, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    setLimits(next: QuotaLimits): void;
+    private syncRefresh;
     check(scopeKey: string): QuotaDecision;
     add(scopeKey: string, micro: number): void;
     flush(): Promise<void>;

package/dist/plugins/pg-cost-quota.js

@@ -2,18 +2,38 @@ import { PgWriteBehindCounter } from "./write-behind-counter.js";
 /** The counter's table binding for the cumulative cost quota (mirror of the TiDB twin's binding). */
 const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" };
 export class PgCostQuota {
-    limitMicroUsd;
     counter;
+    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
+    limitMicroUsd;
+    refreshRequested = false;
+    refreshIntervalMs;
     constructor(pool, limitMicroUsd, windowMs, now, onDegraded, queryTimeoutMs) {
         this.limitMicroUsd = limitMicroUsd;
         this.counter = new PgWriteBehindCounter(pool, COST_QUOTA_TABLE, windowMs, now, onDegraded, queryTimeoutMs);
     }
+    setLimits(next) {
+        this.limitMicroUsd = next.limitMicroUsd;
+        this.counter.setWindowMs(next.windowMs);
+        this.syncRefresh();
+    }
+    syncRefresh() {
+        if (!this.refreshRequested)
+            return;
+        if (this.limitMicroUsd > 0)
+            this.counter.startRefresh(this.refreshIntervalMs);
+        else
+            this.counter.stop();
+    }
     check(scopeKey) {
+        if (this.limitMicroUsd <= 0)
+            return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
         const used = this.counter.used(scopeKey);
         const allowed = used < this.limitMicroUsd;
         return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec: allowed ? 0 : this.counter.retryAfterSec() };
     }
     add(scopeKey, micro) {
+        if (this.limitMicroUsd <= 0)
+            return;
         this.counter.addLocal(scopeKey, micro);
     }
     // write-behind lifecycle (delegated; exposed for the reaper/tests)
@@ -27,10 +47,13 @@ export class PgCostQuota {
         return this.counter.reap();
     }
     startRefresh(intervalMs) {
-        this.counter.startRefresh(intervalMs);
+        this.refreshRequested = true;
+        this.refreshIntervalMs = intervalMs;
+        this.syncRefresh();
         return this;
     }
     stop() {
+        this.refreshRequested = false;
         this.counter.stop();
     }
 }

package/dist/plugins/pg-rate-limiter.d.ts

@@ -14,12 +14,17 @@
  * self-contained {@link PG_RATE_LIMITER_SCHEMA} + {@link ensureSchema} is safe (no shadowing).
  */
 import type { Pool, PoolClient } from "pg";
-import type { RateDecision, RateGate } from "../observability/rate-limit.js";
+import type { RateDecision, RateGate, RateLimits } from "../observability/rate-limit.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgRateLimiter implements RateGate {
-    private readonly limit;
     private readonly counter;
+    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
+    private limit;
+    private refreshRequested;
+    private refreshIntervalMs;
     constructor(pool: Pool, limit: number, windowMs?: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    setLimits(next: RateLimits): void;
+    private syncRefresh;
     check(key: string): RateDecision;
     /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep(): void;

package/dist/plugins/pg-rate-limiter.js

@@ -2,12 +2,27 @@ import { PgWriteBehindCounter } from "./write-behind-counter.js";
 /** The counter's table binding for the per-key request rate limit (mirror of the TiDB twin's binding). */
 const RATE_LIMIT_TABLE = { table: "rate_limit", keyCol: "limit_key", valCol: "hits" };
 export class PgRateLimiter {
-    limit;
     counter;
+    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
+    limit;
+    refreshRequested = false;
+    refreshIntervalMs;
     constructor(pool, limit, windowMs = 60_000, now, onDegraded, queryTimeoutMs) {
         this.limit = limit;
         this.counter = new PgWriteBehindCounter(pool, RATE_LIMIT_TABLE, windowMs, now, onDegraded, queryTimeoutMs);
     }
+    setLimits(next) {
+        this.limit = next.rateLimitPerMin;
+        this.syncRefresh();
+    }
+    syncRefresh() {
+        if (!this.refreshRequested)
+            return;
+        if (this.limit > 0)
+            this.counter.startRefresh(this.refreshIntervalMs);
+        else
+            this.counter.stop();
+    }
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
@@ -29,10 +44,13 @@ export class PgRateLimiter {
         return this.counter.refresh();
     }
     startRefresh(intervalMs) {
-        this.counter.startRefresh(intervalMs);
+        this.refreshRequested = true;
+        this.refreshIntervalMs = intervalMs;
+        this.syncRefresh();
         return this;
     }
     stop() {
+        this.refreshRequested = false;
         this.counter.stop();
     }
 }

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

@@ -1,6 +1,7 @@
-import { BaseSessionStorage, type PromptEpochDescriptor, type AcquiredSession, type SessionMetadata, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { BaseSessionStorage, type PromptEpochDescriptor, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
+import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
@@ -50,15 +51,29 @@ export declare class PgSessionStore implements SessionStore {
     private readonly pool;
     /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    /** #292 C18(core 5.48.0 design/323):placement 声明(TiDB 孪生同格,义务逐条见
+     *  `src/plugins/session-placement.ts` 顶注)。 */
+    readonly placements: {
+        readonly subagent: {
+            readonly durability: "durable";
+        };
+    };
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);
-    acquire(sessionId?: string, opts?: {
-        requireExisting?: boolean;
-    }): Promise<AcquiredSession>;
+    acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
-    register(sessionId: string, owner: string | null): Promise<void>;
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
+     *  #292:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
+    register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
+    /** #292 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
+    /** #292 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
+     *  见 {@link TiDBSessionStore.listPlaced})。 */
+    listPlaced(kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }): Promise<PlacedSessionRow[]>;
     /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
     touch(sessionId: string): Promise<void>;
@@ -70,8 +85,16 @@ export declare class PgSessionStore implements SessionStore {
         owner: string | null;
         leafId: string | null;
     } | undefined>;
-    /** Durable history is retained; just drop any in-flight cache entry. */
+    /** Durable history is retained; just drop any in-flight cache entry.
+     *  🔴 #292 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
+     *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */
     release(sessionId: string): Promise<void>;
+    /** @see TiDBSessionStore.forget — 丢引用不动 durable 史(preflight 纪律的落点;PG 孪生)。 */
+    forget(sessionId: string): void;
+    /** @see TiDBSessionStore.deletePlacedSession — PG 孪生(条件删门 + meta 先删 + 失败上浮同义)。 */
+    private deletePlacedSession;
+    /** #292:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
+    private assertNotPlaced;
     /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
     listSessions(opts: {
         owner?: string;