@sema-agent/server 7.139.0 → 7.141.0

package/dist/memory-scope-stores.js

@@ -0,0 +1,86 @@
+import { resolveMemoryScopeStore } from "@sema-agent/core";
+import { memoryScopeContractOf } from "./memory-scope.js";
+export function createMemoryScopeStores(input) {
+    const byPlane = new Map();
+    const resolve = (layer, backend) => resolveMemoryScopeStore({
+        scope: layer,
+        scopeContract: memoryScopeContractOf([layer]),
+        backend,
+        memoryEngineDir: input.root,
+        ...(input.onIncident !== undefined ? { onIncident: input.onIncident } : {}),
+    });
+    return {
+        backend: input.backend,
+        root: input.root,
+        namedLayers: input.namedLayers,
+        storeOf(layer) {
+            const { plane } = resolve(layer, PLANE_PROBE);
+            const known = byPlane.get(plane);
+            if (known !== undefined)
+                return known;
+            const store = resolve(layer, input.backend).backend;
+            byPlane.set(plane, store);
+            return store;
+        },
+    };
+}
+const PLANE_PROBE = Object.freeze({});
+export class MemoryLayerRefusal extends Error {
+    code = "request.memory_layer";
+    constructor(message, cause) {
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.name = "MemoryLayerRefusal";
+    }
+}
+const quoted = (layers) => layers.map((l) => JSON.stringify(l)).join(", ");
+function storeOfNamed(stores, layer, whose, seat) {
+    try {
+        return stores.storeOf(layer);
+    }
+    catch (err) {
+        if (err?.code !== "config.memory_scope_key")
+            throw err;
+        const why = err instanceof Error ? err.message : String(err);
+        throw new MemoryLayerRefusal(whose === "request"
+            ? `the memory layer ${JSON.stringify(layer)} cannot be read: ${why}`
+            : `this deployment's configured memory layer ${JSON.stringify(layer)} cannot be read (${why}), so the store a request that names no layer belongs to cannot be told — name the layer in the request (${seat})`, err);
+    }
+}
+export function memoryStoreForRequest(stores, layers, seat = "`scope`") {
+    if (layers.length > 0) {
+        const groups = new Map();
+        for (const layer of layers) {
+            const store = storeOfNamed(stores, layer, "request", seat);
+            const group = groups.get(store);
+            if (group === undefined)
+                groups.set(store, [layer]);
+            else
+                group.push(layer);
+        }
+        if (groups.size === 1)
+            return [...groups.keys()][0];
+        const split = [...groups.values()].map((g) => `[${quoted(g)}]`).join(" / ");
+        throw new MemoryLayerRefusal(`the memory layers ${quoted(layers)} live in ${groups.size} different memory stores on this deployment and one request reaches one store — send one request per store: ${split}`);
+    }
+    const groups = deploymentStoreGroups(stores, seat);
+    if (groups.size === 1)
+        return stores.backend;
+    const elsewhere = [...groups.entries()].filter(([store]) => store !== stores.backend).flatMap(([, g]) => g);
+    throw new MemoryLayerRefusal(`this deployment keeps memory layers in ${groups.size} stores — the project layers${groups.get(stores.backend).length > 0 ? ` and ${quoted(groups.get(stores.backend))}` : ""} in the deployment's store, ${quoted(elsewhere)} in another — so a request that names no layer cannot be told which store it means; name the layer in the request (${seat})`);
+}
+export function memoryStoresOfDeployment(stores, seat = "`scope`") {
+    return [...deploymentStoreGroups(stores, seat).keys()];
+}
+function deploymentStoreGroups(stores, seat) {
+    const groups = new Map([[stores.backend, []]]);
+    for (const layer of stores.namedLayers()) {
+        const store = storeOfNamed(stores, layer, "deployment", seat);
+        const group = groups.get(store);
+        if (group === undefined)
+            groups.set(store, [layer]);
+        else
+            group.push(layer);
+    }
+    return groups;
+}
+//# sourceMappingURL=memory-scope-stores.js.map

package/dist/memory-scope.d.ts

@@ -8,11 +8,35 @@ export declare const V2_SCOPE_PREFIXES: readonly string[];
  * 一个 scope 键是否带 v2 typed 前缀。
  *
  * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
- * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
- * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
- * 校验点 fail-loud。
+ * 是 fail-loud 抛错,而本谓词的两个读者都只是在决定「要不要挂 v2 标({@link memoryScopeContractOf})/
+ * 同步层要不要另给(`config.ts`)」——把抛点挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。
+ * 坏键仍由 core 在它自己的校验点 fail-loud。
  */
 export declare function isV2ScopeKey(key: string): boolean;
