@sema-ai/core 1.277.0 → 1.277.1

package/docs/REPL-CODE-MODE-EVALUATION-2026-07-10.md

@@ -1,187 +0,0 @@
-# REPL / code-mode 能力轴评估档 — CHECKLIST #112
-
-> 日期 2026-07-10 · 分支 devendor · 评估者 sema-core design subagent
-> 触发:五维 CC-parity 抽查发现 CC 2.1.198 有 REPL 工具(模型写 JS 程序化直调其他工具的 code-mode 面),我方整件缺,已记 CHECKLIST #112「评估候选非即抄」。本档 = 评估本体(机制取证 + 价值判决 + 形态草案 + 判决),**不写任何产品代码**。
-> 取证 = 亲读 CC 198 源 `claude-cli-2.1.198.pretty.js`(逐字,行号标注);TB 轨迹 = 测试机 `m2-cert-1259-fb/full89`(1.259.0@n=8)真 run。
-
----
-
-## 判决(TL;DR)
-
-**DEFER**(评估记档,暂不落码;等两个先决条件解锁再复评)。
-
-三行核心依据:
-1. **CC 自己没全量**:REPL 灰度门 `Yx()` 默认 **OFF** —— 无 `CLAUDE_CODE_REPL` env 时走 GrowthBook flag `tengu_slate_harbor`,该 flag `nt(...,false)` 默认 false(源 224347-224353 + 144737)。这是「slate/harbor」实验形态,不是 GA 特性 → 「即抄」紧迫度显著降低。
-2. **TB 失败形态不是 code-mode 能救的**:三条失败真轨(filter-js / count-dataset-tokens)已经在用「Write 脚本 → Bash 跑 → Read 输出 → Edit → Bash」的迭代模式;失败根因是**算法/正确性**(filter-js 用 BeautifulSoup 重排了 HTML,违反「不改格式」;count-dataset-tokens 用错 tokenizer),**不是工具调用编排的笨拙**。REPL 给不了增量。
-3. **与我方既有原语高度重叠**:REPL 的「循环/批处理/组合工具调用」在我方 = `Bash`(可跑任意脚本 + 循环)+ subagent(fan-out)+ workflow 已覆盖 90%;REPL 唯一真独有增量 = 「在一个宿主 VM 里让工具调用像函数一样组合、状态跨调用持久、结果作为 JS 值而非文本再解析」的**上下文经济学**(省 round-trip token / 省 LLM 重新解析工具结果),这是 token 经济收益而非能力缺口。
-
----
-
-## 一、机制取证(逐字,CC 2.1.198 源)
-
-### 1.1 工具身份与 schema
-
-- 工具名 `Xf = "REPL"`,`userFacingName()` 也是 `"REPL"`(224355 / 457863)。
-- `searchHint: "execute JavaScript with programmatic tool access"`(457656)。
-- **inputSchema**(457626-457635):
-  - `code: string` —— "JavaScript code to execute. Supports top-level await. **State persists across calls.**"
-  - `description?: string` —— 5-10 词活体描述(同 Bash 的 description 约定)。
-  - `timeout?: number` —— 默认 30000ms,max 600000ms(`jDm=30000` / `pnr=600000`,457594-457595)。
-- **outputSchema**(457637-457651):`code / result / stdout / stderr / error? / registeredTools?[] / images?[] / documents?[]`。注意 `result: unknown` = **代码的返回值直接作为结构化 JS 值回传**(非纯文本),外加 `registeredTools`(本次执行中动态注册的新工具名)和内层 Read 产出的 `images`/`documents`(转成 image/document content block)。
-
-### 1.2 执行环境 = Node `vm` 沙箱(非容器/非进程隔离)
-
-- 用 Node 内置 `vm`(`PHl = require("vm")`,457625;`new PHl.Script(...).runInContext(R,{timeout})`,457789-457794)。
-- VM context 创建(`unr`,457054-457105):`oze.createContext({__proto__:null},{codeGeneration:{strings:true,wasm:false}})` —— **禁 wasm**,允许 `eval`(strings:true,因为要跑用户代码)。
-- **密封点(sealed context)**:
-  - `import()` 动态导入被拦(457791-457793 抛 `nfe("import() is not available in REPL code.")`)。
-  - `import`/`require` 静态扫描拦截:`nnr`→`pDm` 用 `scanImports` 检测 import-statement / dynamic-import / require-call,命中即抛 "Module loading ... is not available in REPL — the vm context is sealed. Use the tool globals instead"(455616-455635)。
-  - prompt 明说:`No import/require/process/Node globals — the VM context is sealed.`(455457)。
-  - **这不是安全沙箱**:Node `vm` 官方文档明确 vm 不是安全边界。它是**能力面收窄**(拿不到 fs/child_process/net),真正的隔离靠下面的「每次内层工具调用走完整权限管线」。
-- 状态持久:VM context 跨 REPL 调用复用(`getReplContexts()[agentId]`,457689;`boundaryUuid` 匹配则复用 `_`,457741),变量与注册工具跨调用保留(prompt 455494 "Variables persist across REPL calls")。有「中毒上下文」恢复:若 replay 把某 global 钉成 non-configurable → 重建 fresh context(457765-457777,HHl 457505-457516)。
-
-### 1.3 哪些工具能从 JS 里调 + 怎么桥接
-
-- 暴露给 VM 的工具集 `BDm`(457397-457403):取 `options.tools` **过滤掉 `is`(某内部工具)和 `Xf`(REPL 自己,防递归)** + 合并 MCP 工具(`Vse(jEe(),t)`),**其余全部暴露** —— 包括 Read/Write/Edit/Glob/Grep/Bash/Task(Agent)/所有 MCP 工具(`await mcp__server__tool({...})`,455451 / 455482)。
-- 桥接工厂 `rFo`/`SDm`(456331-456494):为每个工具生成一个 `async (input) => result` 的 JS 函数注入 VM 全局。调用时:
-  1. `inputSchema.safeParse(input)` 校验(456364)。
-  2. **isolation latch 门**(456367-456379):`bJt` 判 denyMessage,记 `tengu_tool_use_isolation_latch_denied` telemetry(带 `replInnerCall:true`)。
-  3. **PreToolUse hooks**(456383-456388,`gJt`):可 block、可改写 input(`hookUpdatedInput`)、可给 stopReason。
-  4. **权限决策**(456397-456403,`hJt`):`decision.behavior !== "allow"` → deny,调 `onPermissionDenial`,返回 `Permission denied for <tool>: <msg>`。**这是关键安全事实。**
-  5. 真调 `e.call(...)`(456410),带放宽的 limits(REPL 内层 read 无 maxTokens 上限、glob 25000)。
-  6. **PostToolUse hooks**(456425-456428,`mJt`)可改写输出。
-  7. 每步发 progress 事件(`repl_tool_call` phase = start/executing/complete/error),外层据此渲染 + watchdog。
-- **省略约定(dense 变体)**:slate/harbor prompt 里给了一套 shorthand —— `sh(cmd)` / `cat(path)` / `rg(pat)` / `rgf` / `gl` / `put(path,content)` / `chdir` / `haiku(prompt,schema?)`(单轮模型采样!)/ `registerTool`/`unregisterTool`/`listTools`/`getTool`(455436-455453)。这些是工具的薄封装 + 一个 `o={}` 预声明累加器 + 「thenable 在 return 时自动 await」的魔法。
-
-### 1.4 灰度门(默认开吗?——**默认关**)
-
-`Yx()`(224347-224353,= `isEnabled()` 457672-457674):
-```
-if (!e6()) return false;                        // e6()=35583 恒 true,不拦
-if (Hl(env.CLAUDE_CODE_REPL)) return false;     // 显式 off/false/0 → 关
-if (st(env.CLAUDE_CODE_REPL)) return true;      // 显式 on/true/1 → 开
-let e = env.CLAUDE_CODE_ENTRYPOINT;
-if (e === "cli" || e === "remote")
-    return nt("tengu_slate_harbor", false);     // ← GrowthBook flag,默认 false
-return false;
-```
-- `nt(flag, default)`(144737):无本地 override / 无 GrowthBook 缓存命中时**返回 default(=false)**。
-- **结论:默认状态 = OFF。** 只有 ①用户显式设 `CLAUDE_CODE_REPL=1`,或 ②Anthropic 给该会话灰度开了 `tengu_slate_harbor` GrowthBook flag,REPL 才出现。这是「slate/harbor」内部实验分支(prompt 变体 455419-455461 甚至写 "REPL is your **only way** to investigate" —— 一个把 Bash/Read/Grep 全收进 REPL 的激进重构实验),**不是 GA 形态**。
-- 佐证:511814 另一个 `tengu_slate_harbor_experiment` flag 也默认 false,并与 `CLAUDE_CODE_NEW_INIT` 挂钩 —— 整个 slate/harbor 是一整套未全量的实验。
-
-### 1.5 与 Bash 的分工边界
-
-- **两个 prompt 变体**:
-  - **非 slate(默认可见时)变体**(455462-455504):REPL 定位 = "your **programming interface** to Claude Code's tools. Use it to loop, branch, and compose tool calls with code." —— Bash 仍是独立工具,REPL 是**编排层**,建议「把所有操作批进一次 REPL 调用」。
-  - **slate/harbor 变体**(455419-455461):REPL = "your **only way** to investigate" —— shell/file-read/code-search 全走 REPL shorthand,只有 Edit/Write/Agent 留作 top-level 工具。这是把 Bash 吸收进 REPL 的更激进形态。
-- watchdog / 超时分层:script 时间(默认 30s,内层工具调用不计)+ 内层工具 watchdog + 600s 硬墙钟(457800-457809)。「still pending at script end」的未 await 调用会警告并丢弃结果(457819-457826)。
-- `isConcurrencySafe()=false`(457675)、`isReadOnly()=false`(457678):REPL 本身非只读、非并发安全(因为它能跑 Bash/Write)。`checkPermissions()` 对 REPL **自己**恒 allow(457684-457686)—— 但内层每个工具各自过门(见 1.3),**审批不被 REPL 绕过**。
-
----
-
-## 二、价值判决(两个赛道)
-
-### 2.1 TB 判决面 —— code-mode 能救哪些失败形态?
-
-方法:从 `m2-cert-1259-fb/full89`(1.259.0@n=8)取 3 条数据/循环密集型任务真轨对照。
-
-| 任务 | reward | 工具调用形态(真轨) | 失败根因 | REPL 会打得更好吗? |
-|---|---|---|---|---|
-| `filter-js-from-html` | **0** | Write×1 → Bash×11 → Read×3 → Edit×2(经典「写脚本-跑-读-改」迭代) | 用 BeautifulSoup **重排了 HTML**,违反「Do not alter formatting」;12 个 clean 文件里 5 个被误改 | **否**。模型已在写并跑 Python 脚本;失败是算法选型(该用保格式的 parser),与工具调用编排无关。 |
-| `count-dataset-tokens` | **0** | TodoWrite×4 / WebFetch×2 / Bash×8 / Write×1 / Read×1 | 用错 tokenizer(要求 Qwen2.5-1.5B tokenizer),token 数算错 | **否**。纯正确性 / 环境依赖问题。 |
-| `constraints-scheduling` | **1**(过) | Bash×7 迭代 | —— | —— (过题,无失败面) |
-
-**TB 判决结论**:抽到的失败形态**没有一个**是「模型想批量/循环调工具但被 round-trip 拖垮」的形态。TB 题的失败集中在**算法正确性、tokenizer/依赖选型、环境配置**。模型早就有 Bash 可以写任意脚本 + 内部循环 —— code-mode 的「循环/批处理」增量在 TB 上**不构成打平线杠杆**。这与 memory 索引里「M2 并发降质 = 题型选择性、稳定集 16/16 满分」的读数一致:TB 的瓶颈不在工具面编排,在推理/正确性。
-
-> 诚实标注:本抽样 n=3(1 过 2 挂),非全量归因。但选的正是**最可能吃 code-mode 红利**的数据/循环题,若这里都吃不到,全量红利只会更低。若要证伪,需扫全 89 题标注「工具调用编排是否为失败主因」—— 预测该类占比 < 5%。
-
-### 2.2 通用 agent 面 —— 与既有原语的重叠度 + REPL 独有增量
-
-我方既有原语(已核 `src/`):
-- **Bash 工具**:经 `ExecutionEnv`(`src/engine/execution-env/`,`FileSystem + Shell`,harness/types.ts 362-374)跑任意 shell;模型可写 python/node 脚本 + 循环 + 管道。→ 覆盖 REPL 的「循环/批处理/数据变换」**绝大部分**。
-- **subagent / Task**:fan-out 并行、独立上下文。→ 覆盖 REPL 的「并行组合」中的粗粒度部分。
-- **workflow / goal(design/96-98,S8 自助编排)**:脚本化多步编排。→ 覆盖「多步组合」的声明式部分。
-- **并行工具批(design/120 P1 `executeToolCallsPartitioned`)**:单轮内多工具并行执行。→ 覆盖「一次多调用」。
-
-**REPL 的真·独有增量**(既有原语给不了的):
-1. **上下文经济学 / token 效率**:工具结果作为 **JS 值**留在 VM 里被下一步代码直接消费,**不回灌进 LLM 上下文再被重新解析**。「grep→read→grep 在一个 script 里」省掉 2 个 round-trip 的 token + 延迟(prompt 455456 明说「One investigation = one call」)。这是 CC slate/harbor 押注的核心 —— 用 code-mode 压上下文成本。**这是收益点,但属于 token 经济优化,不是能力缺口。**
-2. **跨调用有状态 VM**:变量/中间结果跨 REPL 调用持久(Bash 每次是无状态子进程,除非自己写文件落盘)。
-3. **`registerTool` 动态自建工具 + `haiku()` 内联子采样**:模型在 JS 里现造工具、现调小模型。这是 CC 独有的,但也是最实验性、最未验证的面。
-4. **结构化 image/document 直通**:内层 Read 的图片/PDF 作为 content block 直接冒泡。
-
-**重叠度评估:能力面 ≈ 85-90% 与我方 Bash+subagent+workflow 重叠;独有的 10-15% 主要是 token 经济学与有状态 VM,属「更省」而非「能做我方做不了的事」。**
-
----
-
-## 三、落码形态草案(若判值得 —— 记档备用)
-
-> 判决为 DEFER,以下为解锁后可直接施工的形态草案,不是本轮动工项。
-
-### 3.1 sema seam 形态
-
-- **VM 层**:复用 Node `vm`(与 CC 同),`createContext({__proto__:null},{codeGeneration:{strings:true,wasm:false}})`。**明确它不是安全沙箱**,能力收窄靠不注入 fs/child_process/net + import/require 静态扫描拦截(抄 CC `scanImports`)。真隔离在下面的每-call 权限门。
-- **工具注册表暴露给 VM**:桥接工厂对 harness 的 tool set(除 REPL 自己 + 内部工具)逐个生成 `async (input) => result` 注入 VM 全局。工具名 → JS 函数名直映(Read/Write/Edit/Glob/Grep/Bash/Task/mcp__*)。工具执行仍走 `ExecutionEnv`(`src/engine/execution-env/`),**不新开执行后端**。
-- **状态**:VM context 挂 session/agentId,跨 REPL 调用复用(抄 CC boundaryUuid + 中毒恢复)。
-
-### 3.2 安全面(重点:堵「写代码直调工具绕过 per-call 审批」)
-
-**核心不变量:REPL 内每个内层工具调用,必须走与顶层调用完全相同的门。** 我方已有的门(`src/core/tool-policy.ts` ToolPolicy 三态 / `beforeToolCall` gate / `src/core/hooks.ts` / safety-axis / sensitive-path-policy),内层调用**逐个复用**,不得短路:
-- 校验 input schema → **ToolPolicy / beforeToolCall gate**(可 block / 改写 input / 触发 durable suspend 审批)→ 真执行 → post-tool hook。
-- CC 正是这么做的(§1.3 步骤 2-6:isolation latch + PreToolUse + 权限决策 + PostToolUse 全跑,telemetry 带 `replInnerCall:true`)。**照抄这个结构就堵住了绕过风险。**
-- REPL 工具**自己** `checkPermissions` 可 allow(它不做副作用,副作用全在内层),但这只有在内层门可靠时才成立 —— 否则 = 权限旁路漏洞。落码时这是 **P0 复审焦点 + 对抗 council 必测项**(参 memory「S8 security-heavy 需硬沙箱 + S8b 安全 council」)。
-- 审批交互面:内层工具触发 durable suspend 审批时,REPL script 需能挂起/恢复(比 CC 的 watchdog 更重,因为我方有 durable checkpoint)—— 这是**新增复杂度**,是量级估计上调的主因。
-
-### 3.3 量级估计
-
-- VM 桥接 + 工具注入 + import 扫描:~中(参照 CC ~400 行核心 + prompt)。
-- **每-call 权限门复用 + durable-suspend-in-REPL 语义**:~大(与我方 durable checkpoint / suspend-resume 的交互是新语义,需设计轮)。
-- prompt/description + 输出渲染(image/document 冒泡)+ 测试:~中。
-- **总:一个完整 design 轮 + 对抗 council(安全)+ TB A/B 验收腿**。非小改,是 design 级。
-
-### 3.4 风险清单
-
-1. **权限旁路(P0)**:内层门任一处漏 = 模型写 JS 绕过 per-call 审批直调 Bash/Write。=最高风险,靠 §3.2 结构堵。
-2. **durable-suspend × REPL 语义**:script 中途某工具挂起审批,VM 状态如何 checkpoint/resume?未解决前不可发。
-3. **未全量的上游**:CC 自己 DEFER 状态(灰度关),抄它 = 抄一个 CC 还没验证会不会全量的实验;若 CC 后撤,我方白投。
-4. **token 经济收益 vs 复杂度**:唯一实证收益是上下文经济学,但引入 VM + 双层权限门的复杂度/攻击面很大,ROI 存疑。
-5. **与并行工具批重复**:design/120 P1 已给单轮多工具并行,吃掉了 REPL 的部分「一次多调用」价值。
-
----
-
-## 四、判决与复评条件
-
-**判决:DEFER。**
-
-理由汇总:
-- CC 灰度门默认 OFF(slate/harbor 实验,非 GA)→ 无「即抄」压力,抄它反而是抄未验证实验。
-- TB 失败形态与 code-mode 增量正交(失败在算法/正确性,不在工具编排)→ 对主线 goal(TB 打平 CC)无杠杆。
-- 与既有 Bash+subagent+workflow+并行批重叠 85-90%,独有增量 = token 经济学(「更省」非「能做新事」)→ 不是能力缺口。
-- 落码 = design 级(VM + 双层权限门 + durable-suspend 交互),ROI 相对当前主线(M2.5 打平线)偏低。
-
-**复评触发条件(任一命中即重开评估)**:
-1. **CC 全量**:`tengu_slate_harbor` 转 GA 或 REPL `isEnabled` 默认打开 → 说明 CC 验证了 code-mode,parity 压力回归。
-2. **TB 归因翻转**:全量 89 题标注出现「工具调用编排是失败主因」的题占比 > 10%(当前预测 < 5%)。
-3. **上下文经济学成主瓶颈**:若 OPT-0 profiler / cache 探针显示 round-trip token 是 TB 成本主项(memory 里「腿W 300K/64K 窗口税」若指向此),则 code-mode 的 token 收益从「nice-to-have」升为「杠杆」→ 值得投。
-
-**CHECKLIST #112 状态:评估完成 → DEFER(记档,附三条复评触发)。**
-
----
-
-### 附:关键源行号索引(CC 2.1.198)
-
-| 机制 | 行号 |
-|---|---|
-| 工具名 `Xf="REPL"` / 灰度门 `Yx()` | 224355 / 224347-224353 |
-| `e6()` 恒 true | 35583 |
-| GrowthBook `nt(flag,default)` 默认返回 default | 144737 |
-| inputSchema / outputSchema | 457626-457651 |
-| 工具定义 `cFo`(isEnabled/checkPermissions=allow/call) | 457654-457918 |
-| VM context 创建 `unr`(sealed,no-wasm) | 457054-457105 |
-| 暴露工具集 `BDm`(过滤 REPL 自己 + 合并 MCP) | 457397-457403 |
-| 桥接工厂 `rFo`/`SDm`(**每-call 权限门**) | 456331-456494 |
-| PreToolUse / 权限决策 / PostToolUse | 456383-456428 |
-| import/require 静态拦截 `nnr`/`pDm` | 455616-455635 |
-| prompt(slate + 默认双变体) | 455411-455505 |
-| slate/harbor 实验佐证 | 511814 |
-
-_Co-authored by search-AI design subagent; TB 轨迹取自测试机 91.199.82.197。_

