@sema-agent/server 7.138.0 → 7.140.0

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

@@ -1,29 +1,70 @@
-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 {
     info(msg: string, fields?: Record<string, unknown>): void;
     warn(msg: string, fields?: Record<string, unknown>): void;
 }
-/** 缺省对端名(core `syncMemoryScope` 同款缺省;cursor 按 (scope,peer) 分区)。 */
-export declare 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 太钝)。
+ * 中心基址 → 同步对端的身份(规范化基址)。本仓唯一的铸点:`config.ts` 读 env 时调它拒启(引擎关着也拒),transport 建时再调它铸身份 —— 同一只纯函数,同一个答案。
+ * 两道判,各归各的属主,本函数不另写规则:
+ *  ① 地址的形 —— 这只地址是「后面要拼路径的基址」座位(post 把同步路径拼在它后面),判官与拒句就是那一座位的那一只({@link pathBaseUrlRefusal}:层级式 http(s),
+ *     不带 userinfo / query / fragment;拒句只点名规则、值只到 origin);
+ *  ② 身份里有没有凭据 —— 判官是引擎包根的 `carriesCredential`(引擎同步客户端判 `transport.peer` 的同一只:任何 userinfo,或同主体出口脱敏会遮掉的任何一段,
+ *     例如路径段里的令牌形),判的就是规范化之后的身份 —— 引擎第一轮判的那个值。身份随每个请求体与落盘游标走,所以带凭据的地址拒而不清洗
+ *     (清洗过的身份是另一个身份;令牌只走 `MEMORY_SYNC_TOKEN`);拒句不引地址的任何部分。
+ * 规范化 = WHATWG URL 的 `origin`(协议与主机小写、缺省端口省掉)+ 路径去尾斜杠;规范化之后装不进中心侧 `peer` 列({@link MEMORY_SYNC_PEER_COLUMN_CHARS},
+ * 每一轮都会被中心拒)⇒ 同样拒。
+ */
+export declare function memorySyncPeerOf(url: string): string;
+/**
+ * 起服日志行 `memory_sync_enabled` 的字段(两处起服 —— `boot/stores.ts` 与 `run-local.ts` —— 同读这一只)。`peer` 是运维改绑游标时要抄的那个值:
+ * 它已过 {@link memorySyncPeerOf} 的两道判(带凭据的身份起不来);仍过展示铸点({@link buildDisplaySafeUrl}),日志里的 URL 值一律经它 —— 两只判官
+ * (引擎的出口脱敏与本仓的展示形状律)不是同一份实现,本仓的那一只若遮了引擎放行的一段,这一行带遮记号而不是逐字(响亮,不漏)。
+ */
+export declare function buildMemorySyncEnabledFields(peer: string, scope: string, cursorPath: string): {
+    readonly peer: string;
+    readonly scope: string;
+    readonly cursorPath: string;
+};
+/**
+ * fetch transport(core `MemorySyncTransport` 的部署实现)。`peer` = {@link memorySyncPeerOf}(`url`)(建时铸一次;拒的地址在这里抛,一个请求都不发),
+ * `post` 打 `${peer}${path}`(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 declare function createMemorySyncTransport(opts: {
     url: string;
     token: string;
     timeoutMs?: number;
-    fetchImpl?: typeof fetch;
+    /** The one call shape this transport makes (`fetch` itself fits it). */
+    fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
 }): MemorySyncTransport;