+/**
+ * 本服务给一组记忆层盖的**作用域契约**(core `TaskSpec.memory.scopeContract`)—— 一个判据、两个读者:
+ *  · {@link memorySpecForRequest} 铸 spec 时盖在会话上的那一个(读列表 = 全局层 + 登记簿种子);
+ *  · 同步执行器替一层问「这一层在哪只店」时报给引擎的那一个(`resolveMemoryScopeStore` 的 `scopeContract`,`memory-sync-client.ts`)。
+ * 契约决定**类型化键落哪个平面**(v2 下 `user:` / `userproj:` / `org:` 在个人平面,不透明键在项目平面;不声明则一律项目平面),
+ * 所以两个读者必须读同一只:会话把一层放在哪只店,同步就同步哪只店。
+ *
+ * 判据:列表里有类型化键(前缀表 {@link V2_SCOPE_PREFIXES})⇒ `"v2"`;没有 ⇒ `undefined`(不声明;显式 opt-in,不嗅探调用方数据 ——
+ * 这些键只来自本服务自己的铸点与运维的登记簿,见 {@link memorySpecForRequest} 的 142-S1.5 注)。
+ * 按层问与按会话问答同一只店:平面按**每把键自己的种类**分,契约只挪类型化键,而本判据下带类型化键的会话恒盖 `"v2"`。
+ * 🚧 前提是键为规范形:引擎读键前去掉首尾空白,本判据看原串 —— 带首尾空白的类型化键(`" user:alice"`,配置边界今天放行)本判据不认、引擎在 v2 下读得出,
+ * 于是同一把键在带类型化种子的会话里落个人平面、在不带种子的会话与同步执行器里落项目平面。这是会话面先有的不一致(不同项目的会话对同一层就答两只店,
+ * 同步执行器无从同时对上两者),收口点在配置边界(拒或规范化这一形,后者会挪存量记忆的平面),不在本谓词;未闭环。
+ */
+export declare function memoryScopeContractOf(scopes: readonly string[]): "v2" | undefined;
+/**
+ * 本部署**自己点名**的记忆层 —— 配置里写着的每一层(去重、去空串、保序):单用户的全局层(`MEMORY_SCOPE`,{@link memoryScopeFor} 单用户臂的答案)、
+ * 同步层(`MEMORY_SYNC_SCOPE`,缺省即全局层)、项目登记簿的种子层(`config.projects[*].defaultScopes`,{@link memorySpecForRequest} 盖进会话的读列表)、
+ * 整理层(`MEMORY_CONSOLIDATION_SCOPES`)。项目层(`userrepo:…`)按任务根铸、不在配置里,也就不在这里 —— 它们住部署的店。
+ *
+ * 唯一读者:记忆作用域店的「不点名层的动词答在哪只店」(`memory-scope-stores.ts` 的 {@link memoryStoreForRequest} 无层那一臂)。
+ * 登记簿随中心配置热换(`applyEffective` 在同一只 `config.projects` 对象上原地整表换内容),所以读者每次现调本函数,不在起服时冻一份。
+ */
+export declare function memoryLayersNamedBy(config: Pick<ServiceConfig, "requirePrincipal" | "memoryScope" | "memorySync" | "projects" | "memoryConsolidationDriver">): string[];
 /** Resolve the memory scope for a request —— {@link memoryScopeFor} 的三形(按实现逐臂写;[ref] 合并前主会话点名:
  *  旧版这里写「多租户恒 `undefined` ⇒ 记忆暗」,与下面 DB 后端那一臂正好相反,test [ref] 就是被这句带偏的)。
  *
@@ -22,7 +46,7 @@ export declare function isV2ScopeKey(key: string): boolean;
  *     **读列表的第二层**,不是写家:写家是该任务的**项目层**,由 {@link memoryProjectKeyFor} 按任务根派生、经
  *     {@link memorySpecForRequest} 的 `projectKey` 位铸进 spec(读 = [项目, 本 scope],`writeScope` 显式 = 项目)。
  *     本函数在授权期调(还不知道任务根),所以项目层不在这里。
- *  ② MULTI-TENANT + DB 后端(`requirePrincipal === true` ∧ `memoryEngineBackend` ∈ {`pg`, `tidb`}):按**验过的**
+ *  ② MULTI-TENANT + DB 后端(`requirePrincipal === true` ∧ `memoryEngineBackend` ∈ {`pg`, `mysql`}):按**验过的**
  *     principal 铸 v2 typed 键 —— 无 projectId ⇒ `user:<tenant>`(core `formatUserScope`),有形状合法的
  *     projectId ⇒ `proj:<tenant>/<projectId>`(core `formatProjScope`);principal 缺席(匿名 run)⇒ `undefined`
  *     (无记忆)。scope 列是租户分区,授权就是「验过的 principal 进、一个租户的 scope 出」这一绑定;身份永远不来自
@@ -93,8 +117,8 @@ export declare function replicatesProjectLayersOf(coverage: MemoryReplicationCov
  * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
  * (the lane's file plane IS this worker's fs — `in-process` / `host`), `dark` = split + fail-closed, `forced` =
  * split + operator override.
- * [ref]: the plane question reads the lane-caps table (`hostFilePlane`) — it used to be the hand-written synonym
- * `lane === undefined || lane === "host"` (fold-ban gate D, R3); readings are unchanged lane by lane.
+ * The plane question reads the execution environment block (`hostLocalPaths`, sole author `capabilitiesFor`) — it used to be the
+ * hand-written synonym `lane === undefined || lane === "host"`; readings are unchanged lane by lane.
  */
 export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
     lane: ExecutionLane;
