@sema-agent/server 7.43.0 → 7.44.0

package/dist/memory-bundle-engine.js

@@ -1,66 +1,11 @@
-/**
- * #264 v2-c —— `POST /v1/memory/{export,import}` 两口的**引擎接线**(core 5.40.0 design/178 v2-c)。
- *
- * ## 为什么需要这个模块(而不是在 main.ts 里直接 new)
- *
- * 本仓**没有**一个长命的 `MemoryEngine` 实例:`boot/stores.ts` 装配出来的 `memoryEngine` 是
- * `{ backend, root }` 二元组,真正的引擎由 **core 的 Runner 每任务现构**
- * (`core/runner/prepare-memory.js`),而且构出来的 `memoryDir` 是**按任务的 scope 平面**决定的
- * (personal / project / dual-root 三形,还要看仓根、项目标记、pinned 目录)。
- * 也就是说「这个部署的那一个记忆引擎」这个东西**在本仓不存在** —— HTTP 面若要一个引擎,必须自己构。
- *
- * ## 为什么自己构是安全的:这两个面是 **backend-scoped**,不碰 `memoryDir`
- *
- * 亲读 core 5.40.0 的 `memory-engine/engine.js`(不信 JSDoc,读实现):
- *  · `exportMemoryScopes` 全身只用 `this.backend.exportSnapshotOf` 与 `this.now()`;
- *  · `importMemoryBundle` 全身只用 `this.backend.importBundleCommit`(校验段是纯函数 `memoryBundleInvalid`)。
- * 两条路径**都不读** `memoryDir` / `controlDir` —— 它们是**店级**的单锁复合面(一个 epoch 里把五张
- * 店面围起来),不是「某个任务挂载的那棵树」上的操作。因此本模块传给构造器的 `memoryDir` 只是**构造器
- * 的必填座**,对这两条路径无影响。
- *
- * 🔴 这条判断是承重的,所以它有**机器钉**而不是只有这段注释:`test/memory-bundle-engine.test.ts` 用一只
- * 假 backend 断言两条路径确实落到 `exportSnapshotOf` / `importBundleCommit`,且给一个**不存在的**
- * `memoryDir` 也照样工作。core 哪天让这两条路径去读挂载树,那道钉当场红 —— 而不是在某个部署上静默
- * 读错一棵树。
- *
- * ## 能力缺席在**构造期**判定(不挂一个注定失败的口)
- *
- * backend 没有那两个可选面(本仓两只 SQL 记忆孪生就没有)⇒ 本工厂返回 **undefined**,两口整个不挂载,
- * HTTP 面诚实 501。
- *
- * 🔴 首版把这件事当成**运行期**事实(照常挂载,让 core 每次抛 `memory.export_incomplete` / 422),
- * 被 codex 对抗复审驳倒(#277 提货批 [medium],验真后修):`typeof backend.exportSnapshotOf === "function"`
- * 是一次**属性检查**,boot 期就判得出;而且它是**永久**缺席(换后端才会变),不是瞬时状态。照旧挂着
- * 就成了「能力位说 yes、每一次调用都确定性失败」——本仓「says yes ⟺ route works」是结构性承诺,
- * 一个恒假的 yes 会让壳给用户开出一条走不通的迁移流程。
- *
- * ⚠️ 两面是**一个**能力,判据取合取:只有一半也不挂。半挂的形是「导得出、导不进」,而这条产品面的
- * 全部意义是那趟往返。
- *
- * ⚠️ 与**运行期**拒不是一回事,别合并:面齐备但店自陈说不清(chain-degraded)时,core 照样抛
- * `memory.export_incomplete` —— 那是诚实的运行期拒,附录 A 单列一条。绝不在这里回落到「用通用读面拼
- * 一个包」:core 明写那正是它拒绝生产的形(a governance-less export is the laundering shape)。
- */
 import { MemoryEngine } from "@sema-agent/core";
-/**
- * 在**已装配的记忆后端**上建 bundle 两面。命名照 CLAUDE.md 工厂律:返回的是带行为的活对象 ⇒ `create*`。
- *
- * `memoryDir` = `boot/stores.ts` 的 `memoryEngine.root`(该部署的记忆工作根)。见文件头:这两条路径
- * 不读它,传它是为了不发明第二个「引擎根」的概念 —— 万一 core 日后真用上,它拿到的也是本部署唯一的
- * 那个根,而不是一个本模块凭空编出来的路径。
- */
 export function createMemoryBundleFaces(store) {
-    // 构造期能力判定(见文件头):两个可选面缺任一 ⇒ 整个不挂。判据直接读 backend 的面,不看后端方言名
-    // ——「认能力不认实现名」是本仓的既有教训(按部署名判「组件已装」认不出 helm 装的那次)。
     const b = store.backend;
     if (typeof b.exportSnapshotOf !== "function" || typeof b.importBundleCommit !== "function")
         return undefined;
     const engine = new MemoryEngine({ backend: store.backend, memoryDir: store.root });
     return {
         exportScopes: (scopes) => engine.exportMemoryScopes(scopes),
-        // 唯一一次窄化,就发生在**引擎边界上**:core 的 d.ts 要 MemoryExportBundle,而它的实装第一件事
-        // 就是 JSON 深拷 + `memoryBundleInvalid` 整包校验 —— 也就是说这个形参在运行期本就接受任意值,
-        // 由它自己裁。把窄化收在这一行(而不是让它一路污染 HTTP 层的类型)是「谁裁决谁承型」。
         importBundle: (bundle, opts) => engine.importMemoryBundle(bundle, opts),
     };
 }

package/dist/memory-export.js