package/docs/REPORT-1249-TARGETED.md

@@ -1,48 +0,0 @@
-# 1.249.0 定向验收腿报告(8 题)
-
-- **job**: targeted-1249-verify  · **模型**: deepseek/deepseek-v4-pro · **口径**: 全默认(未设 TB_FULLBODY/TB_CALLCAP/TB_FINALIZE/TB_FINALVERIFY)= 1.249 主效果,132 默认 ON
-- **tgz**: sema-ai-core-1.249.0.tgz · **-n 4 -r 1** · 运行时长 26m38s · rc=0
-- **题集**: model-extraction-relu-logits, regex-log(P1×2) + build-cython-ext, overfull-hbox, configure-git-webserver, reshard-c4-data, password-recovery(132×5) + path-tracing
-- adapter 同步:本地仓 sema_agent.py 与机上 md5 一致(729add86…),无需覆盖;README.md 已 scp(机上原缺)。
-
-## reward 对照(1239.2 基线 / 1244 基线 / 1249 本腿)
-
-| 题 | 1239.2 | 1244 | 1249 | 关键 mechanisms(1249) | 终态 |
-|---|---|---|---|---|---|
-| model-extraction-relu-logits (TBX-07,P1) | 1 | 0 | 0 | nudges1 capShrinks1 toolClamps8 finalVerify | completed turns=29 |
-| regex-log (P1) | 1 | 0 | **1** | capShrinks1 finalVerify (shrink→length) | completed turns=13 |
-| build-cython-ext (132) | 0 | 0 | 0 | capShrinks1 finalVerify | completed turns=55 |
-| overfull-hbox (132) | 0 | 0 | 0 | capShrinks1 finalVerify | completed turns=31 |
-| configure-git-webserver (132) | 1 | 0 | **1** | capShrinks1 finalVerify | completed turns=15 |
-| reshard-c4-data (132) | 1 | 0 | **1** | finalVerify | completed turns=26 |
-| password-recovery (TBX-09,132) | 1 | 0 | **1** | capShrinks1 finalVerify | completed turns=33 |
-| path-tracing | 0 | 0 | 0 | finalizeInjected nudges1 callCutoffs2 toolClamps1 | timeout turns=49 |
-
-> 注:1244 全 8 题=0(=[405]/[406] P1 系统性截断全域回归的直接体现);1249 4 题恢复(regex/configure-git/reshard/password),其中 configure-git/reshard/password 是回到 1239.2 水平,regex 是 P1 净修复方向证据。
-
-## 判据逐条对账
-
-### P1 修复([408]⑥)
-- ① 「brain.call stopReason=error 且 |cc−cap|<50」形态:**8 题全 0**(反证扫描通过)。1244 基线 relu/regex 各 1 命中,1249 消失。
-- ② shrink→stopReason=length:regex-1249 唯一 shrink 调用 cc=cap=5737 且 **stopReason=length**(非 error,可恢复)✓;relu shrink 调用未死(无 error/length,正常收尾)。
-- ③ capShrinks ≤1:8 题全部 capShrinks∈{0,1}(reasoning 观测豁免生效)✓。1244 path-tracing 曾 capShrinks=6。
-- ④ turns>1(不再 turn1 即死):relu 29 turns、regex 13 turns（1244 两题均 turns=1 秒死)✓。
-- ⑤ reward 翻盘(n=1 仅记方向):regex 0→1 翻盘;relu 仍 0 但死亡形态消失(秒死→跑满 29 turn 后 completed 未解出)。
-
-### 132 触发([409]③)
-- finalVerifyInjected 触发率:**5/5**(build-cython/overfull/configure-git/reshard/password 全 true)✓。
-- reward 翻盘数(vs 1244 全 0):**3/5**(configure-git/reshard/password);但这 3 题 1239.2 本就=1,属回归恢复而非净新增。build-cython/overfull 两题三版均 0,未翻。n=1 不下强结论。
-
-### path-tracing 观察
-- 终态 timeout(turns=49),P2b 兜底出现:callCutoffs=2、toolClamps=1、finalizeInjected=true、nudgesSent=1。
-- 2 个 stopReason=error 调用为 walltime cutoff(cc=0/cap=None,非 P1 形态,不计入 ① 命中)。
-- 对比 1244:同 timeout,机制从 capShrinks6 → callCutoffs2 形态(P2b 主动切流+前缀 salvage 已生效),reward 未变(0)。
-
-### 反证扫描(P1 残留)
-- 8 题全链无「stopReason=error + 打满 cap」残留。path-tracing 的 error 调用是 walltime cutoff 空产出(cap=None),非动态 cap 截断。
-
-## 结论
-- P1 修复判据 ①②③④ 全部 PASS;⑤ regex 翻盘、relu 死亡形态消除(方向正,n=1)。
-- 132 触发率 5/5;翻盘 3/5(均为 1239.2 已通过题的回归恢复),build/overfull 仍 0。
-- path-tracing P2b 对 reasoning 腿兜底闭合确认出现(切流+salvage),终态仍 timeout。
-- UNVERIFIED:reward n=1 不能分离模型非确定性;132 翻盘是否归因 finalVerify 需重复腿。