@@ -104,7 +128,7 @@ export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
  * N0 启动告警的**文案**(纯,可单测;boot/stores.ts 的装配点只负责喂「引擎这一腿真的接上了吗」并打日志)。
  *
  * 为什么要按引擎真身分腿(2026-08-12 复扫,已核真):{@link memoryEngineRemoteLanePosture} 的 `dark` 只对
- * **file** 引擎腿有裁决权 —— 车道门的唯一消费者是 {@link memoryEngineBackendFor}。`MEMORY_ENGINE_BACKEND=pg|tidb`
+ * **file** 引擎腿有裁决权 —— 车道门的唯一消费者是 {@link memoryEngineBackendFor}。`MEMORY_ENGINE_BACKEND=pg|mysql`
  * 的两条腿在 boot/stores.ts 里**先于**任何车道判断就被点亮(库是持久真身,与手的文件平面无关),于是同一次
  * 启动会先打 `memory_engine_enabled {enabled:true, backend:"pg"}`,几行之后再打一句「memory dark
  * (fail-closed) … Set MEMORY_ENGINE_REMOTE_LANE=allow」—— 两句直接对撞,而且把运维指向一个在该腿上**不接线**
@@ -148,13 +172,13 @@ engineWired: boolean): {
  * (壳布局 `~/.sema/engine-data`)」时分家 ⇒ 记忆库每一次 Write 被硬拒(7.58.0 放行 ⇒ 回归);反向
  * (`CONFIG_LOCAL_DIR=~/.sema` 当 dataRoot)则让配置根自身免检。两根本就是两件事:店根归誊本门,引擎根归本函数。
  *
- * 形与 boot/stores.ts 逐字同律:DB 记忆腿(pg/tidb)的根 = `<localDataRoot ?? localRoot>/memory-work`
+ * 形与 boot/stores.ts 逐字同律:DB 记忆腿(pg/mysql)的根 = `<localDataRoot ?? localRoot>/memory-work`
  * (per-worker 物化区);file 腿 = boot file 后端的链 `resolveMemoryEngineRoot(memoryEngineDir)`。**不判引擎是否
  * 启用**——纯路径推导,禁用态下豁免根仍以「若开引擎会写到哪」为根(boot 的 `engineDataRoot` 恒铸,经共享基座交每只 Runner)。
  */
 export declare function memoryEngineRootFor(config: Pick<ServiceConfig, "memoryEngineBackend" | "memoryEngineDir" | "localDataRoot">, localRoot?: string): string;
 /** file 后端的根链(`MEMORY_ENGINE_DIR ?? fallback ?? $AGENT_DATA_DIR ?? ~/.ai-agent`)—— 与后端选择器**无关**:
- *  `memoryEngineBackendFor` 恒造 file 后端(run-local 从 env 继承 `MEMORY_ENGINE_BACKEND=pg|tidb` 时仍是 file),
+ *  `memoryEngineBackendFor` 恒造 file 后端(run-local 从 env 继承 `MEMORY_ENGINE_BACKEND=pg|mysql` 时仍是 file),
  *  所以它的根必须走这条链而不是 `memoryEngineRootFor` 的分派(codex 修复验证轮 [medium]:分派会把 run-local 的
  *  记忆搬到 `<localDataRoot>/memory-work`,存量记忆与控制面升级后隐形)。 */
 export declare function fileMemoryEngineRoot(config: Pick<ServiceConfig, "memoryEngineDir">, fallbackRoot?: string): string;

package/dist/memory-scope.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
-import { executionLaneCaps, executionLaneOf } from "./execution-lane-caps.js";
+import { capabilitiesFor, executionLaneOf } from "./execution-lane-caps.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 import { projectLayerForTaskRoot } from "./project-identity.js";
 import { parseProjectLayerKey, projectLayerOwnerOf } from "./project-layer-key.js";
@@ -14,10 +14,22 @@ export const V2_SCOPE_PREFIXES = Object.freeze(Object.values(V2_SCOPE_PREFIX_BY_
 export function isV2ScopeKey(key) {
     return V2_SCOPE_PREFIXES.some((prefix) => key.startsWith(prefix));
 }
+export function memoryScopeContractOf(scopes) {
+    return scopes.some(isV2ScopeKey) ? "v2" : undefined;
+}
+export function memoryLayersNamedBy(config) {
+    const named = [
+        ...(config.requirePrincipal === true ? [] : [config.memoryScope]),
+        ...(config.memorySync !== undefined ? [config.memorySync.scope] : []),
+        ...Object.values(config.projects ?? {}).flatMap((p) => p.defaultScopes ?? []),
+        ...config.memoryConsolidationDriver.scopes,
+    ];
+    return named.filter((s, i) => typeof s === "string" && s.length > 0 && named.indexOf(s) === i);
+}
 export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 export function memoryScopeFor(config, principal, projectId) {
     if (config.requirePrincipal === true) {
-        if (config.memoryEngineBackend === "pg" || config.memoryEngineBackend === "tidb") {
+        if (config.memoryEngineBackend === "pg" || config.memoryEngineBackend === "mysql") {
             if (!principal)
                 return undefined;
             const scope = projectId ? formatProjScope(principal, projectId) : formatUserScope(principal);
@@ -64,7 +76,7 @@ export function replicatesProjectLayersOf(coverage, owner) {
 }
 export function memoryEngineRemoteLanePosture(config) {
     const lane = executionLaneOf(config.remoteExec?.provider);
-    if (executionLaneCaps(lane).hostFilePlane === "supported")
+    if (capabilitiesFor(config).hostLocalPaths)
         return undefined;
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
 }
@@ -158,14 +170,14 @@ export function memorySpecForRequest(scope, projectKey, memoryWrite, defaultScop
         throw new Error(`memory project scope ${JSON.stringify(projectScope)} equals the global memory scope (MEMORY_SCOPE) — the project layer and the global layer would be one directory. ` +
             "Set MEMORY_SCOPE to a name outside the server-minted project-key families (see src/project-layer-key.ts).");
     }
-    const isV2 = isV2ScopeKey;
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && s !== projectScope && arr.indexOf(s) === i);
     const layered = projectKey !== undefined
         ? { scopes: projectScope !== undefined ? [projectScope, scope, ...extras] : [scope, ...extras], writeScope: projectScope ?? scope, projectKey }
         : extras.length > 0
             ? { scopes: [scope, ...extras], writeScope: scope }
             : { scopes: [scope] };
-    const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
+    const contract = memoryScopeContractOf([scope, ...extras]);
+    const v2 = contract !== undefined ? { scopeContract: contract } : {};
     const stamped = {};
     if (originPolicy !== undefined) {
         if (scope.startsWith("org:"))

package/dist/memory-sync-client.d.ts

@@ -1,4 +1,6 @@
-import { type MemoryBackend, type MemorySyncClientResult, type MemorySyncTransport } from "@sema-agent/core";
+import { type MemorySyncClientResult, type MemorySyncTransport } from "@sema-agent/core";
+import type { ServiceConfig } from "./config-types.js";
+import type { MemoryScopeStores } from "./memory-scope-stores.js";
 import { type OneTimeMigrationWindow } from "./plugins/one-time-migrations.js";
 /** 结构化日志面(src/observability/logger.ts Logger 的结构子集——测试可注入捕获器)。 */
 export interface MemorySyncLog {
@@ -18,7 +20,7 @@ export interface MemorySyncLog {
  */
 export declare function memorySyncPeerOf(url: string): string;
 /**
- * 起服日志行 `memory_sync_enabled` 的字段(两处起服 —— `boot/stores.ts` 与 `run-local.ts` —— 同读这一只)。`peer` 是运维改绑游标时要抄的那个值:
+ * 起服日志行 `memory_sync_enabled` 的字段(两处起服 —— `boot/stores.ts` 与 `run-local.ts` —— 同读这一只)。`peer` 是这一腿的对端身份(游标绑的就是它;排障时与停驻行的轴对读):
  * 它已过 {@link memorySyncPeerOf} 的两道判(带凭据的身份起不来);仍过展示铸点({@link buildDisplaySafeUrl}),日志里的 URL 值一律经它 —— 两只判官
  * (引擎的出口脱敏与本仓的展示形状律)不是同一份实现,本仓的那一只若遮了引擎放行的一段,这一行带遮记号而不是逐字(响亮,不漏)。
  */
@@ -41,9 +43,19 @@ export declare function createMemorySyncTransport(opts: {
     /** The one call shape this transport makes (`fetch` itself fits it). */
     fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
 }): MemorySyncTransport;
-/** 一层的游标文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root)下 `sync-cursors/<scope 摘要>.json`。一层一只,不随对端变。
+/** 一层的游标文件路径:引擎根 `memoryEngineDir`(= `RunnerDeps.memoryEngineDir` 的那一个值)下 `sync-cursors/<scope 摘要>.json`。一层一只,不随对端变、不随店变。
  *  落在子目录里:与更早的根下一层文件名 `sync-cursor-<peer>.json` 的空间不相交。 */
-export declare function memorySyncCursorPath(memoryRoot: string, scope: string): string;
+export declare function memorySyncCursorPath(memoryEngineDir: string, scope: string): string;
+/**
+ * ⑦ 停驻层的出路(闭集;今天唯一成员)。`delete_cursor` = 删掉这一层的游标文件,下一轮从空基线重收敛。读面 `memorySync.parked[].wayOut` 与运维行同读这只词;
+ * 加一个词 ⇒ {@link wayOutSentence} 的穷尽 switch 编译红(句子先写好,词才上得了 wire)。
+ */
+export type MemorySyncWayOut = "delete_cursor";
+/** ⑦ 一层停驻的读数(读面与运维行同读这一只记录;不带盘路径 —— 路径只进运维行)。 */
+export interface MemorySyncParkedLayer {
+    readonly scope: string;
+    readonly wayOut: MemorySyncWayOut;
+}
 /** M31 一次的读数(测试按它断言)。`window: "closed"` ⇒ 一行都没读。 */
 export interface SyncCursorRelocationM31Report {
     readonly window: "open" | "closed";
@@ -54,12 +66,12 @@ export interface SyncCursorRelocationM31Report {
  * ⑤ 一次性迁移 M31:把升级前的游标搬到各自那一层的路径(`rename`,字节不变;只搬不改,判归引擎)。`today` = UTC 日历日;窗关 ⇒ 不搬。
  *  · 上一版的分区目录 `sync-cursors/central/<scope 摘要>.json` ⇒ `sync-cursors/<同名>`(两种布局的文件名是同一只 scope 摘要);搬空的目录删掉;
  *    名字不是摘要形的(写游标的 staging 残片)原地不动。
- *  · 更早的 `sync-cursor-central.json` ⇒ 它记的那一层的路径;读不成对象 / 没有 scope ⇒ 原地不动、一行 warn(没法说它是哪一层的基线)。
+ *  · 更早的 `sync-cursor-central.json` ⇒ 它记的那一层的路径;读不成对象 / 没有 scope ⇒ 原地不动、一行 warn(没法说它是哪一层的基线;句子只点名删掉它,⑦ 一出路律)。
  *  · 目标路径上已有游标 ⇒ 不搬、不删,一行 warn(这一层用路径上的那一份;留下的那只没有读者)。
  * 与同一数据根上并跑的另一个进程(server + run-local)同搬:源已被对方搬走(`ENOENT`)⇒ 跳过。残余(如实):先查目标再 `rename` 之间若有写者在目标路径上
  * 落下游标,会被盖掉 —— 写者只有本模块的 runner,而 runner 写任何游标之前先跑完本步。别的读写错 ⇒ 抛(这一轮整轮失败、下一轮再搬)。
  */
-export declare function relocateSyncCursorsM31(memoryRoot: string, log: MemorySyncLog, opts: {
+export declare function relocateSyncCursorsM31(memoryEngineDir: string, log: MemorySyncLog, opts: {
     readonly today: string;
     readonly window?: Pick<OneTimeMigrationWindow, "removableAfter">;
 }): Promise<SyncCursorRelocationM31Report>;
@@ -84,6 +96,8 @@ export interface MemorySyncRunner {
     exclusive<T>(work: () => Promise<T>): Promise<T>;
     /** 某一层的 cursor sidecar 路径(boot 日志/测试可见性)。 */
     cursorPathFor(scope: string): string;
+    /** ⑦ 停驻的层(最近一轮被拒在游标上的那些;按轮序:同步层在前、项目层按键)。停驻事实的唯一读口 —— 读面与运维行读同一份。 */
+    parked(): readonly MemorySyncParkedLayer[];
     /** 排队+在飞的轮数(测试的确定性等待面;0 = 完全空闲)。 */
     pending(): number;
 }
@@ -91,13 +105,13 @@ export interface MemorySyncRunner {
 export declare const MAX_SYNC_ROUNDS = 32;
 /**
  * 组装同步执行器:同步层 `scope` + 同属主的项目层,逐层一轮(cursor 持久化 + core `syncMemoryScope` + conflicts 上报),串行化/节流。
- * `backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` = resolved config root(cursor sidecar 落在 memory/ 目录旁)。
+ * 每一层同步的店由记忆作用域店答(⑥);同步层建时就问(坏的层键 ⇒ 这里抛引擎的 `config.memory_scope_key`,原样)。
  */
 export declare function createMemorySyncRunner(opts: {
-    backend: MemoryBackend;
+    /** 记忆作用域店(本进程那一只):每一层的店问它的 `storeOf`;项目层的发现列它的 `backend`(部署的店本身);游标的根 = 它的 `root`。 */
+    stores: MemoryScopeStores;
     /** 同步层(`config.memorySync.scope`);它同属主的项目层随它一起同步。 */
     scope: string;
-    memoryRoot: string;
     /** 对端 = 它的 `peer`(这一轮的对端只有这一个来源;游标绑的对端由引擎对它判)。 */
     transport: MemorySyncTransport;
     log: MemorySyncLog;
@@ -106,4 +120,15 @@ export declare function createMemorySyncRunner(opts: {
     maxPushEntries?: number;
     maxPullEntries?: number;
 }): MemorySyncRunner;
+/**
+ * 两个入口(HTTP 服务 `boot/stores.ts` 与 `run-local.ts`)起同步执行器的**唯一一处**:建 transport(对端身份在这里铸一次)、建执行器、
+ * 起服日志一行 `memory_sync_enabled`、fire-and-forget 起服那一轮。两处此前各手抄一份同样的装配(上限两键漏过一次);
+ * 店只经入口装配出的那只记忆作用域店取 —— 它的两件事实就是交给 Runner 的那两只,会话把一层放在哪只店由同样的两件事实决定。
+ */
+export declare function startMemorySyncRunner(deps: {
+    sync: NonNullable<ServiceConfig["memorySync"]>;
+    /** 入口装配出的记忆作用域店(= 本入口的记忆引擎对象)。 */
+    stores: MemoryScopeStores;
+    log: MemorySyncLog;
+}): MemorySyncRunner;
 //# sourceMappingURL=memory-sync-client.d.ts.map

package/dist/memory-sync-client.js

@@ -50,13 +50,57 @@ const SYNC_CURSOR_DIR = "sync-cursors";
 function scopeDigest(scope) {
     return createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32);
 }
-export function memorySyncCursorPath(memoryRoot, scope) {
-    return join(memoryRoot, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
+export function memorySyncCursorPath(memoryEngineDir, scope) {
+    return join(memoryEngineDir, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
 }
-function unusableCursor(scope, path, why) {
-    return new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — the cursor file ${path} cannot be read as a sync cursor (${why}); the layer stays unsynced until the operator picks one of two ways out: ` +
-        "(1) restore the file from a backup; (2) delete it to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
-        "and entries deleted on one side since the last round come back from the other side");
+const CURSOR_AXES = { scope: true, peer: true, store: true };
+const CURSOR_FOUND = { absent: true, other: true };
+function wayOutSentence(wayOut, cursorPath) {
+    switch (wayOut) {
+        case "delete_cursor":
+            return (`one way out: delete the cursor file ${cursorPath} — the next round re-converges from an empty baseline: it pulls what the center holds for this layer, ` +
+                "pushes what this store holds and pushes no deletes; entries changed on both sides are reported as conflicts, and an entry deleted on one side since the last round comes back from the other side");
+        default: {
+            const unhandled = wayOut;
+            throw new Error(`memory sync: no sentence for way out ${String(unhandled)}`);
+        }
+    }
+}
+function parkCauseSentence(cause) {
+    switch (cause.kind) {
+        case "cursor_refused":
+            return cause.detail === undefined
+                ? "the sync engine refused its cursor"
+                : `the sync engine refused its cursor on the ${cause.detail.axis} axis (${cause.detail.found === "absent" ? `the cursor has no ${cause.detail.axis} binding` : `the cursor is bound to another ${cause.detail.axis}`})`;
+        case "cursor_unusable":
+            return `the cursor file cannot be read as a sync cursor (${cause.why})`;
+        default: {
+            const unhandled = cause;
+            throw new Error(`memory sync: unknown park cause ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+class MemorySyncLayerParked extends Error {
+    scope;
+    cursorPath;
+    parkCause;
+    wayOut;
+    constructor(scope, cursorPath, parkCause, wayOut = "delete_cursor") {
+        super(`memory sync: layer ${JSON.stringify(scope)} parked — ${parkCauseSentence(parkCause)}; ${wayOutSentence(wayOut, cursorPath)}`);
+        this.scope = scope;
+        this.cursorPath = cursorPath;
+        this.parkCause = parkCause;
+        this.wayOut = wayOut;
+    }
+}
+function cursorRefusalOf(err) {
+    if (err === null || typeof err !== "object" || err.code !== "config.memory_sync_cursor_mismatch")
+        return undefined;
+    const d = err.detail;
+    const axis = d?.axis;
+    const found = d?.found;
+    const known = typeof axis === "string" && Object.hasOwn(CURSOR_AXES, axis) && typeof found === "string" && Object.hasOwn(CURSOR_FOUND, found);
+    return { detail: known ? { axis, found } : undefined };
 }
 function cursorOf(parsed) {
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
@@ -86,11 +130,11 @@ async function loadLayerBaseline(path, scope) {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw unusableCursor(scope, path, "not JSON");
+        throw new MemorySyncLayerParked(scope, path, { kind: "cursor_unusable", why: "not JSON" });
     }
     const cursor = cursorOf(parsed);
     if (typeof cursor === "string")
-        throw unusableCursor(scope, path, cursor);
+        throw new MemorySyncLayerParked(scope, path, { kind: "cursor_unusable", why: cursor });
     return { kind: "cursor", cursor };
 }
 async function saveCursor(path, cursor) {
@@ -120,7 +164,7 @@ function scopeOfLegacyCursor(raw) {
     const scope = parsed["scope"];
     return typeof scope === "string" && scope.length > 0 ? scope : undefined;
 }
-export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
+export async function relocateSyncCursorsM31(memoryEngineDir, log, opts) {
     if (!migrationWindowOpen(opts.window ?? m31Window(), opts.today))
         return { window: "closed", moved: 0, left: 0 };
     let moved = 0;
@@ -155,7 +199,7 @@ export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
         moved += 1;
         log.info("memory_sync_cursor_relocated", { from, to });
     };
-    const legacyDir = join(memoryRoot, SYNC_CURSOR_DIR, LEGACY_PEER_SEGMENT);
+    const legacyDir = join(memoryEngineDir, SYNC_CURSOR_DIR, LEGACY_PEER_SEGMENT);
     let names = [];
     try {
         names = await readdir(legacyDir);
@@ -166,7 +210,7 @@ export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
     }
     for (const name of [...names].sort()) {
         if (/^[0-9a-f]{32}\.json$/.test(name))
-            await move(join(legacyDir, name), join(memoryRoot, SYNC_CURSOR_DIR, name));
+            await move(join(legacyDir, name), join(memoryEngineDir, SYNC_CURSOR_DIR, name));
     }
     if (names.length > 0) {
         try {
@@ -177,7 +221,7 @@ export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
                 throw err;
         }
     }
-    const legacyFile = join(memoryRoot, LEGACY_ROOT_CURSOR_FILE);
+    const legacyFile = join(memoryEngineDir, LEGACY_ROOT_CURSOR_FILE);
     let raw;
     try {
         raw = await readFile(legacyFile, "utf8");
@@ -190,10 +234,10 @@ export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
         const scope = scopeOfLegacyCursor(raw);
         if (scope === undefined) {
             left += 1;
-            log.warn("memory_sync_cursor_not_relocated", { path: legacyFile, note: "a cursor file written by an earlier version that is not a JSON object naming its scope, so no layer can take it as its baseline; restore it from a backup and restart, or delete it" });
+            log.warn("memory_sync_cursor_not_relocated", { path: legacyFile, note: "a cursor file written by an earlier version that is not a JSON object naming its scope, so no layer can take it as its baseline and no round reads it; delete it" });
         }
         else {
-            await move(legacyFile, memorySyncCursorPath(memoryRoot, scope));
+            await move(legacyFile, memorySyncCursorPath(memoryEngineDir, scope));
         }
     }
     return { window: "open", moved, left };
@@ -209,8 +253,11 @@ export function createMemorySyncRunner(opts) {
     const tracked = new Set();
     let enumerationWarned = false;
     const isCoveredProjectLayer = (scope) => scope !== opts.scope && parseProjectLayerKey(scope) !== undefined && replicationCovers(coverage, scope);
+    const storeOf = (scope) => opts.stores.storeOf(scope);
+    const memoryEngineDir = opts.stores.root;
+    storeOf(opts.scope);
     const layersOfRound = () => {
-        const local = enumerateScopes(opts.backend);
+        const local = enumerateScopes(opts.stores.backend);
         if (!local.supported && !enumerationWarned) {
             enumerationWarned = true;
             opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, reason: local.reason, note: "only the sync layer and tracked project layers are synced" });
@@ -219,22 +266,30 @@ export function createMemorySyncRunner(opts) {
         return [opts.scope, ...[...projectLayers].sort()];
     };
     const syncLayer = async (scope, reason) => {
-        const cursorPath = memorySyncCursorPath(opts.memoryRoot, scope);
+        const cursorPath = memorySyncCursorPath(memoryEngineDir, scope);
         const baseline = await loadLayerBaseline(cursorPath, scope);
         let cursor = baseline.kind === "cursor" ? baseline.cursor : undefined;
         let result;
         let subRound = 0;
         for (;;) {
             subRound += 1;
-            result = await syncMemoryScope({
-                backend: opts.backend,
-                scope,
-                transport: opts.transport,
-                ...(cursor !== undefined ? { cursor } : {}),
-                ...(opts.now !== undefined ? { now: opts.now } : {}),
-                ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
-                ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
-            });
+            try {
+                result = await syncMemoryScope({
+                    backend: storeOf(scope),
+                    scope,
+                    transport: opts.transport,
+                    ...(cursor !== undefined ? { cursor } : {}),
+                    ...(opts.now !== undefined ? { now: opts.now } : {}),
+                    ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
+                    ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
+                });
+            }
+            catch (err) {
+                const refusal = cursorRefusalOf(err);
+                if (refusal !== undefined)
+                    throw new MemorySyncLayerParked(scope, cursorPath, { kind: "cursor_refused", detail: refusal.detail });
+                throw err;
+            }
             for (const w of result.warnings ?? [])
                 opts.log.warn("memory_sync_warning", { scope, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
@@ -286,22 +341,32 @@ export function createMemorySyncRunner(opts) {
         return result;
     };
     let relocated = false;
+    let parkedLayers = [];
     const round = async (reason) => {
         if (!relocated) {
-            await relocateSyncCursorsM31(opts.memoryRoot, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
+            await relocateSyncCursorsM31(memoryEngineDir, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
             relocated = true;
         }
         const layers = [];
         const failures = [];
+        const parkedNow = [];
         for (const scope of layersOfRound()) {
             try {
                 layers.push({ scope, result: await syncLayer(scope, reason) });
             }
             catch (err) {
                 failures.push({ scope, err });
-                opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(opts.memoryRoot, scope), err: String(err) });
+                if (err instanceof MemorySyncLayerParked) {
+                    parkedNow.push({ scope, wayOut: err.wayOut });
+                    const refused = err.parkCause.kind === "cursor_refused" ? err.parkCause.detail : undefined;
+                    opts.log.warn("memory_sync_layer_parked", { reason, scope, cursorPath: err.cursorPath, ...(refused !== undefined ? { axis: refused.axis, found: refused.found } : {}), wayOut: err.wayOut, note: err.message });
+                }
+                else {
+                    opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(memoryEngineDir, scope), err: String(err) });
+                }
             }
         }
+        parkedLayers = Object.freeze(parkedNow);
         if (failures.length > 0) {
             throw new Error(`memory sync round failed for ${failures.length} layer(s): ${failures.map((f) => `${f.scope}: ${f.err instanceof Error ? f.err.message : String(f.err)}`).join("; ")}`);
         }
@@ -339,6 +404,21 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, scope), pending: () => pending };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(memoryEngineDir, scope), parked: () => parkedLayers, pending: () => pending };
+}
+export function startMemorySyncRunner(deps) {
+    const { sync } = deps;
+    const transport = createMemorySyncTransport({ url: sync.url, token: sync.token });
+    const runner = createMemorySyncRunner({
+        stores: deps.stores,
+        scope: sync.scope,
+        transport,
+        log: deps.log,
+        ...(sync.maxPushEntries !== undefined ? { maxPushEntries: sync.maxPushEntries } : {}),
+        ...(sync.maxPullEntries !== undefined ? { maxPullEntries: sync.maxPullEntries } : {}),
+    });
+    deps.log.info("memory_sync_enabled", buildMemorySyncEnabledFields(transport.peer, sync.scope, runner.cursorPathFor(sync.scope)));
+    runner.trigger("boot");
+    return runner;
 }
 //# sourceMappingURL=memory-sync-client.js.map