-/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录旁)下的
- *  per-(peer, scope) sidecar(`sync-cursors/<peer>/<scope 摘要>.json`)。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同);scope 段取 sha256 前 32 hex
- *  (scope 键带 `:` `/` 且可长过段编码的 64 字符帽 —— 名字只需区分,内容里仍记原 scope,读时比对)。 */
-export declare function memorySyncCursorPath(memoryRoot: string, peer: string, scope: string): string;
+/** 一层的游标文件路径:引擎根 `memoryEngineDir`(= `RunnerDeps.memoryEngineDir` 的那一个值)下 `sync-cursors/<scope 摘要>.json`。一层一只,不随对端变、不随店变。
+ *  落在子目录里:与更早的根下一层文件名 `sync-cursor-<peer>.json` 的空间不相交。 */
+export declare function memorySyncCursorPath(memoryEngineDir: string, scope: string): string;
+/** M31 一次的读数(测试按它断言)。`window: "closed"` ⇒ 一行都没读。 */
+export interface SyncCursorRelocationM31Report {
+    readonly window: "open" | "closed";
+    readonly moved: number;
+    readonly left: number;
+}
+/**
+ * ⑤ 一次性迁移 M31:把升级前的游标搬到各自那一层的路径(`rename`,字节不变;只搬不改,判归引擎)。`today` = UTC 日历日;窗关 ⇒ 不搬。
+ *  · 上一版的分区目录 `sync-cursors/central/<scope 摘要>.json` ⇒ `sync-cursors/<同名>`(两种布局的文件名是同一只 scope 摘要);搬空的目录删掉;
+ *    名字不是摘要形的(写游标的 staging 残片)原地不动。
+ *  · 更早的 `sync-cursor-central.json` ⇒ 它记的那一层的路径;读不成对象 / 没有 scope ⇒ 原地不动、一行 warn(没法说它是哪一层的基线)。
+ *  · 目标路径上已有游标 ⇒ 不搬、不删,一行 warn(这一层用路径上的那一份;留下的那只没有读者)。
+ * 与同一数据根上并跑的另一个进程(server + run-local)同搬:源已被对方搬走(`ENOENT`)⇒ 跳过。残余(如实):先查目标再 `rename` 之间若有写者在目标路径上
+ * 落下游标,会被盖掉 —— 写者只有本模块的 runner,而 runner 写任何游标之前先跑完本步。别的读写错 ⇒ 抛(这一轮整轮失败、下一轮再搬)。
+ */
+export declare function relocateSyncCursorsM31(memoryEngineDir: string, log: MemorySyncLog, opts: {
+    readonly today: string;
+    readonly window?: Pick<OneTimeMigrationWindow, "removableAfter">;
+}): Promise<SyncCursorRelocationM31Report>;
 /** 一轮里一层的结果。 */
 export interface MemorySyncLayerResult {
     readonly scope: string;
@@ -52,19 +93,30 @@ 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;
-    peer?: string;
     now?: () => number;
     /** S2.5 分批(core 1.284 两 seam):push 集/pull 集单轮上限。未设=不分批(wire 字节不变)。 */
     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

@@ -1,110 +1,202 @@
 import { createHash, randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rmdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
+import { carriesCredential, syncMemoryScope, } from "@sema-agent/core";
 import { replicationCovers } from "./memory-scope.js";
 import { parseProjectLayerKey } from "./project-layer-key.js";
-const CURSOR_MISMATCH_CODE = "config.memory_sync_cursor_mismatch";
-const CURSOR_PREDATES_STORE_NOTICE = "memory_sync_cursor_predates_store";
-const CURSOR_PREDATES_STORE_OUTS = "this layer's sync baseline was written before sync cursors carried a store binding, so the layer does not sync until the operator picks one of two ways out: " +
-    "(1) run one sync round on the previous server version so deletions made since the last round reach the other side, then delete this file; " +
-    "(2) delete this file now 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";
-export const DEFAULT_MEMORY_SYNC_PEER = "central";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
+import { pathBaseUrlRefusal } from "./web-admin-client/center-request.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export function memorySyncPeerOf(url) {
+    const refusal = pathBaseUrlRefusal("memory sync: MEMORY_SYNC_URL", url);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const u = new URL(url);
+    const identity = `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+    if (carriesCredential(identity)) {
+        throw new Error("memory sync: MEMORY_SYNC_URL holds a credential (a token-shaped part of its path) — the sync peer identity travels verbatim in every request body and " +
+            "cursor, so it is refused, never cleaned: put the token in MEMORY_SYNC_TOKEN and set MEMORY_SYNC_URL to the central base address itself");
+    }
+    if (identity.length > MEMORY_SYNC_PEER_COLUMN_CHARS) {
+        throw new Error(`memory sync: MEMORY_SYNC_URL normalizes to ${identity.length} characters — the peer identity is the central request's peer, which holds at most ${MEMORY_SYNC_PEER_COLUMN_CHARS}: use a shorter base URL`);
+    }
+    return identity;
+}
+export function buildMemorySyncEnabledFields(peer, scope, cursorPath) {
+    return { peer: buildDisplaySafeUrl(peer), scope, cursorPath };
+}
 export function createMemorySyncTransport(opts) {
-    const base = opts.url.replace(/\/+$/, "");
+    const peer = memorySyncPeerOf(opts.url);
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 60_000;
-    return async (path, body) => {
-        const res = await fetchImpl(`${base}${path}`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        const text = await res.text();
-        if (!res.ok)
-            throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
-        return JSON.parse(text);
-    };
+    return Object.freeze({
+        peer,
+        async post(path, body) {
+            const res = await fetchImpl(`${peer}${path}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
+            return JSON.parse(text);
+        },
+    });
+}
+const SYNC_CURSOR_DIR = "sync-cursors";
+function scopeDigest(scope) {
+    return createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32);
 }
-export function memorySyncCursorPath(memoryRoot, peer, scope) {
-    return join(memoryRoot, "sync-cursors", encodeScopeSegment(peer), `${createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32)}.json`);
+export function memorySyncCursorPath(memoryEngineDir, scope) {
+    return join(memoryEngineDir, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
 }
-function perPeerCursorPath(memoryRoot, peer) {
-    return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.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");
 }
-async function readCursorFile(path) {
+function cursorOf(parsed) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return "not a JSON object";
+    const c = parsed;
+    const baseRevs = c["baseRevs"];
+    if (baseRevs === null || typeof baseRevs !== "object" || Array.isArray(baseRevs) || !Object.values(baseRevs).every((v) => typeof v === "string" && v.length > 0)) {
+        return "baseRevs is not a map of entry id to a non-empty rev";
+    }
+    const updatedAtMs = c["updatedAtMs"];
+    if (typeof updatedAtMs !== "number" || !Number.isFinite(updatedAtMs))
+        return "updatedAtMs is not a finite number";
+    return { scope: c["scope"], peer: c["peer"], store: c["store"], baseRevs: { ...baseRevs }, updatedAtMs };
+}
+async function loadLayerBaseline(path, scope) {
     let raw;
     try {
         raw = await readFile(path, "utf8");
     }
     catch (err) {
-        return err.code === "ENOENT" ? { kind: "absent" } : { kind: "unreadable", err: String(err) };
+        if (err.code === "ENOENT")
+            return { kind: "none" };
+        throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — cannot read the cursor file ${path} (${String(err)}); the next round reads it again once it is readable`);
     }
+    let parsed;
     try {
-        const value = JSON.parse(raw);
-        return { kind: "parsed", value };
+        parsed = JSON.parse(raw);
     }
-    catch (err) {
-        return { kind: "corrupt", err: String(err) };
+    catch {
+        throw unusableCursor(scope, path, "not JSON");
     }
+    const cursor = cursorOf(parsed);
+    if (typeof cursor === "string")
+        throw unusableCursor(scope, path, cursor);
+    return { kind: "cursor", cursor };
+}
+async function saveCursor(path, cursor) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+    await writeFile(tmp, JSON.stringify(cursor), "utf8");
+    await rename(tmp, path);
 }
-function predatesStoreBinding(parsed, scope, peer) {
+const LEGACY_PEER_SEGMENT = "central";
+const LEGACY_ROOT_CURSOR_FILE = "sync-cursor-central.json";
+function m31Window() {
+    const row = ONE_TIME_MIGRATIONS.find((w) => w.id === "M31");
+    if (row === undefined)
+        throw new Error("memory-sync-client: the one-time migration registry has no M31 row — this migration outlived its registry row; delete it with that row");
+    return row;
+}
+function scopeOfLegacyCursor(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-        return false;
-    const c = parsed;
-    return c["scope"] === scope && c["peer"] === peer && c["store"] === undefined;
+        return undefined;
+    const scope = parsed["scope"];
+    return typeof scope === "string" && scope.length > 0 ? scope : undefined;
 }
-async function loadLayerBaseline(path, perPeer, scope, peer, log) {
-    const read = await readCursorFile(path);
-    switch (read.kind) {
-        case "absent": {
-            if (perPeer === undefined)
-                return { kind: "none" };
-            const legacy = await readCursorFile(perPeer);
-            return legacy.kind === "parsed" && predatesStoreBinding(legacy.value, scope, peer) ? { kind: "predates-store", path: perPeer } : { kind: "none" };
+export async function relocateSyncCursorsM31(memoryEngineDir, log, opts) {
+    if (!migrationWindowOpen(opts.window ?? m31Window(), opts.today))
+        return { window: "closed", moved: 0, left: 0 };
+    let moved = 0;
+    let left = 0;
+    const codeOf = (err) => err?.code;
+    const exists = async (path) => {
+        try {
+            await stat(path);
+            return true;
         }
-        case "unreadable":
-            log.warn("memory_sync_cursor_read_failed", { path, err: read.err, note: "treating as first round" });
-            return { kind: "none" };
-        case "corrupt":
-            log.warn("memory_sync_cursor_corrupt", { path, err: read.err, note: "treating as first round" });
-            return { kind: "none" };
-        case "parsed": {
-            if (predatesStoreBinding(read.value, scope, peer))
-                return { kind: "predates-store", path };
-            const cursor = cursorOf(read.value, scope, peer);
-            if (cursor !== undefined)
-                return { kind: "cursor", cursor };
-            log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
-            return { kind: "none" };
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return false;
+            throw err;
+        }
+    };
+    const move = async (from, to) => {
+        if (await exists(to)) {
+            left += 1;
+            log.warn("memory_sync_cursor_not_relocated", { path: from, to, note: "this layer already has a cursor at its path, so the file written by an earlier version stays where it is and no round reads it; delete it" });
+            return;
+        }
+        await mkdir(dirname(to), { recursive: true });
+        try {
+            await rename(from, to);
         }
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return;
+            throw err;
+        }
+        moved += 1;
+        log.info("memory_sync_cursor_relocated", { from, to });
+    };
+    const legacyDir = join(memoryEngineDir, SYNC_CURSOR_DIR, LEGACY_PEER_SEGMENT);
+    let names = [];
+    try {
+        names = await readdir(legacyDir);
     }
-}
-function cursorOf(parsed, scope, peer) {
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-        const c = parsed;
-        const baseRevsRaw = c["baseRevs"];
-        if (c["scope"] === scope &&
-            c["peer"] === peer &&
-            typeof c["store"] === "string" &&
-            typeof c["updatedAtMs"] === "number" &&
-            Number.isFinite(c["updatedAtMs"]) &&
-            baseRevsRaw !== null &&
-            typeof baseRevsRaw === "object" &&
-            !Array.isArray(baseRevsRaw) &&
-            Object.values(baseRevsRaw).every((v) => typeof v === "string" && v.length > 0)) {
-            return { scope, peer, store: c["store"], baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    for (const name of [...names].sort()) {
+        if (/^[0-9a-f]{32}\.json$/.test(name))
+            await move(join(legacyDir, name), join(memoryEngineDir, SYNC_CURSOR_DIR, name));
+    }
+    if (names.length > 0) {
+        try {
+            await rmdir(legacyDir);
+        }
+        catch (err) {
+            if (codeOf(err) !== "ENOENT" && codeOf(err) !== "ENOTEMPTY" && codeOf(err) !== "EEXIST")
+                throw err;
         }
     }
-    return undefined;
-}
-async function saveCursor(path, cursor) {
-    await mkdir(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
-    await writeFile(tmp, JSON.stringify(cursor), "utf8");
-    await rename(tmp, path);
+    const legacyFile = join(memoryEngineDir, LEGACY_ROOT_CURSOR_FILE);
+    let raw;
+    try {
+        raw = await readFile(legacyFile, "utf8");
+    }
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    if (raw !== undefined) {
+        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" });
+        }
+        else {
+            await move(legacyFile, memorySyncCursorPath(memoryEngineDir, scope));
+        }
+    }
+    return { window: "open", moved, left };
 }
 export const MAX_SYNC_ROUNDS = 32;
 function enumerateScopes(backend) {
@@ -112,58 +204,46 @@ function enumerateScopes(backend) {
     return typeof face === "function" ? face.call(backend) : { supported: false, reason: "the memory backend has no listScopes face" };
 }
 export function createMemorySyncRunner(opts) {
-    const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
+    const now = opts.now ?? Date.now;
     const coverage = { kind: "layers", layers: [opts.scope] };
     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, peer, reason: local.reason, note: "only the sync layer and tracked project layers are synced" });
+            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" });
         }
         const projectLayers = new Set([...(local.supported ? local.scopes : []), ...tracked].filter(isCoveredProjectLayer));
         return [opts.scope, ...[...projectLayers].sort()];
     };
     const syncLayer = async (scope, reason) => {
-        const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer, scope);
-        const baseline = await loadLayerBaseline(cursorPath, scope === opts.scope ? perPeerCursorPath(opts.memoryRoot, peer) : undefined, scope, peer, opts.log);
-        if (baseline.kind === "predates-store") {
-            opts.log.warn(CURSOR_PREDATES_STORE_NOTICE, { scope, peer, path: baseline.path, note: CURSOR_PREDATES_STORE_OUTS });
-            throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — its baseline ${baseline.path} predates the store binding (see warn ${CURSOR_PREDATES_STORE_NOTICE})`);
-        }
+        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;
-            try {
-                result = await syncMemoryScope({
-                    backend: opts.backend,
-                    scope,
-                    transport: opts.transport,
-                    peer,
-                    ...(cursor !== undefined ? { cursor } : {}),
-                    ...(opts.now !== undefined ? { now: opts.now } : {}),
-                    ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
-                    ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
-                });
-            }
-            catch (err) {
-                if (cursor === undefined || err?.code !== CURSOR_MISMATCH_CODE)
-                    throw err;
-                opts.log.warn("memory_sync_cursor_rebound", { scope, peer, subRound, note: "the persisted cursor is bound to another store — running this round from no cursor and replacing it" });
-                cursor = undefined;
-                subRound -= 1;
-                continue;
-            }
+            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 } : {}),
+            });
             for (const w of result.warnings ?? [])
-                opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
+                opts.log.warn("memory_sync_warning", { scope, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
                 break;
             if (subRound >= MAX_SYNC_ROUNDS) {
-                opts.log.warn("memory_sync_rounds_exhausted", { scope, peer, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
+                opts.log.warn("memory_sync_rounds_exhausted", { scope, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
                 break;
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
@@ -175,12 +255,11 @@ export function createMemorySyncRunner(opts) {
                 }
             }
             cursor = result.cursor ?? cursor;
-            opts.log.info("memory_sync_continuation", { reason, scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
+            opts.log.info("memory_sync_continuation", { reason, scope, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
                 scope,
-                peer,
                 side: c.side,
                 id: c.id,
                 reason: c.reason,
@@ -199,7 +278,6 @@ export function createMemorySyncRunner(opts) {
         opts.log.info("memory_sync_round", {
             reason,
             scope,
-            peer,
             ok: result.ok,
             cursorAdvanced: result.cursorAdvanced,
             pushedEntries: result.pushed.entries.length,
@@ -210,7 +288,12 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
+    let relocated = false;
     const round = async (reason) => {
+        if (!relocated) {
+            await relocateSyncCursorsM31(memoryEngineDir, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
+            relocated = true;
+        }
         const layers = [];
         const failures = [];
         for (const scope of layersOfRound()) {
@@ -219,7 +302,7 @@ export function createMemorySyncRunner(opts) {
             }
             catch (err) {
                 failures.push({ scope, err });
-                opts.log.warn("memory_sync_layer_failed", { reason, scope, peer, err: String(err) });
+                opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(memoryEngineDir, scope), err: String(err) });
             }
         }
         if (failures.length > 0) {
@@ -242,7 +325,7 @@ export function createMemorySyncRunner(opts) {
     const syncOnce = (reason) => exclusive(() => round(reason));
     const queueRound = (reason) => {
         void syncOnce(reason).catch((err) => {
-            opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, peer, err: String(err) });
+            opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, err: String(err) });
         });
     };
     const trigger = (reason) => {
@@ -259,6 +342,21 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, peer, scope), pending: () => pending };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(memoryEngineDir, scope), 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

package/dist/memory-sync.d.ts

@@ -2,7 +2,7 @@ import { type MemoryBackend, type MemoryEntry, type PatchReport } from "@sema-ag
 import type { MemorySyncStore } from "./plugins/memory-sync-store-pg.js";
 /** 一轮同步请求(验型后的干净形状——`parseMemorySyncRequest` 是唯一铸造点)。 */
 export interface MemorySyncRequest {
-    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)。 */
+    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)= 客户端 transport 的身份(本仓的客户端腿:规范化的中心基址,`memory-sync-client.ts` `memorySyncPeerOf`)。 */
     peer: string;
     /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;

package/dist/memory-sync.js

@@ -1,5 +1,6 @@
 import { computeEntryRev, MEMORY_ORIGIN_CAUSES, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
 export function parseMemorySyncRequest(body, scope) {
@@ -7,8 +8,8 @@ export function parseMemorySyncRequest(body, scope) {
         return { ok: false, error: "body must be a JSON object { peer, baseRevs, entries, deletes }" };
     const b = body;
     const peer = b["peer"];
-    if (typeof peer !== "string" || peer.length === 0 || peer.length > 190)
-        return { ok: false, error: "peer must be a non-empty string of at most 190 characters" };
+    if (typeof peer !== "string" || peer.length === 0 || peer.length > MEMORY_SYNC_PEER_COLUMN_CHARS)
+        return { ok: false, error: `peer must be a non-empty string of at most ${MEMORY_SYNC_PEER_COLUMN_CHARS} characters` };
     const rawBase = b["baseRevs"];
     if (rawBase === null || typeof rawBase !== "object" || Array.isArray(rawBase))
         return { ok: false, error: "baseRevs must be an object mapping entry id → rev (may be empty on the first round)" };

package/dist/observability/cost-taxonomy.d.ts

@@ -10,8 +10,8 @@
  * batch; stacking a second wide-fanout move on it in one session was the higher-risk option for no added
  * clarity.)
  *
- * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / memoryConsolidation
- * / compaction). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
+ * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / compaction, plus the
+ * suggestions and side-call lines). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
  * the service owns the data + rates for. This module is the thin report layer: it turns a
  * per-run infra USAGE + the deployment's RATES into an infra breakdown, then composes it with the core LLM
  * breakdown into one supervisor-facing total. Pure + rate-driven (rates default 0 ⇒ infra reads $0, exactly like