package/docs/RESEARCH-3P-MEMORY-SWAP-2026-07-12.md

@@ -1,273 +0,0 @@
-# 第三方记忆引擎可换性调研（scope 身份契约 × memory-backend-contract）
-
-- 日期：2026-07-12
-- 定位：纯文档级调研交付，供 fable 出 design/138 r3「第三方引擎对接」正文用；**非终判**。
-- 输入：design/138 §0 四约束（尤其第 4「可接第三方」）+ §2.1/§2.6 adapter 面 + M12 定谳 + 「边界重切 2026-07-12」§3；`src/core/memory-engine/memory-backend-contract.ts`（17 case）；`types.ts`（MemoryEntry/NotePatch/PatchReport）。
-- 新增语境（本次调研增量）：**scope 身份契约**——scope 键语法 `user:<principal>` / `proj:<tenant>/<projectId>`（projectId = in-repo marker 铸造），多租户命名空间，本地↔云按同键同步。
-- 调研对象：Mem0、Zep、Letta（M12 三家）+ 追加 LangMem（LangGraph BaseStore）、Cognee（各 1 家，自拍）。
-- 纪律注记：凡「查不到官方文档明证」的判定标 **UNVERIFIED-训练数据**；官方文档面在部分深页被 license/JS 限制挡住时如实标注。
-
----
-
-## 0. 契约提炼（判定基线，先对齐「换什么」）
-
-memory-backend-contract 的可执行定义可归纳成 6 条能力轴（17 case 是它们的展开）：
-
-| 轴 | 契约要求 | 来源 case |
-|---|---|---|
-| A. 逐字保真存取 | `add` 的 body 原样经 `getByIds` 拿回（rev canonical 口径，尾空白除外） | #1 #4 #11 #12 #14 |
-| B. scope 隔离 | `listHeaders(scopes)` 严格按 scope 过滤；空 scope→空；跨 scope move 语义 | #2 #10 |
-| C. slug/文件名身份 | entry 有 model-visible 可改的 `slug`；同 scope slug 撞→确定性 `-n` 后缀 | #1 #8 |
-| D. 乐观并发 / 版本 | `update`/`delete` 带 `baseRev`；stale→**冲突报告不盲写**；跨实例同库 CAS | #4 #5 #6 #17 |
-| E. 批事务语义 | 逐 patch 独立 applied/conflict；批内同 id 二次非 delete→冲突；malformed 拒绝 | #6 #7 #13 |
-| F. search（词法地板） | 返回 `ScoredEntry[]`，score∈[0,2] 升序、零重叠排除、limit、tie 按 id | #9 #12 #15 #16 |
-| （游标） | consolidation cursor per-scope round-trip | #14 |
-
-**关键不变量**：条目 = 本体，文件 = 引擎投影，id 不可变（uuid，≥8 字符 `ID_RE`），CAS baseRev = 内容哈希（id+frontmatter+body）。第三方引擎要作**权威位**必须能承载 A–F 全部；作**RecallSource 增强位**只需 F（返回 ScoredEntry）。
-
----
-
-## Q1 — scope 身份契约的三键映射矩阵
-
-我们的三键：`user:<principal>`、`proj:<tenant>`、`proj:<...>/<projectId>`。复合键本质 = **tenant × project 二维命名空间**，外加一条正交的 user 维。判定各家能否无损承载：
-
-| 引擎 | 原生分组原语（2026 版本） | user 键 | tenant 键 | project 键 | 复合 tenant×project 映射 | 自托管隔离强度 | 无损？ |
-|---|---|---|---|---|---|---|---|
-| **Mem0** | `user_id` / `agent_id` / `run_id` / `app_id`（+ `org_id`/`project_id` 平台面）；`metadata` 任意 KV | `user_id` | `org_id` 或 `app_id` | `project_id` 或 `metadata.project` | 平台版有 org/project 原生二级；OSS 版靠 `metadata` AND 过滤拼二维 | **行级**（单实例共享向量库，filter 隔离）；OSS 自托管 = Qdrant/PG 单库多租户，无库级墙 | 部分（见下 ⚠️1） |
-| **Zep** | `user_id`（用户图）/ `graph_id`(=旧 `group_id`)（独立图）；`session_id`（会话图） | `user_id` | `graph_id` 命名空间 | 再套一层 `graph_id` 或 group | group graph「完全隔离，无共享状态」；二维需 `graph_id="<tenant>:<project>"` 复合串 | **图级命名空间隔离**（官方称 user/standalone 图彼此完全隔离）；自托管仍单库多图 | 是（命名空间够，但需自拼复合串） |
-| **Letta** | `agent_id`（每 agent 一套 memory）；`organization`（多租户）；memory `block` 可 `label`+跨 agent 共享 | block label 或 agent | `organization` | 无原生 project 层 → agent 命名 / block label 承载 | 弱：Letta 以 **agent** 为记忆宿主，非 scope 命名空间；tenant×project 要映射成「一组 agent」或 block 命名约定 | **PG 行级**（org 列过滤）；自托管单 PG 集群 | ⚠️范畴不匹配（scope≠agent） |
-| **LangMem / LangGraph BaseStore** | `namespace` = 任意 string tuple，如 `("user_123","preferences")` | tuple 段 | tuple 段 | tuple 段 | **原生分层 tuple 天然承载三键**：`(user, tenant, project)` 直接落 namespace | 取决于 BaseStore 实现（PG/内存）；tuple 前缀过滤 = 行级 | **是**（映射最干净的一家） |
-| **Cognee** | `dataset`（带 ownership+permissions）+ 显式 namespaces + 多租户 | user=owner | dataset 或 namespace | dataset 或 namespace | dataset/namespace 二维可拼；多租户官方声称支持 | **行级**（SQLite/LanceDB/KuzuDB 嵌入式默认单库）；库级需自部署拆分 | 部分（namespace 承载，语义偏「知识库」非 scope） |
-
-**Q1 摘要结论**：
-- **映射最干净**：LangMem（BaseStore tuple namespace）——三键直接是 tuple 段，零阻抗。
-- **命名空间够但需自拼复合串**：Zep（`graph_id` 里编码 `tenant/project`）、Cognee（dataset/namespace）。
-- **需 metadata 拼二维**：Mem0 OSS（平台版有 org/project 原生）。
-- **范畴不匹配**：Letta——它的隔离宿主是 **agent 运行时**，不是记忆 scope；把「一个 project scope」映成「一个 Letta agent」是把编排单位当存储单位，会与我们「scope 是纯存储命名空间」的模型对撞。
-- **隔离强度**：五家自托管默认全是**行级/命名空间级**（单库多租户 filter），无一提供开箱**库级/进程级**硬墙——硬隔离需部署方自行拆库。这对我们**可接受**（我们自己的 Pg/File 权威盘也是行级 scope 列），但要在 scope 契约里明确「隔离强度 = 行级，硬墙归部署」。
-
-**⚠️1（Mem0 组合键陷阱，已坐实）**：Mem0 平台面「组合多个 entity 类型的单次查询返回空结果」——即 `user_id` + `agent_id` 同时给会**冲突/空返回**（llama_index #20492 也踩到「同时给 user_id 与 agent_id 不工作」的 bug）。它的多键是**分区选择器不是复合键**：一次只能按 user *或* agent 查。→ 我们的 `proj:<tenant>/<projectId>` 复合键**不能**拆成 Mem0 的两个原生分区，只能塞进单个 `metadata.scope="proj:<tenant>/<projectId>"` 字符串键靠 filter 命中。可行但等于放弃它的原生分区。
-
-来源：
-- Mem0 Entity-Scoped Memory 文档（user_id/agent_id/run_id/app_id + org_id/project_id + metadata；「query user scope OR agent scope」限制）https://docs.mem0.ai/platform/features/entity-scoped-memory
-- Mem0 组合键 bug：https://github.com/run-llama/llama_index/issues/20508 ；namespace 碎片化 issue #25084 https://github.com/NousResearch/hermes-agent/issues/25084
-- Zep group/graph 命名空间 + 完全隔离：https://help.getzep.com/v2/cookbook/how-to-share-memory-across-users-using-group-graphs ；https://help.getzep.com/graphiti/core-concepts/graph-namespacing
-- Letta organization/agent/block：https://docs.letta.com/guides/core-concepts/memory/memory-blocks ；https://deepwiki.com/letta-ai/letta/2.3-agent-memory-system
-- LangGraph BaseStore namespace tuple：https://langchain-ai.github.io/langgraphjs/reference/classes/langgraph-checkpoint.BaseStore.html ；LangMem：https://langchain-ai.github.io/langmem/reference/memory/
-- Cognee dataset/namespace/多租户：https://github.com/topoteretes/cognee ；https://www.cognee.ai/blog/guides/best-open-source-ai-memory-tools-for-llm-agents-and-developers
-
----
-
-## Q2 — 17-case 逐条可通过性判定表
-
-档位：**PASS**（公开 API 直接支持）/ **ADAPTER**（适配层可补，注补法与成本）/ **FAIL**（范畴性过不了，注为什么）。
-
-图例：case 编号对应 contract.ts 中 `defer(...)` 顺序（#1 = 第一条 add→listHeaders）。
-
-### Mem0（infer=False 原始模式作权威盘假设）
-
-| # | 能力 | 判定 | 依据 |
-|---|---|---|---|
-| 1 | add→list/get 可见 + header 字段 | ADAPTER | infer=False 存原文可拿回；但无 `name/description/type/slug/sizeBytes` 结构头，靠 `metadata` 补，`sizeBytes` 自算 |
-| 2 | scope 过滤 + 空 scope 空 | ADAPTER | 用 `metadata.scope` filter；空/未知 scope 返回空天然满足 |
-| 3 | getByIds 跳未知 id | PASS | memory_id 查询，缺失自然空 |
-| 4 | update 带 current baseRev 胜 + 推进 rev | FAIL(D) | **无 baseRev/version/etag/If-Match**（update 文档无并发原语，坐实）；无 rev 概念可推进 |
-| 5 | stale baseRev = 冲突报告不盲写 | **FAIL(D)** | 范畴性：update = last-write-wins 盲写，无冲突检测（官方文档并发面空白 + 社区实测「两条矛盾事实各自 ADD」）。CAS 语义无法承载 |
-| 6 | delete + 未知 id update/delete=冲突 | ADAPTER | delete(memory_id) 有；「未知 id = 冲突」需适配层自己判存在性 |
-| 7 | 批内同 id 二次非 delete 冲突 | ADAPTER | 无批事务语义，适配层自己在提交前查重 |
-| 8 | slug 撞→确定性 -n 后缀 | **FAIL(C)** | **无 slug/文件名概念**，只有系统生成 memory_id UUID（坐实）。slug 身份缺失 |
-| 9 | search 词法地板 [0,2] 升序等 | ADAPTER | search 返回带 score 的结果，但 score 是余弦相似非我们的 jaccard 距离；作 RecallSource 够，逐值等价断言过不了 |
-| 10 | update 跨 scope move | ADAPTER | 改 `metadata.scope` 可模拟；旧 scope 失去/新 scope 得到靠 filter 自然满足 |
-| 11 | 同 scope 同 id re-add = 幂等覆盖 | ADAPTER | ⚠️infer=False「跳过冲突消解」→ 同内容第二次 add **创建第二条**而非覆盖（官方明示）。需适配层先 delete 再 add 或走 update |
-| 12 | getByIds 去重 + limit:0/0.5 空 | ADAPTER | 去重/limit 边界适配层兜 |
-| 13 | entry.id≠patch.id 拒绝 malformed | ADAPTER | 适配层校验 |
-| 14 | consolidation cursor per-scope | ADAPTER | 无游标原语，塞一条特殊 metadata memory 承载 |
-| 15 | search tie 按 id 定序 | ADAPTER | 需适配层重排（引擎不保证 tie 序） |
-| 16 | search 空 query 空 | ADAPTER | 适配层短路 |
-| 17 | 跨实例 CAS | **FAIL(D)** | 同 #5，无版本原语 |
-
-**Mem0 计数：PASS 1 / ADAPTER 12 / FAIL 4**（#4 #5 #8 #17）。范畴性失败：**无 CAS/版本（D 轴 3 条）+ 无 slug（C 轴）**。
-
-### Zep（episode 作 raw 权威盘假设）
-
-Zep 的 episode 被官方描述为「**non-lossy 原始输入存储**（messages/text/JSON）」，从中抽取语义实体/关系——这是 M12 未充分区分的一个**关键新事实**：Zep 除图化外**确实有一个 raw episode 面**。但决定性细节（按 UUID 取回原文 verbatim、episode 是否可 in-place update）文档深页被 license/JS 挡住，标注如下。
-
-| # | 能力 | 判定 | 依据 |
-|---|---|---|---|
-| 1 | add→list/get 可见 + header | ADAPTER | episode 存原文；但无 name/description/slug/sizeBytes 结构头，靠自加字段 |
-| 2 | scope 过滤 | ADAPTER | `graph_id`/`user_id` 命名空间 = scope，list episodes by group 可过滤 |
-| 3 | getByIds 跳未知 | ADAPTER(UNVERIFIED) | 「按 UUID 取单 episode 原文」的 Get 未在可读文档坐实（Go SDK v3.24.0 页 license 挡住；只见 `get_by_group` 与 `episodes/:uuid/mentions`）。标 UNVERIFIED-需核 SDK 源 |
-| 4 | update 带 baseRev 胜 | **FAIL(D)** | 无版本/etag（graph 写并发面文档空白，坐实未见）；且 episode 语义偏 append-only |
-| 5 | stale baseRev 冲突 | **FAIL(D)** | 同上，无 CAS |
-| 6 | delete + 未知 id 冲突 | ADAPTER(UNVERIFIED) | episode delete 存在与否未坐实 |
-| 7 | 批内同 id 冲突 | ADAPTER | 无批事务，适配层兜 |
-| 8 | slug -n 后缀 | **FAIL(C)** | 无 slug/文件名，episode 只有 UUID |
-| 9 | search 词法地板 | ADAPTER | graph.search 返回相关结果，但是**图检索非词法 jaccard**；作 RecallSource 强，逐值等价过不了 |
-| 10 | 跨 scope move | ADAPTER(UNVERIFIED) | 换 graph_id 是否支持未坐实；大概率 delete+re-add |
-| 11 | 同 id re-add 幂等覆盖 | **FAIL(A/C)** | episode 概念是**追加式非幂等**：同内容再 add 产新 episode + 重新抽取。「re-add=覆盖」范畴不成立 |
-| 12 | 去重/limit 边界 | ADAPTER | 适配层兜 |
-| 13 | malformed 拒绝 | ADAPTER | 适配层 |
-| 14 | consolidation cursor | ADAPTER | 无游标，自存 |
-| 15 | search tie 按 id | ADAPTER | 图检索不保证 tie 序 |
-| 16 | search 空 query 空 | ADAPTER | 短路 |
-| 17 | 跨实例 CAS | **FAIL(D)** | 无版本原语 |
-
-**Zep 计数：PASS 0 / ADAPTER 10 / FAIL 4**（#4 #5 #8 #17；#11 记为 FAIL(A/C) 追加 → 实为 5 条范畴问题）。范畴性失败：**append-only 非幂等（A/C）+ 无 CAS（D）+ 无 slug（C）+ 10k 字符/episode 上限**（我们默认 100KB/文件，body 会被迫切块，逐字往返破裂）。
-
-⚠️ 额外硬约束：`graph.add` **10,000 字符上限**，超过要 chunk——这直接和契约的「body 逐字往返 + 100KB/文件」冲突，是 Zep 作权威盘的独立 CATEGORICAL 阻断。来源：https://help.getzep.com/v2/adding-data-to-the-graph
-
-### Letta（archival passages 作权威盘假设）
-
-| # | 能力 | 判定 | 依据 |
-|---|---|---|---|
-| 1 | add→list/get 可见 | ADAPTER(UNVERIFIED) | `passages.insert/list/get` 存在（CRUD 齐）；但「存 verbatim 还是 transform」官方文档**未明示**（标 UNVERIFIED）；无 slug/结构头 |
-| 2 | scope 过滤 | **FAIL(B)** | passages 挂 **agent**，非独立 scope 命名空间。scope≠agent 范畴不匹配（见 Q1 Letta 行） |
-| 3 | getByIds 跳未知 | ADAPTER | passages.get by id 有 |
-| 4 | update baseRev 胜 | **FAIL(D)** | update 存在但**无 version/revision/OCC**（文档并发面空白，坐实）；官方建议靠「timestamp+agent_id 内容内约定」管竞态 = 明证无系统级 CAS |
-| 5 | stale baseRev 冲突 | **FAIL(D)** | 同上 |
-| 6 | delete + 未知冲突 | ADAPTER | delete 有,未知判定适配层兜 |
-| 7 | 批内同 id 冲突 | ADAPTER | 适配层 |
-| 8 | slug -n 后缀 | **FAIL(C)** | 无 slug/文件名，passage 只有系统 id |
-| 9 | search 词法地板 | ADAPTER | archival = 语义搜索,非 jaccard;RecallSource 够 |
-| 10 | 跨 scope move | **FAIL(B)** | 跨 agent 搬 passage = 换宿主,非 scope move |
-| 11 | 同 id re-add 幂等 | ADAPTER(UNVERIFIED) | 需先 delete 再 insert 模拟 |
-| 12–16 | 边界/tie/空 | ADAPTER | 适配层兜 |
-| 17 | 跨实例 CAS | **FAIL(D)** | 无版本原语 |
-
-**Letta 计数：PASS 0 / ADAPTER ~9 / FAIL 5**（#2 #4 #5 #8 #10 #17 中 #2/#10 = scope-agent 范畴,#4/#5/#17 = CAS,#8 = slug）。范畴性失败最重：**记忆宿主 = agent 运行时（B 轴 scope 模型对撞）+ 无 CAS + 无 slug + archival 保真度未证**。M12「Letta 是竞争性 agent 运行时」判断在 scope 契约维度再次坐实。
-
-### LangMem / LangGraph BaseStore（作权威盘假设）— 追加候选，结果最强
-
-BaseStore 是 KV store：`put(namespace, key, value)` / `get` / `delete` / `search(namespace, query)`，value 是**任意 dict 原样存取**（非抽取式）。这是五家里唯一**非抽取范式、逐字保真**的底座。
-
-| # | 能力 | 判定 | 依据 |
-|---|---|---|---|
-| 1 | add→list/get + header | ADAPTER | value dict 里放 body+frontmatter,原样拿回;header 字段自定义 KV。sizeBytes 自算 |
-| 2 | scope 过滤 | PASS | namespace tuple 前缀 = scope,天然过滤 |
-| 3 | getByIds 跳未知 | PASS | get(ns,key) 缺失返回空 |
-| 4 | update baseRev 胜 | ADAPTER(UNVERIFIED) | put 覆盖同 key;**BaseStore 抽象无内建 OCC**（可读文档未见 If-Match）→ CAS 需在 value 里存 rev + put 前 get-compare（有 TOCTOU 窗,除非底层 store 提供事务）。标 UNVERIFIED,取决于具体 BaseStore（PostgresStore 可加条件写） |
-| 5 | stale baseRev 冲突 | ADAPTER | 同 #4:适配层 compare-and-put;严格 CAS 需底层条件写支持,否则弱一致 |
-| 6 | delete + 未知冲突 | ADAPTER | delete 有;未知判定适配层 |
-| 7 | 批内同 id 冲突 | ADAPTER | batch 操作有,冲突判定适配层 |
-| 8 | slug -n 后缀 | ADAPTER | key 可当 slug,-n 后缀适配层生成(比其它家自然:key 是 model-visible string) |
-| 9 | search 词法地板 | ADAPTER | search 是向量/语义,score 非 jaccard;逐值等价过不了,RecallSource 够 |
-| 10 | 跨 scope move | ADAPTER | delete 旧 ns + put 新 ns |
-| 11 | 同 id re-add 幂等覆盖 | PASS | put 同 key = 覆盖,天然幂等(唯一开箱 PASS 这条的) |
-| 12 | 去重/limit 边界 | ADAPTER | 适配层 |
-| 13 | malformed 拒绝 | ADAPTER | 适配层 |
-| 14 | consolidation cursor | ADAPTER | 单独 namespace 存游标 KV |
-| 15 | search tie 按 id | ADAPTER | 重排 |
-| 16 | search 空 query 空 | ADAPTER | 短路 |
-| 17 | 跨实例 CAS | ADAPTER(UNVERIFIED) | 取决于底层 store 是否条件写;PostgresStore 可,MemoryStore 不可 |
-
-**LangMem 计数：PASS 3 / ADAPTER 14 / FAIL 0**。**无范畴性失败**——因为 BaseStore 本质就是我们要的「KV + namespace + 逐字 value」,只缺内建 CAS（可补，强弱取决于底层 store 是否条件写）和 jaccard search（RecallSource 侧不需要）。这是五家里唯一**可能进「适配后可作权威盘」**的候选。⚠️但注意:LangMem 的**背景 memory manager**（create_memory_store_manager）是抽取式改写——那一层要**关掉**,只用裸 BaseStore,否则同样违反逐字契约。
-
-### Cognee（作权威盘假设）
-
-Cognee `add` 会「normalize 成纯文本 + hash 去重 + 组织成 dataset」,然后 `cognify` 抽取成图——**抽取范式**,与逐字契约同样对立。
-
-| 能力簇 | 判定 | 依据 |
-|---|---|---|
-| A 逐字保真 | **FAIL(A)** | add 后走 cognify 图抽取,权威表征是图节点非原文;raw 面存在但非一等取回接口 |
-| C slug | **FAIL(C)** | dataset/节点无 model-visible slug |
-| D CAS | **FAIL(D)** | 无版本/OCC 原语(文档未见) |
-| B scope | ADAPTER | dataset/namespace 承载 scope,行级隔离 |
-| F search | ADAPTER | 14 retrieval modes,RecallSource 强;非 jaccard |
-| E 批事务 | ADAPTER | 适配层 |
-
-**Cognee 计数（簇级）：FAIL 3 簇（A/C/D）**。范畴性失败与 Zep 同型（抽取式 + 无 slug + 无 CAS）。作 RecallSource 增强位很强（graph+vector hybrid,14 模式）。
-
----
-
-## Q2 汇总：每家 PASS/ADAPTER/FAIL 计数 + 范畴性失败清单
-
-| 引擎 | PASS | ADAPTER | FAIL | 范畴性失败（不可适配）清单 |
-|---|---|---|---|---|
-| **LangMem/BaseStore** | 3 | 14 | 0 | 无（唯一无范畴 fail；CAS 强度依底层 store） |
-| **Mem0**（infer=False） | 1 | 12 | 4 | D 轴无 CAS/版本（#4#5#17）、C 轴无 slug（#8）、组合键非复合（Q1⚠️1） |
-| **Zep**（episode） | 0 | 10 | 4–5 | append-only 非幂等（#11 A/C）、无 CAS（#4#5#17 D）、无 slug（#8 C）、**10k 字符/episode 上限**（独立阻断） |
-| **Letta**（passages） | 0 | ~9 | 5 | **scope=agent 范畴对撞（#2#10 B）**、无 CAS（#4#5#17 D）、无 slug（#8 C）、archival 保真度未证 |
-| **Cognee** | 0 | ~簇 | 3 簇 | 抽取式破坏逐字（A）、无 slug（C）、无 CAS（D） |
-
-**共性范畴性失败**（除 LangMem 外五家全中）：
-1. **无乐观并发/版本原语（D 轴）**——这是最致命的共性:五家里除 BaseStore 依底层可补,**Mem0/Zep/Letta/Cognee 全无系统级 CAS**,直接击穿 contract 的 baseRev 冲突语义(#4 #5 #17)。M12 判断在此坐实且强化。
-2. **无 slug/文件名身份（C 轴）**——全部只有系统生成 UUID,无 model-visible 可改 slug + 确定性 -n 后缀。我们「文件为投影,model 用文件技能操作」的锚被打断。
-3. **抽取/改写范式破坏逐字往返（A 轴）**——Zep(图抽取)、Cognee(cognify)、Mem0 默认 infer=True、Letta archival(保真未证)。**唯一有明确 raw 模式**的是 Mem0 infer=False 和 Zep episode「non-lossy」——但都带上面 1/2 的阻断。
-
----
-
-## 综合判决建议（给 fable 出 r3,非终判）
-
-### (a) 权威位可换性：每家「今天可换/适配后可换/永不可换」+ 证据
-
-| 引擎 | 权威位判决 | 核心证据 |
-|---|---|---|
-| **LangMem/BaseStore** | **适配后可换（唯一候选）** | 非抽取 KV+namespace+逐字 value(PASS 3/FAIL 0);关掉背景抽取 manager、CAS 走底层条件写(PostgresStore)。成本=中,主要在 CAS 强一致 + jaccard search 适配。⚠️需核 PostgresStore 是否支持条件写(UNVERIFIED) |
-| **Mem0** | **永不可换（作权威盘）**;degraded 盘技术可行但价值≈裸 Pg（同 M12 §2.6） | 无 CAS(坐实 update 无 version)、无 slug、组合键陷阱、infer=False 非幂等 re-add。4 FAIL |
-| **Zep** | **永不可换** | append-only 非幂等 + 10k 上限 + 无 CAS + 无 slug。episode 有 raw 面但形态与「可覆盖的文件条目」对立 |
-| **Letta** | **永不可换** | scope=agent 范畴对撞(最重)+ 无 CAS + 无 slug;M12「竞争性 agent 运行时」再坐实 |
-| **Cognee** | **永不可换** | cognify 抽取式 + 无 slug + 无 CAS |
-
-**结论**:M12「Mem0/Zep/Letta 无一可作权威 backend」在权威位维度**依然成立**。唯一值得 r3 新增讨论的是 **LangMem/LangGraph BaseStore**——它不是「记忆产品」而是「KV store 抽象」,恰因如此反而是唯一可能跑通契约套件的第三方底座(与 design/138 §3「自实现 MemoryBackend 跑契约套件」正道同构:BaseStore 本身就近似一个 MemoryBackend seam)。
-
-### (b) RecallSource 增强位:接入成本排序（低→高）
-
-1. **Mem0**（最低）——`search(query, filters)→ 带 score 结果`,API 最简,直接映射 `search(query)→ScoredEntry[]`。metadata.scope 过滤天然。
-2. **Cognee**——14 retrieval modes,graph+vector hybrid,召回质量可能最高;成本略高在选模式 + dataset 映射。
-3. **Zep**——`graph.search` 时序知识图召回,质量强(时间感知);成本在 graph_id 命名空间对齐 + 结果结构转 ScoredEntry。
-4. **LangMem/BaseStore**——`search(ns, query)` 有,但它更适合直接作权威位;作纯 RecallSource 是杀鸡用牛刀。
-5. **Letta**（最高/不推荐作侧信道）——archival search 绑 agent,要为召回起一个 agent 宿主,阻抗最大。
-
-RecallSource 只需 F 轴(返回 ScoredEntry),**五家全 ADAPTER-可接**(score 从余弦/图相关度归一到 [0,2] 距离即可)。design/138 §2.6「单向只读侧信道,永不参与 harvest 写回」的定谳对全部五家安全成立。
-
-### (c) M12 定谳是否需修订
-
-**建议:小幅增补,不推翻主结论。**
-- **不推翻**:「Mem0/Zep/Letta 无一可作**权威** backend」在 2026 现状下依然正确,核心是**无系统级 CAS + 无 slug + 抽取范式**三条范畴墙,2026 版本无一家补齐(证据:Mem0 update 文档并发面空白、Zep/Letta 版本原语文档未见)。
-- **需增补 1（新事实)**:M12 措辞「Zep 把文件粉碎成图节点」**不完整**——Zep 有一个官方称「non-lossy」的 **raw episode 面**(原文可存)。但 episode 是 append-only + 10k 上限 + 无 in-place update,依然作不了权威盘;修订建议把理由从「粉碎成图」精确化为「**episode 虽 non-lossy 但 append-only + 10k 上限 + 无 CAS**」,更经得起对抗审。
-- **需增补 2(新候选)**:M12 未覆盖 **LangGraph BaseStore**。建议 r3 显式记一句:「**唯一可能进适配后可换的第三方底座是 LangGraph BaseStore(KV+namespace+逐字 value),因它非抽取式记忆产品而是存储抽象;与 §3『自实现 MemoryBackend』正道同构**」——这既补全调研,又不动 M12 对三家改写型引擎的判决。
-- **需增补 3(Mem0 组合键)**:记档 Mem0「多键=分区选择器非复合键,一次只能 user 或 agent 查」这条硬事实,以防未来有人试图用 Mem0 承载我们的复合 `proj:<tenant>/<projectId>`。
-
-### (d) scope 键语法该预留的兼容点
-
-为**未来任一第三方(尤其 LangMem/Cognee/Zep)可换**,建议 scope 键语法即刻预留:
-
-1. **字符集收窄到 namespace 安全子集**:多家 namespace/group_id/dataset 实测倾向只保证 `[a-z0-9._:/-]` 安全。我们的键含 `:` 和 `/`(`user:<p>` / `proj:<t>/<pid>`)——`/` 在 Zep `graph_id`、Cognee dataset 里可能被当路径分隔或非法。**建议**:定义一个**可逆编码函数** `scopeKey → engineNamespace`(如 `/`→`__`、`:`→`--`),契约里锁定「principal/tenant/projectId 三段各自 `[A-Za-z0-9._-]`,分隔符 `:` `/` 由编码层处理」,避免直接把裸键喂第三方。
-2. **长度上限**:部分引擎 id/namespace 有长度限制(未逐一坐实,标 UNVERIFIED)。建议契约给三段各设**保守上限(如 64 字符/段)**,`projectId`(in-repo marker 铸造)天然可控,`tenant` 归部署方约束。
-3. **大小写与 ASCII**:多家 namespace 只许小写/ASCII。建议 principal/tenant/projectId **锁 ASCII、大小写敏感但不依赖大小写区分**(避免 `Foo`/`foo` 在某引擎折叠成同 namespace 引起 scope 串台)。
-4. **复合键作单串,不拆分区**:因 Mem0 已坐实「组合多分区=空返回」,契约应把 `proj:<tenant>/<projectId>` 当**单个不可拆的 scope 字符串**对待,不假设第三方能按 tenant/project 二级原生索引——二级索引是可选优化,不是契约保证。
-5. **保真回读契约位**:在 scope 契约里显式声明「backend 必须逐字回读 body(rev canonical 口径)」作为**可换性验收前置**——任何候选先过这条才谈接契约套件,把「抽取式引擎」在门口挡掉,不进 17-case 才发现。
-
----
-
-## ④ 文档与关键源坐标
-
-- 本交付:`/Users/clay/开发/gittea/ai-agent-core/docs/RESEARCH-3P-MEMORY-SWAP-2026-07-12.md`
-- 契约套件:`/Users/clay/开发/gittea/ai-agent-core/src/core/memory-engine/memory-backend-contract.ts`(17 case)
-- 类型:`/Users/clay/开发/gittea/ai-agent-core/src/core/memory-engine/types.ts`(MemoryEntry/NotePatch/PatchReport/MemoryBackend)
-- 设计:`/Users/clay/开发/gittea/ai-agent-core/design/138-memory-engine-rearchitecture.md`(§0 四约束 / §2.1 / §2.6 / M12 / 边界重切 §3)
-
-### 主要外部来源（带版本/坐标）
-- Mem0 Entity-Scoped Memory（scope 参数 + 组合键限制）：https://docs.mem0.ai/platform/features/entity-scoped-memory
-- Mem0 Add（infer=False Direct Mode）：https://docs.mem0.ai/core-concepts/memory-operations/add
-- Mem0 Update（无 version/OCC,memory_id only,坐实）：https://docs.mem0.ai/core-concepts/memory-operations/update
-- Mem0 组合键 bug（run-llama #20492/20508）：https://github.com/run-llama/llama_index/issues/20508
-- Mem0 v3 算法（2026-04,LongMemEval 94.8）：https://mem0.ai/blog/state-of-ai-agent-memory-2026
-- Mem0 冲突消解弱（ADD-only,FactConsolidation 18%）：https://github.com/mem0ai/mem0/issues/4896
-- Zep group graph 完全隔离：https://help.getzep.com/v2/cookbook/how-to-share-memory-across-users-using-group-graphs
-- Zep graph namespacing（group_id 命名空间）：https://help.getzep.com/graphiti/core-concepts/graph-namespacing
-- Zep episode = non-lossy raw store + 10k 字符上限：https://help.getzep.com/v2/adding-data-to-the-graph ；https://help.getzep.com/v2/reading-data-from-the-graph
-- Zep 概念（三层 episodes/entities/communities）：https://help.getzep.com/v2/concepts
-- Zep Go SDK v3.24.0（episode 包,2026-07-10,方法列表 license 挡住=UNVERIFIED）：https://pkg.go.dev/github.com/getzep/zep-go/v3/graph/episode
-- Letta memory blocks / core memory：https://docs.letta.com/guides/core-concepts/memory/memory-blocks
-- Letta archival（passages CRUD,保真/OCC 未明示=UNVERIFIED）：https://docs.letta.com/guides/agents/archival-memory/
-- Letta agent memory system（PG/org,竞态靠内容约定）：https://deepwiki.com/letta-ai/letta/2.3-agent-memory-system
-- LangGraph BaseStore（namespace tuple + put/get/search/delete）：https://langchain-ai.github.io/langgraphjs/reference/classes/langgraph-checkpoint.BaseStore.html
-- LangMem memory API（背景抽取 manager = 需关闭以保逐字）：https://langchain-ai.github.io/langmem/reference/memory/
-- Cognee（add→cognify 抽取式,dataset/namespace,多租户）：https://github.com/topoteretes/cognee
-
-### UNVERIFIED-需进一步核实（标注,未当结论）
-- Zep episode「按 UUID 取回原文 verbatim」的 Get 方法、episode in-place update/delete（Go SDK v3.24.0 文档 license 挡住,需读源码坐实）。
-- Letta archival passage 是否 verbatim 存取（官方文档未明示 transform 与否）。
-- LangGraph PostgresStore 是否支持条件写(决定 LangMem 作权威盘的 CAS 强度)。
-- 各家 namespace/id 精确长度上限与字符集白名单(仅从「推荐一致格式」推断,无逐一硬限文档)。