@@ -1,12 +1,8 @@
-/** All entries of one scope, deterministic id order (both backend read faces ORDER BY id). */
 export async function exportMemoryScope(backend, scope) {
     const headers = await backend.listHeaders([scope]);
     if (headers.length === 0)
         return [];
     const entries = await backend.getByIds(headers.map((h) => h.id));
-    // Defense-in-depth: getByIds is id-keyed (no scope filter). The ids came from THIS scope's own
-    // headers, but a header-read/entry-read race (concurrent cross-scope re-add) must never leak a
-    // foreign scope's entry into an owner-gated export — filter honestly.
     return entries.filter((e) => e.scope === scope);
 }
 //# sourceMappingURL=memory-export.js.map

package/dist/memory-posture.js

@@ -1,7 +1,3 @@
-/**
- * 纯推导(`build*`:产纯数据)。成因的判序是**显式关停 > 租户隔离 > 车道分裂**:
- * operator 自己关的那一形必须报成 `engine_off`,报成隔离/车道会把人指向一个改了也没用的旋钮。
- */
 export function buildMemoryPosture(facts) {
     const { config, engineWired, vectorMode, remoteLaneDark } = facts;
     const embedder = config.memoryEmbedder;
@@ -13,8 +9,7 @@ export function buildMemoryPosture(facts) {
                 ? "multi_tenant_file_backend"
                 : remoteLaneDark
                     ? "remote_lane_split"
-                    : // 到不了的第四形只可能是「装配拒启路径上」(DB 腿半配 fail-loud 已 throw),那时这个对象根本
-                        // 不会被建出来。仍然给一个词而不是 null:点亮态为假时 `darkReason` 必须有值,才谈得上机器可读。
+                    :
                         "engine_off";
     return {
         enabled: engineWired,
@@ -23,19 +18,10 @@ export function buildMemoryPosture(facts) {
         darkReason,
         multiTenant: config.requirePrincipal === true,
         embedder: embedder !== undefined ? { model: embedder.model, dimensions: embedder.dimensions } : null,
-        // #299:键缺席 ⇒ `null`(「本部署没设」),不折成 core 的缺省词 —— 见字段 JSDoc 的诚实纪律。
         delegationEvidence: config.memoryDelegationEvidence ?? null,
-        // #307 件4:同一条诚实纪律 —— 键缺席 ⇒ `null`(「本部署没设」),不折成 core 的缺省词 `carry`。
         provenance: config.memoryProvenance ?? null,
     };
 }
-/**
- * 能力面(`GET /v1/capabilities` 的 `memoryEngine` 位)的**窄投影**:点亮 ⇒ 后端形 + 档位;
- * 暗 ⇒ `false`(位在场且假 = 「这台认识这一位、本部署没点亮」,与位整个缺席 = 老 server 两回事)。
- *
- * 刻意**不**外泄 `darkReason` / `multiTenant` / embedder 身份:能力面是任何持凭证调用方都能读的面,
- * 它只需要回答「我能不能用记忆、用的是哪一档」;成因与身份是运维诊断料,归 operator-only 那一面。
- */
 export function projectMemoryEngineCapability(posture) {
     if (posture === undefined || !posture.enabled)
         return false;

package/dist/memory-scope.js

@@ -1,124 +1,43 @@
-// design/158 N17: the memory-plane resolvers moved VERBATIM out of security.ts (lens4 §4.1 — "budget.ts"'s
-// sibling finding: security.ts's name says auth, but ~110 of its 765 lines were memory-scope config
-// resolution with nothing to do with authentication). security.ts imports memoryScopeFor for its own
-// createAuthorizer; consumers import all four from HERE ([2354] 兼容面全清 — the security.ts compat re-export is gone); index.ts's npm-facing re-export is unaffected (package.json
-// "exports" only ever exposed "." and "./main" — dist/security.js was never a reachable deep-import path).
 import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope } from "@sema-agent/core";
-import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js"; // #271 件1:列宽单一属主(本文件再导出)
-/**
- * design/142 §1.2 的 v2 typed scope-key 前缀表 —— **单一属主**(A-002.4:`config.ts` 的
- * MEMORY_SYNC_SCOPE 派生处曾有一份逐字副本,两处咬合用途不同[盖 v2 契约标 vs 判要不要再包一层
- * `formatUserScope`],但判据必须是同一份,否则 core 加第五种 typed 前缀时两处各自漂)。
- *
- * 🔴 表按 core 的 {@link ParsedScopeKey} 判别词**穷举**:`Record<Exclude<kind,"legacy">, …>` 少一格
- * 编译红、多一格也编译红 —— core 新增/改名一种 typed kind,本表在编译期就先红,而不是等某个运行期
- * 分支静默走错。(`legacy` 排除在外正是本谓词要判的反面:无可识别前缀 = 不透明旧键。)
- */
+import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 const V2_SCOPE_PREFIX_BY_KIND = {
     user: "user:",
     org: "org:",
     proj: "proj:",
     userproj: "userproj:",
 };
-/** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
 export const V2_SCOPE_PREFIXES = Object.freeze(Object.values(V2_SCOPE_PREFIX_BY_KIND));
-/**
- * 一个 scope 键是否带 v2 typed 前缀。
- *
- * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
- * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
- * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
- * 校验点 fail-loud。
- */
 export function isV2ScopeKey(key) {
     return V2_SCOPE_PREFIXES.some((prefix) => key.startsWith(prefix));
 }
-/** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
- *
- *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
- *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
- *  principals are surface labels, not isolation identities — keying memory by them would split the one
- *  user's memory across surfaces). Explicit `MEMORY_SCOPE` wins (it IS config.memoryScope).
- *
- *  MULTI-TENANT (REQUIRE_PRINCIPAL=true): always `undefined` ⇒ no `spec.memory` ⇒ memory is DARK,
- *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
- *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
- *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
-/** R5(批γ):memory scope 列宽(两方言 VARCHAR(190) 同宽)。principal 上限 190 **字符**在
- *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
- *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。
- *
- *  #271 件1:定义**搬去** `plugins/memory-key-guards.ts`(列宽与 store 写口同源单一属主),此处
- *  只再导出——旧 import 路径(本文件)逐字不变,`memoryScopeFor` 的产出处消费点也不变。 */
 export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 export function memoryScopeFor(config, principal, projectId) {
     if (config.requirePrincipal === true) {
-        // S3-TOB(设计 §1.3):multi-tenant lights up ONLY on a DB backend (scope column = tenant
-        // partition) — the scope is the VERIFIED principal, never MEMORY_SCOPE (a shared-env scope here would
-        // be a cross-tenant bleed, 复审 F6) and never absent-principal (anonymous run ⇒ no memory).
-        // NOTE (复审 F-07): the scope column is data PARTITIONING; tenant AUTHORIZATION is exactly this
-        // binding — verified principal in, one tenant's scope out. File backend stays dark (no isolation).
-        // 142-S1.5(core 1.268.0 到货即切,免费迁移窗=现网点亮前存量 0):bare principal → the v2 typed
-        // key `user:<tenant>` via core's formatUserScope (encodeScopeSegment inside — principal chars are
-        // segment-encoded, never truncated/collided). Paired with scopeContract:"v2" on the spec face below
-        // (opt-in is EXPLICIT per design/142 §1.2 — no prefix sniffing anywhere).
-        // 142-S4(派生 v1=项目盘):a SHAPE-VALIDATED projectId(authorizer 的 PROJECT_ID_REGEX 门)
-        // 在场 ⇒ 项目盘 v2 键 `proj:<tenant>/<projectId>`(core formatProjScope;tenant 段 = verified
-        // principal,身份永远不来自 body — projectId 只挑盘)。铁律:proj: 键经我方 DB 的场景=无仓
-        // project(有仓 project 权威=git,根本不到这条派生线)。userproj: 派生不在 v1(待拍板)。
         if (config.memoryEngineBackend === "pg" || config.memoryEngineBackend === "tidb") {
             if (!principal)
                 return undefined;
             const scope = projectId ? formatProjScope(principal, projectId) : formatUserScope(principal);
-            assertMemoryScopeWidth(scope); // R5:编码膨胀在产出处接住,不落 store 裸错
+            assertMemoryScopeWidth(scope);
             return scope;
         }
-        return undefined; // file backend: dark, fail-closed (no tenant isolation in the file engine)
+        return undefined;
     }
-    return config.memoryScope; // single-user: one shared scope — principal labels never partition memory
+    return config.memoryScope;
 }
-/**
- * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core design/138) materializes and
- * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
- * the SANDBOX fs — the planes never meet: materialized memory is invisible inside the sandbox (the injected
- * instructions burn failing Write turns) and sandbox writes are never harvested (add=0). Until core defines
- * the boundary (engine routed through the ExecutionEnv seam, or host-only by contract — relayed on the team
- * channel), a remote lane forces memory DARK unless the operator explicitly vouches both lanes share one fs
- * (`MEMORY_ENGINE_REMOTE_LANE=allow`, e.g. ssh to a host on the same NFS mount).
- *
- * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
- * (no remote lane, or the `host` lane), `dark` = split + fail-closed, `forced` = split + operator override.
- */
 export function memoryEngineRemoteLanePosture(config) {
     const lane = config.remoteExec?.provider;
     if (lane === undefined || lane === "host")
-        return undefined; // hands work THIS machine's fs — same plane
+        return undefined;
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
 }
-/**
- * N0 启动告警的**文案**(纯,可单测;boot/stores.ts 的装配点只负责喂「引擎这一腿真的接上了吗」并打日志)。
- *
- * 为什么要按引擎真身分腿(2026-08-12 复扫,已核真):{@link memoryEngineRemoteLanePosture} 的 `dark` 只对
- * **file** 引擎腿有裁决权 —— 车道门的唯一消费者是 {@link memoryEngineBackendFor}。`MEMORY_ENGINE_BACKEND=pg|tidb`
- * 的两条腿在 boot/stores.ts 里**先于**任何车道判断就被点亮(库是持久真身,与手的文件平面无关),于是同一次
- * 启动会先打 `memory_engine_enabled {enabled:true, backend:"pg"}`,几行之后再打一句「memory dark
- * (fail-closed) … Set MEMORY_ENGINE_REMOTE_LANE=allow」—— 两句直接对撞,而且把运维指向一个在该腿上**不接线**
- * 的旋钮(`memoryEngineRemoteLaneAllowed` 的读者只有本文件与那条日志)。日志是运维唯一能看见的部署事实,
- * 一句谎比没有这句更贵。
- *
- * 返回 `undefined` = 本部署没什么可说的(无平面分裂车道 / 记忆整体关 / 多租户 file 腿的 dark 成因是租户隔离,
- * 已由 `memory_engine_enabled` 的 reason 位报因,不在这里重复)。
- */
-export function buildMemoryRemoteLaneWarn(config, 
-/** 记忆引擎这一腿**真的**接上了吗(`memoryEngine !== undefined`)——装配结果,不在本函数里重算。 */
-engineWired) {
+export function buildMemoryRemoteLaneWarn(config, engineWired) {
     const posture = memoryEngineRemoteLanePosture(config);
     if (posture === undefined || !config.memoryEngineEnabled)
         return undefined;
     if (config.memoryEngineBackend !== "file") {
         if (!engineWired)
-            return undefined; // DB 腿没接上只可能是拒启路径(半配 fail-loud),不在这里猜
+            return undefined;
         return {
             lane: posture.lane,
             effect: `memory ON over a remote lane: the "${config.memoryEngineBackend}" memory plane is durable in the DB and is NOT gated by ` +
@@ -128,7 +47,7 @@ engineWired) {
         };
     }
     if (config.requirePrincipal === true)
-        return undefined; // 多租户 file 腿:dark 的成因是隔离,不是车道
+        return undefined;
     return posture.posture === "dark"
         ? {
             lane: posture.lane,
@@ -141,77 +60,22 @@ engineWired) {
                 "WORKER fs; verify the lane really shares it.",
         };
 }
-/**
- * design/138 S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
- * backend for this deployment, or `undefined` when memory must stay dark.
- *
- *  - SINGLE-USER TURNKEY ONLY (`requirePrincipal !== true`): the engine's file basement
- *    (`FileMemoryEngineBackend` over one directory tree) has NO tenant isolation, so a multi-tenant
- *    deployment gets `undefined` — memory dark, fail-closed (never a shared cross-tenant store).
- *  - `MEMORY_ENGINE=off` (`config.memoryEngineEnabled === false`) is the explicit operator kill-switch.
- *  - REMOTE EXEC LANE (N0): a plane-splitting lane (any non-`host` remoteExec) forces `undefined` — memory
- *    dark, fail-closed — unless `MEMORY_ENGINE_REMOTE_LANE=allow` (see memoryEngineRemoteLanePosture above).
- *  - Directory: `<root>/memory` where root = `resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot)`
- *    (explicit `MEMORY_ENGINE_DIR` → caller's data root → `AGENT_DATA_DIR` env → `~/.ai-agent`). The
- *    FileBackend PINS this directory (core §2.7: `directoryRoot` wins over per-repo derivation), so the
- *    single user has ONE memory home across repos/tasks — the CC `~/.claude` posture.
- *
- * Returns the backend + the resolved config root (the root also rides on `RunnerDeps.memoryEngineDir` so
- * core derives the B3 control plane beside it).
- */
 export function memoryEngineBackendFor(config, fallbackRoot) {
     if (config.requirePrincipal === true || !config.memoryEngineEnabled)
         return undefined;
     if (memoryEngineRemoteLanePosture(config)?.posture === "dark")
-        return undefined; // N0: worker/sandbox file planes split
+        return undefined;
     const root = resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot);
     const dir = join(root, "memory");
-    // 🔴 controlDir EXPLICIT: the backend's DEFAULT control plane derives from the ARGLESS
-    // resolveMemoryEngineRoot() — i.e. AGENT_DATA_DIR/~/.ai-agent, IGNORING an explicit MEMORY_ENGINE_DIR. With a
-    // custom dir the sidecars (ledger/shadow/quarantine) would land under the DEFAULT root while
-    // RunnerDeps.memoryEngineDir points core's engine at the custom root — a split control plane. Pin it beside
-    // OUR root using core's own derivation (key = the memory dir, the same shape as the backend's default).
     return { backend: new FileMemoryEngineBackend(dir, { controlDir: deriveControlPlaneDir(root, dir) }), root };
 }
-/**
- * MF-30 memory PAUSE (option B, per-request — clay 2026-06-27): build the `TaskSpec.memory` spec for ONE run from
- * the resolved memory `scope` + the request's `memoryWrite` toggle. `memoryWrite === false` ⇒ `writeScope: null`
- * (design/138 engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
- * commits nothing). Absent/true ⇒ normal read+write. No scope (engine off / multi-tenant dark) ⇒ undefined
- * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
- * engine-backend presence guard.
- */
-export function memorySpecForRequest(scope, memoryWrite, defaultScopes, 
-/** design/170 件A(#148 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
- *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
- *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
- *  否则单用户部署被自家规则整拒——v4 §0 伤害①的成立前提)。缺参=旧调用形,不盖章(整键缺席=
- *  core legacy 语义,零迁移)。 */
-originPolicy) {
+export function memorySpecForRequest(scope, memoryWrite, defaultScopes, originPolicy) {
     if (!scope)
         return undefined;
-    // 142-S1.5: a scope carrying a v2 typed prefix rides WITH the explicit contract marker — core validates
-    // the key fail-loud under "v2" (design/142 §1.2). Detection here is NOT sniffing: `user:`/`proj:` keys are
-    // OUR memoryScopeFor's own mint (formatUserScope/formatProjScope) and `defaultScopes` entries are the
-    // OPERATOR's center-registry declaration (config.projects — 登记簿说明其形态=v2 scope 键串),so the
-    // prefix is a self/operator-produced marker, never a guess about caller data; a legacy opaque scope
-    // (single-user config.memoryScope) with no defaultScopes stays contract-less byte-identical.
-    const isV2 = isV2ScopeKey; // A-002.4:词表单一属主(见文件顶部 V2_SCOPE_PREFIX_BY_KIND)
-    // 142-S4 defaultScopes 种子(config.projects[projectId].defaultScopes):额外的 READ 层(去重、去 scope
-    // 自身、去空串;保 center 声明顺序)。写路由不变:core normalizeMemorySpec 的 writeScope 缺省=scopes 的
-    // 最后一层,所以带种子时必须 EXPLICIT 钉 writeScope=派生 scope(否则 harvest 会写进登记簿的最后一个默认
-    // scope — 一个共享层,错)。无种子 = 形状逐字节等价旧版(additive 锁)。
+    const isV2 = isV2ScopeKey;
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && arr.indexOf(s) === i);
-    // core 5.1.0([2390]②)删单数 `scope` 键:normalizeMemorySpec 只迭代 `scopes`,单数形 ⇒ undefined ⇒
-    // memory 静默整体关闭(全窗复审 D7-F1,HIGH——返回值位不触发多余属性检查,旧形编译全绿)。生产者恒产
-    // `scopes: [scope, ...extras]`;writeScope 只在带种子时显式钉(core 默认取 scopes 最后一层,无种子时
-    // 最后一层就是派生 scope=正确,不钉保持最小形)。
     const layered = extras.length > 0 ? { scopes: [scope, ...extras], writeScope: scope } : { scopes: [scope] };
     const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
-    // 件A origin 盖章(core 5.13.0 `memory.scopeOrigins` 两格语义):只盖 org 键(非 org 不入准入判决,
-    // v4 §1);派生/env 位的 `scope` org 形只可能来自 operator 显式 MEMORY_SCOPE(memoryScopeFor 多租户
-    // 恒铸 user: 形)⇒ deployment;登记簿种子按部署形态维分格(见参数注)。零 org 键 ⇒ 整键缺席
-    // (core legacy 零迁移;非 org 部署形状逐字节不变=additive 锁)。
     const stamped = {};
     if (originPolicy !== undefined) {
         if (scope.startsWith("org:"))
@@ -222,7 +86,6 @@ originPolicy) {
         }
     }
     const origins = Object.keys(stamped).length > 0 ? { scopeOrigins: stamped } : {};
-    // memoryWrite === false(MF-30 pause)wins over the layered writeScope pin — 只读语义在有种子时同样成立。
     return memoryWrite === false ? { ...layered, writeScope: null, ...v2, ...origins } : { ...layered, ...v2, ...origins };
 }
 //# sourceMappingURL=memory-scope.js.map

package/dist/memory-sync-client.js

@@ -1,29 +1,8 @@
-// 142-S2.5-W1 —— TOC 同步 client 腿:包 core `syncMemoryScope`(1.275.1 导出,一轮 =
-// 一 RTT 双向,cursor 保留纪律见 core sync-client.js 头注)。本模块只补 core 刻意留白的部署半场:
-//   ① transport:fetch POST `{MEMORY_SYNC_URL 去尾斜杠}{path}`(path 由 core 铸,scope 已
-//      encodeURIComponent),headers = Bearer + JSON;非 2xx throw(带 status + body 前 200 字节)。
-//      core 契约:transport 在任何本地写之前跑,throw = 本轮零本地副作用。
-//   ② cursor 持久化:`join(memoryRoot, "sync-cursor-" + encodeScopeSegment(peer) + ".json")`——
-//      读:不存在 ⇒ undefined(首轮);坏 JSON/形状不符/scope-peer 不匹配 ⇒ warn + 当首轮(core 对
-//      错配 cursor 是 fail-loud throw,这里预检降为首轮:空基线重收敛是协议的幂等安全面)。
-//      写:仅 cursorAdvanced 才写(core 保留纪律的落盘半场),tmp+rename 原子。
-//   ③ 串行化 + 节流:syncOnce 按 promise 链串行(两轮并发会在同一文件面上交错写);trigger =
-//      fire-and-forget,上一轮在飞(排队中/执行中)则跳过(设计:简单 inflight 布尔)。
-// conflicts = logger.warn 逐条上报(不自动 ladder——败者铸 sibling 的解决动作留给 operator/后续单)。
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
-/** 缺省对端名(core `syncMemoryScope` 同款缺省;cursor 按 (scope,peer) 分区)。 */
 export const DEFAULT_MEMORY_SYNC_PEER = "central";
-/**
- * fetch transport(core `MemorySyncTransport` 的部署实现)。`url` = 中心 server 基址(尾斜杠剥除,
- * core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的
- * verified-principal 门对齐)。非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error
- * body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core parseMemorySyncResponse,职责
- * 不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把
- * inflight 节流永久卡住(undici 默认 headers 超时 300s 太钝)。
- */
 export function createMemorySyncTransport(opts) {
     const base = opts.url.replace(/\/+$/, "");
     const fetchImpl = opts.fetchImpl ?? fetch;
@@ -41,13 +20,9 @@ export function createMemorySyncTransport(opts) {
         return JSON.parse(text);
     };
 }
-/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录
- *  旁)下的 per-peer sidecar。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同)。 */
 export function memorySyncCursorPath(memoryRoot, peer) {
     return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
 }
