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

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

@@ -1,3 +1,30 @@
+/**
+ * ForkRoutingSessionStore — the subRunner's session backing after core 1.350's fork 终修([1364]①/[1367]①).
+ *
+ * 问题形:core 的 `hostSessionFork` 在 HOST runner 的店里 fork,fork 子任务带 `requireExistingSession:true`
+ * 在 opts.runner(subRunner)上执行——subRunner 拆店时子任务查不到刚 fork 出的会话,响亮失败
+ * `resume.session_not_found`(cli 真机复现)。
+ *
+ * 但把 host durable 店**整个**给 subRunner(第一版修)被 codex 判两 high:普通子任务(council 镜头/
+ * team/子代理)会把每次运行都铸成 committed durable 会话——sweepStagingSessions 只扫**无 session_meta**
+ * 的 staging 弃置行,committed 子会话没有 reaper=无界增长;且进 owner 过滤的会话枚举(零 run 的内部
+ * 会话污染 /v1/sessions)。
+ *
+ * 此包装店按**会话的真居所**路由,两边语义都保住:
+ *  - `acquire(id, {requireExisting})`(fork 子 + retained-child resume 的形)→ **host 店优先**,miss 落
+ *    transient(retained 瞬态子的 resume 仍走私店);两边都 miss=抛 host 侧错误(fail-loud 原语义)。
+ *  - `acquire()`(无 id=普通子任务铸新会话)→ **transient**(throwaway 姿势保留:council/team 子会话
+ *    不落 durable、不进枚举、TTL 自清)。
+ *  - `acquire(id)`(带 id 不 requireExisting)→ 已有路由按路由走;未知 id 落 transient(claim-create
+ *    绝不打到 durable 店——那是 authorizer 的职权)。
+ *  - `fork(sourceId)` → 源在哪店在哪店 fork(路由未知时 host 先试,null 再 transient);新 id 记路由。
+ *  - `list`/`size`/`dispose` = transient 侧(host 店归 main runner 所有;不双列、不双清)。
+ *
+ * 路由表 LRU 上限 {@link ROUTE_MAX}:满额逐最老(refresh-on-use);被逐后下次 `acquire` 按上述规则重derive
+ * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
+ */
+import { SessionError } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
 const ROUTE_MAX = 8192;
 export class ForkRoutingSessionStore {
     host;
@@ -10,9 +37,26 @@ export class ForkRoutingSessionStore {
      *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
      *  parked 子代数,天然小);pick/acquire 首查。 */
     promoted = new Set();
+    /** #292 placement 半场:placed id 名册(与 promoted 同姿势——不随路由 LRU 逐出)。placed 会话的
+     *  真居所恒=host(分区在 durable 店),任何形的 acquire/touch/release 都不得落 transient——
+     *  否则 transient 的 claim-create 会铸出同 id 影子会话,requireExisting 的 transient-first 顺序
+     *  会让影子遮蔽真转录(F-7 顺序对 placed 反向成害)。 */
+    placed = new Set();
+    /** #292:host 店的 placements 声明透传(声明制——包装层不 duck-type,host 声明了才武装 placed
+     *  路由;host 不声明时本店全行为与 5.47 前逐字节同)。 */
+    placements;
+    /** #292:分区枚举透传(host 有才有——恒在的空实现会把「不能枚举」谎报成「没有 placed 会话」)。 */
+    listPlaced;
     constructor(host, transient) {
         this.host = host;
         this.transient = transient;
+        // #292 声明/枚举面:host 声明什么透传什么(transient 永不声明 placements——分区住 durable 店)。
+        if (host.placements !== undefined)
+            this.placements = host.placements;
+        const hostListPlaced = host.listPlaced;
+        if (typeof hostListPlaced === "function") {
+            this.listPlaced = (kind, o) => hostListPlaced.call(host, kind, o);
+        }
         // backlog(hasSessionFork 恒真):两 backing 都无 fork 面时,包装店的 fork 方法**摘除**——core 的
         // fork 门(hasSessionFork(opts.runner.sessions))才能诚实报 fork.unavailable,而不是放行后折叠成
         // 误导性的「source not found」。现三 backing 均有 fork,此臂为接入无 fork durable backend 备。
@@ -30,29 +74,71 @@ export class ForkRoutingSessionStore {
         }
     }
     pick(id) {
-        if (this.promoted.has(id))
-            return this.host; // [1593] 晋升名册优先(路由可被 LRU 逐出,名册不逐)
+        if (this.promoted.has(id) || this.placed.has(id))
+            return this.host; // 名册优先(路由可被 LRU 逐出,名册不逐;placed 同姿势 #292)
         const r = this.route.get(id);
         if (r !== undefined)
             this.remember(id, r); // refresh recency
         return r === "host" ? this.host : this.transient;
     }
+    /** #292:host 声明分区时的冷缓存判位探针。判据=host `requireExisting` acquire 的 `SessionMetadata.placement`
+     *  (5.48 additive,File/SQL/Ttl 三形都带——比 `placementOf` 面更普适:Ttl 缓存层不透传 placementOf)。
+     *  placed 命中把 acquired 会话一并交回(调用方正需要它时零二次 acquire);非 placed/absent 的探针
+     *  acquire 一律 **forget** 收尾([4743] 义务①:验存在的 acquire 禁 release——release(placed)=真删)。 */
+    async hostPlacedProbe(id) {
+        if (this.placed.has(id)) {
+            const acquired = await this.host.acquire(id, { requireExisting: true });
+            return { state: "placed", acquired };
+        }
+        if (this.placements?.subagent === undefined)
+            return { state: "absent" };
+        let acquired;
+        try {
+            acquired = await this.host.acquire(id, { requireExisting: true });
+        }
+        catch (err) {
+            // not_found=常态(绝大多数 id 非 placed),静默折 absent;**真故障**(host 不可达/读错)同样折
+            // absent 但计数留痕(#191 门②:F 类兜底必走 recordFailOpen)——放行的是 transient 腿在 host
+            // 故障窗内保持独立可用,代价与恢复路径见 tag 注册表。
+            if (!(err instanceof SessionError && err.code === "not_found")) {
+                recordFailOpen("server.fork-routing.placed-probe-host-error", err instanceof Error ? err.message : String(err));
+            }
+            return { state: "absent" };
+        }
+        const meta = await acquired.session.getMetadata();
+        if (meta.placement !== undefined) {
+            this.placed.add(id);
+            return { state: "placed", acquired };
+        }
+        await this.host.forget?.(id); // 只为验居所:丢缓存引用,内容不动(禁 release)
+        return { state: "unplaced" };
+    }
     async acquire(sessionId, opts) {
         if (sessionId === undefined) {
-            const a = await this.transient.acquire();
+            const a = await this.transient.acquire(undefined, opts);
             this.remember(a.sessionId, "transient");
             return a;
         }
-        if (this.promoted.has(sessionId)) {
+        // #292 建会话入分区形(受信 spawner:带 placement、不 requireExisting)——分区住 host durable 店;
+        // host 不声明 placements 时按旧行为落 transient(core 铸造门本就不会给这种部署铸 placement,
+        // 这臂只是防御性一致)。
+        if (opts?.placement !== undefined && opts.requireExisting !== true && this.placements?.subagent !== undefined) {
+            const a = await this.host.acquire(sessionId, opts);
+            this.placed.add(sessionId);
+            this.remember(sessionId, "host");
+            return a;
+        }
+        if (this.promoted.has(sessionId) || this.placed.has(sessionId)) {
             // [1593] 晋升名册:恒走 host——绝不能让 transient-first 把 forget 后仍活在私店 repo 里的陈旧
-            // 快照端给 revive(探针 Finding A)。
+            // 快照端给 revive(探针 Finding A)。placed 名册同规则(#292:影子遮蔽真转录的反向 F-7)。
             const a = await this.host.acquire(sessionId, opts);
             this.remember(sessionId, "host");
             return a;
         }
         const routed = this.route.get(sessionId);
-        if (routed !== undefined) {
-            const a = await this.pick(sessionId).acquire(sessionId, opts);
+        if (routed === "host") {
+            const a = await this.host.acquire(sessionId, opts);
+            this.remember(sessionId, "host");
             return a;
         }
         if (opts?.requireExisting) {
@@ -60,9 +146,19 @@ export class ForkRoutingSessionStore {
             // transient(miss)→ fallback host 命中,语义不变。顺序反转封住 F-7 组合链:同 id 在两店并存时
             // (child uuid 被同租户误提交到主 API 而 host 店 claim-create 出空壳),真子会话(transient)赢,
             // 空壳不遮蔽。双 miss 抛 host 侧错误(响亮,fail-closed 到「真不存在」)。
+            // #292 例外:transient 命中且 host 声明分区时,还要过一次 placed 判位——同 id 若在 host 是 placed
+            // 会话,transient 那份是影子(claim-create 铸的),真转录必须赢(F-7 顺序对 placed 反向成害)。
             let transientErr;
             try {
                 const a = await this.transient.acquire(sessionId, opts);
+                if (this.placements?.subagent !== undefined) {
+                    const probe = await this.hostPlacedProbe(sessionId);
+                    if (probe.state === "placed" && probe.acquired !== undefined) {
+                        await this.transient.forget?.(sessionId); // 影子只丢引用(私店 repo 行本就 sweep 不到,名册是真防线)
+                        this.remember(sessionId, "host");
+                        return probe.acquired;
+                    }
+                }
                 this.remember(sessionId, "transient");
                 return a;
             }
@@ -71,6 +167,20 @@ export class ForkRoutingSessionStore {
             }
             try {
                 const a = await this.host.acquire(sessionId, opts);
+                // 顺手:host 端回的会话若带 placement 元组,入名册(后续零探针直达)。只在声明分区的部署上读
+                // (非声明形零行为差),且 meta 读失败不阻断 acquire(名册只是省探针的缓存,不是判定)。
+                if (this.placements?.subagent !== undefined) {
+                    try {
+                        const meta = await a.session.getMetadata();
+                        if (meta.placement !== undefined)
+                            this.placed.add(sessionId);
+                    }
+                    catch (err) {
+                        // 名册只是省探针的缓存,不是判定——缺一条=该 id 下次多付一次 hostPlacedProbe,正确性零影响;
+                        // 计数留痕(#191 门②)让「meta 一直读失败」的环境病在遥测显形。
+                        recordFailOpen("server.fork-routing.placed-roster-meta-unreadable", err instanceof Error ? err.message : String(err));
+                    }
+                }
                 this.remember(sessionId, "host");
                 return a;
             }
@@ -80,6 +190,17 @@ export class ForkRoutingSessionStore {
             }
         }
         // 带 id 但不要求已存在:claim-create 只允许落 transient(durable 店的 claim-create 是 authorizer 的职权)。
+        // #292 claim closure(义务⑥过墙形):id 若已是 host 分区的 placed 会话,claim-create 落 transient 会
+        // 铸同 id 影子——委托给 host claim 形,让其 placement_refused 响亮拒(绝不静默铸影子)。
+        if (this.placements?.subagent !== undefined) {
+            const probe = await this.hostPlacedProbe(sessionId);
+            if (probe.state === "placed") {
+                await this.host.forget?.(sessionId); // 探针引用丢弃(refusal 路径不把会话交出)
+                const a = await this.host.acquire(sessionId, opts); // claim 形打声明店 ⇒ placement_refused(义务⑥)
+                this.remember(sessionId, "host");
+                return a; // 不可达(上一行必抛);保留形以防 host 语义演化时静默吞
+            }
+        }
         const a = await this.transient.acquire(sessionId, opts);
         this.remember(sessionId, "transient");
         return a;
@@ -151,7 +272,9 @@ export class ForkRoutingSessionStore {
         catch {
             // 私店无此会话:可能已在 host(直查确认=幂等),否则如实抛(host 侧错误响亮上浮)
             const probe = await this.host.acquire(sessionId, { requireExisting: true });
-            await this.host.release(probe.sessionId);
+            // #292 preflight 纪律([4743] 义务①):**只为验存在**的 acquire 收尾一律 forget —— host 店的
+            // release 对 placed 会话是真删除(core 5.48 义务 4),用它给一次探活收尾就是拿删除当探针。
+            await this.host.forget?.(probe.sessionId);
             this.promoted.add(sessionId);
             this.remember(sessionId, "host");
             return;
@@ -179,7 +302,9 @@ export class ForkRoutingSessionStore {
                 throw new Error(`session "${sessionId}" promotion verification failed (leaf mismatch after import)`);
         }
         finally {
-            await this.host.release(sessionId);
+            // #292:晋升写完只需**丢引用**(内容必须留下,那正是晋升的目的)⇒ forget,不是 release
+            // (同上:release 对 placed 会话已是真删除,而这条 finally 连失败路径都会走)。
+            await this.host.forget?.(sessionId);
         }
         try {
             await this.transient.forget?.(sessionId);

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

@@ -64,6 +64,7 @@ export declare class PgMemoryEngineBackend 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-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>;