-/** 读 cursor:不存在 ⇒ undefined(首轮);坏 JSON / 形状不符 / (scope,peer) 错配 ⇒ warn + undefined
- *  (core 对错配 cursor fail-loud throw——这里预检降为首轮,空基线重收敛幂等安全)。 */
 async function loadCursor(path, scope, peer, log) {
     let raw;
     try {
@@ -83,22 +58,12 @@ async function loadCursor(path, scope, peer, log) {
     log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
     return undefined;
 }
-/** 写 cursor:tmp + rename 原子(半写的 cursor = 下轮坏 JSON 当首轮,重收敛而非错基线)。 */
 async function saveCursor(path, cursor) {
     await mkdir(dirname(path), { recursive: true });
-    // #131-3:staging 名带熵(pid+random)——共享 memoryRoot 的跨进程形(server + run-local 同 data 根)
-    // 用固定 `.tmp` 会互抢 staging(一侧 rename 走对方的 tmp ⇒ 对方 ENOENT / 写出对方字节);同仓其余
-    // 原子写(config-lkg / local-session-store / skills-mcp / workflow-completion-inbox)全带熵,此处对齐。
     const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
     await writeFile(tmp, JSON.stringify(cursor), "utf8");
     await rename(tmp, path);
 }
-/**
- * 组装一个 per-(scope,peer) 的同步执行器:cursor 持久化 + core `syncMemoryScope` + conflicts 上报 +
- * 串行化/节流。`backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` =
- * resolved config root(cursor sidecar 落在 memory/ 目录旁)。
- */
-/** S2.5 分批 loop 的轮数上限(fail-loud 警戒,防协议异常时死循环;正常收敛远低于此)。 */
 export const MAX_SYNC_ROUNDS = 32;
 export function createMemorySyncRunner(opts) {
     const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
@@ -107,8 +72,6 @@ export function createMemorySyncRunner(opts) {
         let cursor = await loadCursor(cursorPath, opts.scope, peer, opts.log);
         let result;
         let subRound = 0;
-        // S2.5 分批续轮:任一半场截断 ⇒ 立即续跑下一子轮(用上一轮返回的 cursor 作基线,协议幂等收敛);
-        // MAX_SYNC_ROUNDS 警戒 fail-loud(截断标志异常粘死时不无限烧请求,余量下轮 trigger 自然补)。
         for (;;) {
             subRound += 1;
             result = await syncMemoryScope({
@@ -131,7 +94,7 @@ export function createMemorySyncRunner(opts) {
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
                 try {
-                    await saveCursor(cursorPath, result.cursor); // 子轮间也持久化(崩溃不回退基线)
+                    await saveCursor(cursorPath, result.cursor);
                 }
                 catch (err) {
                     opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: String(err) });
@@ -140,7 +103,6 @@ export function createMemorySyncRunner(opts) {
             cursor = result.cursor ?? cursor;
             opts.log.info("memory_sync_continuation", { reason, scope: opts.scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
-        // conflicts 逐条 warn(server 半场 + 本地半场聚合,core 绝不隐藏;解决 ladder 不自动跑)。
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
                 scope: opts.scope,
@@ -152,8 +114,6 @@ export function createMemorySyncRunner(opts) {
                 ...(c.currentRev !== undefined ? { currentRev: c.currentRev } : {}),
             });
         }
-        // 保留纪律的落盘半场:仅 cursorAdvanced 才写。写失败只 warn(数据已按 CAS 落定,丢的是基线推进——
-        // 下轮按旧基线重放即幂等自愈,与中心侧 putCursor 失败的收敛论证同款),绝不把成功轮报成失败。
         if (result.cursorAdvanced && result.cursor !== undefined) {
             try {
                 await saveCursor(cursorPath, result.cursor);
@@ -176,8 +136,6 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
-    // 串行链:两轮并发会在同一 File plane / cursor 文件上交错(push 半场读集与 pull 半场落盘互踩)。
-    // `pending` = 排队+在飞的轮数(设计的“简单 inflight 布尔”推广到可排队形态:syncOnce 排队,trigger 跳过)。
     let chain = Promise.resolve();
     let pending = 0;
     const syncOnce = (reason) => {
@@ -192,7 +150,7 @@ export function createMemorySyncRunner(opts) {
     };
     const trigger = (reason) => {
         if (pending > 0)
-            return; // 上一轮在飞 ⇒ 跳过(harvest 高频时的节流;漏掉的变更下一轮全量补上)
+            return;
         void syncOnce(reason).catch((err) => {
             opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, peer, err: String(err) });
         });

package/dist/memory-sync.js

@@ -1,49 +1,7 @@
-// 142-S2.5 中心侧同步 API 的执行内核(设计 sema-internal server/docs/design/142-S4-DATAPLANE.md §2.5;裁定:
-// **plan 随数据走,core 零运行时半场**——core 的 `reconcileMemoryEntries`/`nextSyncBaseline`/
-// `screenInboundEntries` 是纯函数导出,持数据的一侧(本 server=DB 权威+per-(scope,peer) 游标)直接
-// import 调用算 plan 并执行 CAS;API 面全在 server,core 的承诺=纯函数语义稳定。
-//
-// 协议(POST /v1/memory/sync/:scope,http/server.ts 持路由/鉴权/验型;本模块只吃已验型请求):
-//   请求 = { peer, baseRevs, entries[], deletes[] } —— TOC 本地引擎按**自己的**游标把 push 半场打过来:
-//     entries = 自 baseRevs 以来本地新增/变更的条目全量;deletes = 本地删除(tombstone)的 id
-//     (CAS 基线 = baseRevs[id],所以 deletes ⊆ baseRevs 键——验型层已保证)。
-//   响应 = { applied[], conflicts[], serverEntries[], serverDeletes[], cursor } —— 一个 RTT 双向:
-//     serverEntries/serverDeletes = 中心侧自 baseRevs 以来变过/删过的条目 = 本地的 pull 半场。
-//
-// 与 §2.5 草案的两处**诚实偏离**(按 core JSDoc 实况,不硬凑草案):
-//   ① 响应加 `serverDeletes[]`:core MemorySyncPlan.deleteRemote—— 没有删除传播腿,
-//     中心侧删除永远过不去、每轮重摆同一状态 = livelock;草案响应形状缺这条腿。
-//   ② 响应加 `cursor`(本轮落库的 per-(scope,peer) 新基线):客户端应用完 pull 半场后持久化为
-//     自己的游标——它自己算不出(不持有中心全集)。
-//
-// 游标推进纪律(nextSyncBaseline 的 JSDoc 假设「POST-round 双方都已应用」,但响应发出时客户端还
-// **没有**应用 pull 半场——直接乐观推进会在客户端应用失败时把它的旧条目误判为「客户端改过」而回灌
-// 中心 = 数据回退):对 pull 半场(plan.push/plan.deleteRemote)的 id **保留旧基线**。两种客户端结局
-// 都收敛且零回退:客户端应用了 ⇒ 下轮 identical revs → no-op+基线推进;没应用 ⇒ 下轮干净重推。
-//
-// 执行序(任务书①-⑤):
-//   ① screenInboundEntries 入站门(拒 = 该条入 conflicts 上报,不落库不入队——门拒是终态)+
-//     rev 诚实校验(rev = core computeEntryRev 的内容哈希契约;谎报的 rev 会破坏 identical-revs
-//     收敛判定,按条拒入 conflicts,批内其余照常——applyPatches 的 per-patch 非致命姿势);
-//   ② 过门条目按 baseRevs[id] CAS applyPatches(基线有 ⇒ update+baseRev;基线无 ⇒ add——core
-//     MemorySyncPlan JSDoc 的 CAS 纪律原文:absent from the baseline ⇒ plain add);
-//   ③ deletes 同 CAS(plan.deleteLocal 的 {id, baseRev} → delete patch);
-//   ④ reconcileMemoryEntries(baseRevs, 中心集, 对端视图) 算双向 plan(对端视图 = push 条目 +
-//     「基线未提及 id 钉在基线 rev」的合成 stub——stub 永远不会被 pull/delete 判定选中,只参与
-//     rev 对比);⑤ nextSyncBaseline + 保留纪律 → putCursor。
-//
-// putCursor 失败于 applyPatches 之后 = 补丁已落、游标陈旧:向上抛(路由 500),客户端按同一
-// baseRevs 重放即幂等自愈(identical revs 全程 no-op)——游标写不是本轮正确性的一部分。
 import { computeEntryRev, MEMORY_ORIGIN_CAUSES, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
-// ── 验型(HTTP 面的 422 判据;返回 error 字符串而非 throw——validateUserSkills 姿势) ──────────
-/** 一轮 push 的条目数上限 = core REMOTE_HARVEST_MAX_FILES 同款口径(一个 scope 的文件面上限 500;
- *  同步一轮打满全集也在此内)。deletes 上限同基数放宽(全集删除也要能一轮表达)。 */
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
-/** Shape-validate + NORMALIZE the request body (picked-not-spread:只挑认识的字段重建,body 上的
- *  多余键绝不透传进数据面)。`scope` = 路径上已过 owner 门的 scope——每个条目的 scope 必须逐字
- *  等于它(否则一个 owner-gated 路由就成了跨租户写门)。 */
 export function parseMemorySyncRequest(body, scope) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be a JSON object { peer, baseRevs, entries, deletes }" };
@@ -99,12 +57,6 @@ export function parseMemorySyncRequest(body, scope) {
         if (fm["extra"] !== undefined && !(Array.isArray(fm["extra"]) && fm["extra"].every((s) => typeof s === "string"))) {
             return { ok: false, error: "entry.frontmatter.extra must be an array of strings when present" };
         }
-        // #323([4769]):三只 provenance 载体入白名单——修前这里静默剥掉 origin/trust/provenance,
-        // 带标条目过 sync wire 即丢标(污染追踪断链)、rev 恒假冲突(client 以含标载体算 rev),且
-        // 「typed origin + 冲突 extra 块」的歧义表示被选择性改写成非歧义形绕过 core 的
-        // ambiguousOriginRepresentation 拒绝门(applyPatches 直调路径拒、sync 路径放行=同法两答)。
-        // 修=pick+闭集验形(照 core MemoryEntryFrontmatter 单源形),坏形响亮拒;歧义**判定**刻意不在
-        // 这里重复——保真透传后 core 受理门(clause 31)与 sync 路径同答([4770] core 已确认零改动)。
         const rawOrigin = fm["origin"];
         if (rawOrigin !== undefined) {
             if (rawOrigin === null || typeof rawOrigin !== "object" || Array.isArray(rawOrigin))
@@ -120,9 +72,6 @@ export function parseMemorySyncRequest(body, scope) {
         }
         if (fm["trust"] !== undefined && fm["trust"] !== "untrusted")
             return { ok: false, error: 'entry.frontmatter.trust must be the literal "untrusted" when present (single-value union — there is no trusted spelling)' };
-        // core 5.55.0 第 9 键 distilled(consolidation 产物块):受理为**不透明块**浅验过境——成员级判据
-        // 不在这里手抄(F1b 温床),真闸=store add/update 臂的 distilledWhitewashRefusal(committedDistilledOf/
-        // distilledEquals);sync 剥掉它=洗白(#323 origin 同病),深验它=第二份 core 结构。
         const rawDistilled = fm["distilled"];
         if (rawDistilled !== undefined && (rawDistilled === null || typeof rawDistilled !== "object" || Array.isArray(rawDistilled))) {
             return { ok: false, error: "entry.frontmatter.distilled must be an object (opaque consolidation block) when present" };
@@ -152,7 +101,6 @@ export function parseMemorySyncRequest(body, scope) {
                 ...(fm["description"] !== undefined ? { description: fm["description"] } : {}),
                 ...(fm["type"] !== undefined ? { type: fm["type"] } : {}),
                 ...(fm["deleted"] !== undefined ? { deleted: fm["deleted"] } : {}),
-                // #323:三载体保真重建(pick,不 spread——上面已闭集验形;origin 逐成员重建防原对象带私货键)
                 ...(rawOrigin !== undefined
                     ? {
                         origin: {
@@ -203,21 +151,12 @@ export function parseMemorySyncRequest(body, scope) {
     }
     return { ok: true, value: { peer, baseRevs, entries, deletes, ...(pull !== undefined ? { pull } : {}) } };
 }
-// ── 执行内核 ─────────────────────────────────────────────────────────────────────────────────
-/** 基线 stub:对端在基线上、本轮未提及(或被门拒钉回基线)的 id 的合成占位。只有 id/rev 参与
- *  reconcile 判定;rev === baseRevs[id] ⇒ remoteChanged 恒 false ⇒ 永不被 pull/deleteLocal 选中,
- *  身体永不落任何盘。 */
 function baselineStub(id, rev, scope, slug) {
     return { id, rev, scope, slug: slug ?? `sync-baseline-stub/${id}`, frontmatter: {}, body: "" };
 }
-/**
- * One full sync round for one (scope, peer). `backend` = 中心侧 entry plane(DB 权威),`cursors` =
- * per-(scope,peer) 游标面(sync_cursors)。纯数据参数进(路由已完成鉴权/owner 门/验型),响应形状出。
- */
 export async function performMemorySync(backend, cursors, scope, req, now = Date.now) {
     const conflicts = [];
-    // ① 入站门 + rev 诚实校验(拒 = 终态:上报 conflicts,不落库不入队;per-entry 非致命,批内其余照常)。
-    const rejected = new Map(); // id → reason
+    const rejected = new Map();
     for (const e of req.entries) {
         const computed = computeEntryRev(e);
         if (computed !== e.rev)
@@ -233,23 +172,16 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
         conflicts.push({ id, reason, ...(base !== undefined ? { baseRev: base } : {}) });
     }
     const clean = req.entries.filter((e) => !rejected.has(e.id));
-    // 中心侧全集(export 面同款读姿势:listHeaders → getByIds → scope 过滤纵深)。
     const central = await exportMemoryScope(backend, scope);
     const centralById = new Map(central.map((e) => [e.id, e]));
-    // 对端视图:push 条目 + 基线 stub。门拒的 id 钉回基线(有基线时)——绝不能让「拒收」被误判成
-    // 「对端删除」而触发 deleteLocal(中心副本会被误删);新条目被拒 = 视图里干脆没有它。
     const peerView = [...clean];
     const pushedOrDeleted = new Set([...clean.map((e) => e.id), ...req.deletes]);
     for (const [id, rev] of Object.entries(req.baseRevs)) {
         if (pushedOrDeleted.has(id))
             continue;
-        // 未提及 = 对端仍在基线(含被门拒钉回的);stub 只有 rev 参与判定。
         peerView.push(baselineStub(id, rev, scope, centralById.get(id)?.slug));
     }
-    // ④(判定先行)三方 reconcile:local = 中心,remote = 对端视图。
     const plan = reconcileMemoryEntries(req.baseRevs, central, peerView);
-    // ②③ 中心半场执行:pull(采纳对端 push)按 baseRevs CAS;deleteLocal 同 CAS。backend.applyPatches
-    // 的 per-id CAS 是并发纵深——本函数读集与落库之间挤进来的写者会让 baseRev 失配 = 冲突上报,绝不盲写。
     const patches = [
         ...plan.pull.map((e) => {
             const base = req.baseRevs[e.id];
@@ -261,8 +193,6 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
     for (const c of report.conflicts) {
         conflicts.push({ id: c.id, reason: c.reason, ...(c.baseRev !== undefined ? { baseRev: c.baseRev } : {}), ...(c.currentRev !== undefined ? { currentRev: c.currentRev } : {}) });
     }
-    // plan 冲突(双边自基线各自变过 / 删改相撞):currentRev = 中心当前 rev(中心已删则缺席),
-    // 客户端拿它走 §3 ladder(败者铸 sibling)。
     for (const c of plan.conflicts) {
         conflicts.push({
             id: c.id,
@@ -275,7 +205,6 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
             ...(c.local !== undefined ? { currentRev: c.local.rev } : {}),
         });
     }
-    // ⑤ 游标:POST-round 中心集(内存推演,只按 applied 口径——CAS 输掉的补丁不算)× 对端视图。
     const appliedByKey = new Set(report.applied.map((a) => `${a.op}\x1f${a.id}`));
     const appliedPatch = new Map();
     for (const p of patches)
@@ -292,9 +221,6 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
             centralPost.push(p.entry);
     }
     const nextBase = nextSyncBaseline(centralPost, peerView);
-    // 保留纪律(头注):pull 半场的 id 保留旧基线——客户端此刻还没应用 serverEntries/serverDeletes,
-    // 乐观推进会在「客户端没应用」的下一轮把它的旧条目误判成新改动回灌中心(数据回退)。保留旧基线
-    // 两种结局都收敛:应用了 ⇒ identical revs no-op+推进;没应用 ⇒ 干净重推/重删。
     for (const e of plan.push) {
         const base = req.baseRevs[e.id];
         if (base !== undefined)
@@ -302,11 +228,6 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
     }
     for (const d of plan.deleteRemote)
         nextBase[d.id] = d.baseRev;
-    // ⑥ S2.5 pull 分批(契约 settled 2026-07-14):serverEntries 稳定序(id 升序)截 limit;deletes 轻不截。
-    // cursor 精确化约束(core 回执):**不得预填未交付条目的 rev**——有基线的 pull id 上面的保留纪律已经
-    // 钉回旧值;无基线的新条目若未交付,必须从 nextBase 整个剔除(预填=客户端应用交付子集后持久化整张
-    // cursor,下轮把未交付 id 误判「baseline 已知」⇒ 该条目永久漏拉)。已交付的新条目保持 nextSyncBaseline
-    // 值(客户端按纪律应用完交付集才持久化 cursor,安全)。
     let serverEntries = plan.push;
     let pullTruncated = false;
     if (req.pull !== undefined && plan.push.length > req.pull.limit) {