@sema-agent/server 7.141.0 → 7.143.0

package/dist/memory-scope-stores.js

@@ -1,30 +1,63 @@
-import { resolveMemoryScopeStore } from "@sema-agent/core";
+import { createMemoryDeployment, normalizeMemorySpec, resolveMemoryScopeStore, scopePlanesOf } from "@sema-agent/core";
 import { memoryScopeContractOf } from "./memory-scope.js";
+export function backendOwnsControlPlane(backend) {
+    return controlPlaneRootOf(backend) !== undefined;
+}
+export function controlPlaneRootOf(backend) {
+    const root = backend?.controlPlaneRoot;
+    return typeof root === "string" && root !== "" ? root : undefined;
+}
 export function createMemoryScopeStores(input) {
-    const byPlane = new Map();
-    const resolve = (layer, backend) => resolveMemoryScopeStore({
+    let personal;
+    const resolve = (layer) => resolveMemoryScopeStore({
         scope: layer,
         scopeContract: memoryScopeContractOf([layer]),
-        backend,
+        backend: input.backend,
         memoryEngineDir: input.root,
         ...(input.onIncident !== undefined ? { onIncident: input.onIncident } : {}),
     });
+    const planeOf = (layer) => {
+        const contract = memoryScopeContractOf([layer]);
+        let spec;
+        try {
+            spec = normalizeMemorySpec({ scopes: [layer], writeScope: layer, ...(contract !== undefined ? { scopeContract: contract } : {}) });
+        }
+        catch {
+            spec = undefined;
+        }
+        if (spec === undefined || spec.writeScope === null)
+            return resolve(layer).plane;
+        return scopePlanesOf(spec.scopes, spec.writeScope, spec.scopeContract)?.writePlane ?? "project";
+    };
+    let deployment;
     return {
         backend: input.backend,
         root: input.root,
-        namedLayers: input.namedLayers,
+        captureRecords: input.captureRecords,
+        planeOf,
         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);
+            const plane = planeOf(layer);
+            if (plane === "personal" && personal !== undefined)
+                return personal;
+            const store = resolve(layer).backend;
+            if (plane === "personal")
+                personal = store;
             return store;
         },
+        deployment() {
+            if (deployment !== undefined || !backendOwnsControlPlane(input.backend))
+                return deployment;
+            deployment = createMemoryDeployment({
+                backend: input.backend,
+                memoryEngineDir: input.root,
+                scopeContract: "v2",
+                ...(input.onIncident !== undefined ? { onIncident: input.onIncident } : {}),
+                ...(input.captureRecords !== undefined ? { memoryCaptureRecordStore: input.captureRecords } : {}),
+            });
+            return deployment;
+        },
     };
 }
-const PLANE_PROBE = Object.freeze({});
 export class MemoryLayerRefusal extends Error {
     code = "request.memory_layer";
     constructor(message, cause) {
@@ -33,7 +66,7 @@ export class MemoryLayerRefusal extends Error {
     }
 }
 const quoted = (layers) => layers.map((l) => JSON.stringify(l)).join(", ");
-function storeOfNamed(stores, layer, whose, seat) {
+function storeOfNamed(stores, layer) {
     try {
         return stores.storeOf(layer);
     }
@@ -41,16 +74,14 @@ function storeOfNamed(stores, layer, whose, seat) {
         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);
+        throw new MemoryLayerRefusal(`the memory layer ${JSON.stringify(layer)} cannot be read: ${why}`, 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 store = storeOfNamed(stores, layer);
             const group = groups.get(store);
             if (group === undefined)
                 groups.set(store, [layer]);
@@ -62,25 +93,9 @@ export function memoryStoreForRequest(stores, layers, seat = "`scope`") {
         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)
+    const census = stores.deployment()?.stores() ?? [];
+    if (census.length <= 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;
+    throw new MemoryLayerRefusal(`this deployment keeps memory in ${census.length} stores (the project store and the personal store under the memory engine root), so a request that names no layer cannot be told which store it means; name the layer in the request (${seat})`);
 }
 //# sourceMappingURL=memory-scope-stores.js.map

package/dist/memory-scope.d.ts

@@ -28,15 +28,6 @@ export declare function isV2ScopeKey(key: string): boolean;
  * 同步执行器无从同时对上两者),收口点在配置边界(拒或规范化这一形,后者会挪存量记忆的平面),不在本谓词;未闭环。
  */
 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] 就是被这句带偏的)。
  *

package/dist/memory-scope.js

@@ -17,15 +17,6 @@ export function isV2ScopeKey(key) {
 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) {

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

@@ -1,4 +1,4 @@
-import { type MemorySyncClientResult, type MemorySyncTransport } from "@sema-agent/core";
+import { type memorySyncReportOf, 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";
@@ -8,15 +8,9 @@ export interface MemorySyncLog {
     warn(msg: string, fields?: Record<string, unknown>): void;
 }
 /**
- * 中心基址 → 同步对端的身份(规范化基址)。本仓唯一的铸点:`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},
- * 每一轮都会被中心拒)⇒ 同样拒。
+ * 客户端腿的同步地址 `MEMORY_SYNC_URL` → 同步对端的身份(规范化基址)。判与铸只在 `memory-sync-identity.ts` 的唯一铸点({@link readMemorySyncIdentity});
+ * 本函数是那只铸点的「客户端腿」座位:值可以不是规范形(铸成规范形用),有缺陷 ⇒ 抛(拒句不引地址的路径与凭据)。`config.ts` 读 env 时调它拒启(引擎关着也拒),
+ * transport 建时再调它铸身份 —— 同一只纯函数,同一个答案。
  */
 export declare function memorySyncPeerOf(url: string): string;
 /**
@@ -75,20 +69,26 @@ export declare function relocateSyncCursorsM31(memoryEngineDir: string, log: Mem
     readonly today: string;
     readonly window?: Pick<OneTimeMigrationWindow, "removableAfter">;
 }): Promise<SyncCursorRelocationM31Report>;
-/** 一轮里一层的结果。 */
-export interface MemorySyncLayerResult {
-    readonly scope: string;
-    readonly result: MemorySyncClientResult;
-}
-/** 一轮(按层)的结果:成功的各层,按同步序(同步层在前,项目层按键序)。 */
+/**
+ * 一层的一次调用如它落定的那样:`{ scope, result }`(`syncMemoryScope` 兑现)或 `{ scope, thrown }`(它或本服务在这一层上抛的)。
+ * 型**从引擎报告的入参派生**(`memorySyncReportOf` 的 `layers` 元素;引擎没有单独导出这只型)—— 本服务不手抄一份。
+ */
+export type MemorySyncLayerCall = Extract<Parameters<typeof memorySyncReportOf>[0], {
+    readonly layers: unknown;
+}>["layers"][number];
+/** 一轮:这一轮每一层的每一次调用,按跑的顺序(同步层在前、项目层按键;一层续轮 = 多条;一层失败 = 那一层最后一条是 `thrown`)。 */
 export interface MemorySyncRound {
-    readonly layers: readonly MemorySyncLayerResult[];
+    readonly calls: readonly MemorySyncLayerCall[];
 }
 export interface MemorySyncRunner {
-    /** 一轮同步(串行:排在上一轮之后),逐层一轮。任一层 transport/协议错误 ⇒ 其余层照跑,轮末汇总 reject(失败层本地零副作用,
-     *  core 契约);cursor 读写、conflicts warn 都在层内完成。 */
-    syncOnce(reason: string): Promise<MemorySyncRound>;
-    /** fire-and-forget 一轮:上一轮在飞(排队/执行中)则跳过(inflight 节流);失败 warn 不上抛。 */
+    /** 这一腿的对端身份(transport 的 `peer`;会话触发口拿请求点名的目标与它比)。 */
+    readonly peer: string;
+    /** 一轮同步(串行:排在上一轮之后),逐层一轮;**从不 reject**(⑧):一层失败那一层以 `{ scope, thrown }` 收尾、别的层照跑,逐层失败各一行运维 warn。
+     *  `reading`:会话触发的读集 —— 里面被本腿覆盖的项目层并进这一轮(并登记进跟踪表);不被覆盖的层不进轮。 */
+    syncOnce(reason: string, opts?: {
+        readonly reading?: readonly string[];
+    }): Promise<MemorySyncRound>;
+    /** fire-and-forget 一轮:上一轮在飞(排队/执行中)则跳过(inflight 节流)。 */
     trigger(reason: string): void;
     /** 跟踪一只本层属主的项目层(本地还没有条目也每轮拉它);首次跟踪即排一轮。不是本同步腿覆盖的项目层 ⇒ 抛(调用方的错)。 */
     track(scope: string): void;

package/dist/memory-sync-client.js

@@ -4,24 +4,17 @@ import { dirname, join } from "node:path";
 import { carriesCredential, syncMemoryScope, } from "@sema-agent/core";
 import { replicationCovers } from "./memory-scope.js";
 import { parseProjectLayerKey } from "./project-layer-key.js";
-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 { buildMemorySyncIdentityBootRefusal, readMemorySyncIdentity } from "./memory-sync-identity.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { errorText } from "./observability/err-text.js";
 export function memorySyncPeerOf(url) {
-    const refusal = pathBaseUrlRefusal("memory sync: MEMORY_SYNC_URL", url);
-    if (refusal !== undefined)
+    const r = readMemorySyncIdentity(url);
+    if ("flaw" in r) {
+        const refusal = buildMemorySyncIdentityBootRefusal("MEMORY_SYNC_URL", url, r.flaw, "put the token in MEMORY_SYNC_TOKEN and set MEMORY_SYNC_URL to the central base address itself");
         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;
+    return r.identity;
 }
 export function buildMemorySyncEnabledFields(peer, scope, cursorPath) {
     return { peer: buildDisplaySafeUrl(peer), scope, cursorPath };
@@ -53,7 +46,7 @@ function scopeDigest(scope) {
 export function memorySyncCursorPath(memoryEngineDir, scope) {
     return join(memoryEngineDir, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
 }
-const CURSOR_AXES = { scope: true, peer: true, store: true };
+const CURSOR_AXES = { scope: true, peer: true, store: true, incarnation: true };
 const CURSOR_FOUND = { absent: true, other: true };
 function wayOutSentence(wayOut, cursorPath) {
     switch (wayOut) {
@@ -113,7 +106,18 @@ function cursorOf(parsed) {
     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 };
+    const peerIncarnation = c["peerIncarnation"];
+    if (peerIncarnation !== undefined && (typeof peerIncarnation !== "string" || peerIncarnation.trim().length === 0 || carriesCredential(peerIncarnation))) {
+        return "peerIncarnation is not a non-blank string free of credentials";
+    }
+    return {
+        scope: c["scope"],
+        peer: c["peer"],
+        store: c["store"],
+        ...(peerIncarnation !== undefined ? { peerIncarnation } : {}),
+        baseRevs: { ...baseRevs },
+        updatedAtMs,
+    };
 }
 async function loadLayerBaseline(path, scope) {
     let raw;
@@ -123,7 +127,7 @@ async function loadLayerBaseline(path, scope) {
     catch (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`);
+        throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — cannot read the cursor file ${path} (${errorText(err)}); the next round reads it again once it is readable`);
     }
     let parsed;
     try {
@@ -265,7 +269,7 @@ export function createMemorySyncRunner(opts) {
         const projectLayers = new Set([...(local.supported ? local.scopes : []), ...tracked].filter(isCoveredProjectLayer));
         return [opts.scope, ...[...projectLayers].sort()];
     };
-    const syncLayer = async (scope, reason) => {
+    const syncLayer = async (scope, reason, calls) => {
         const cursorPath = memorySyncCursorPath(memoryEngineDir, scope);
         const baseline = await loadLayerBaseline(cursorPath, scope);
         let cursor = baseline.kind === "cursor" ? baseline.cursor : undefined;
@@ -290,6 +294,7 @@ export function createMemorySyncRunner(opts) {
                     throw new MemorySyncLayerParked(scope, cursorPath, { kind: "cursor_refused", detail: refusal.detail });
                 throw err;
             }
+            calls.push({ scope, result });
             for (const w of result.warnings ?? [])
                 opts.log.warn("memory_sync_warning", { scope, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
@@ -303,7 +308,7 @@ export function createMemorySyncRunner(opts) {
                     await saveCursor(cursorPath, result.cursor);
                 }
                 catch (err) {
-                    opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: String(err) });
+                    opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: errorText(err) });
                 }
             }
             cursor = result.cursor ?? cursor;
@@ -324,7 +329,7 @@ export function createMemorySyncRunner(opts) {
                 await saveCursor(cursorPath, result.cursor);
             }
             catch (err) {
-                opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: String(err) });
+                opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: errorText(err) });
             }
         }
         opts.log.info("memory_sync_round", {
@@ -342,35 +347,46 @@ export function createMemorySyncRunner(opts) {
     };
     let relocated = false;
     let parkedLayers = [];
+    const logLayerFailure = (reason, scope, err) => {
+        if (err instanceof MemorySyncLayerParked) {
+            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: errorText(err) });
+        }
+    };
     const round = async (reason) => {
-        if (!relocated) {
-            await relocateSyncCursorsM31(memoryEngineDir, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
-            relocated = true;
+        const calls = [];
+        let layers;
+        try {
+            if (!relocated) {
+                await relocateSyncCursorsM31(memoryEngineDir, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
+                relocated = true;
+            }
+            layers = layersOfRound();
+        }
+        catch (err) {
+            for (const scope of [opts.scope, ...[...tracked].filter(isCoveredProjectLayer).sort()]) {
+                calls.push({ scope, thrown: err });
+                logLayerFailure(reason, scope, err);
+            }
+            return { calls };
         }
-        const layers = [];
-        const failures = [];
         const parkedNow = [];
-        for (const scope of layersOfRound()) {
+        for (const scope of layers) {
             try {
-                layers.push({ scope, result: await syncLayer(scope, reason) });
+                await syncLayer(scope, reason, calls);
             }
             catch (err) {
-                failures.push({ scope, err });
-                if (err instanceof MemorySyncLayerParked) {
+                calls.push({ scope, thrown: 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) });
-                }
+                logLayerFailure(reason, scope, 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("; ")}`);
-        }
-        return { layers };
+        return { calls };
     };
     let chain = Promise.resolve();
     let pending = 0;
@@ -384,11 +400,14 @@ export function createMemorySyncRunner(opts) {
         });
         return run;
     };
-    const syncOnce = (reason) => exclusive(() => round(reason));
+    const syncOnce = (reason, syncOpts) => {
+        for (const scope of syncOpts?.reading ?? [])
+            if (isCoveredProjectLayer(scope))
+                tracked.add(scope);
+        return exclusive(() => round(reason));
+    };
     const queueRound = (reason) => {
-        void syncOnce(reason).catch((err) => {
-            opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, err: String(err) });
-        });
+        void syncOnce(reason);
     };
     const trigger = (reason) => {
         if (pending > 0)
@@ -404,7 +423,7 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(memoryEngineDir, scope), parked: () => parkedLayers, pending: () => pending };
+    return { peer: opts.transport.peer, syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(memoryEngineDir, scope), parked: () => parkedLayers, pending: () => pending };
 }
 export function startMemorySyncRunner(deps) {
     const { sync } = deps;

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

@@ -0,0 +1,24 @@
+/**
+ * 同步身份的拒因词(闭集,判序):形的四词逐字是契约包 `HttpUrlFlaw`;`credential` = 规范化之后带凭据;`too-long` = 装不进中心 `peer` 列;
+ * `not-canonical` = 值本身没缺陷、但不是它自己的规范形(只在「声明的身份」座位出现)。wire 面:`request.field_invalid` 拒体的 `reason`。
+ */
+export declare const MEMORY_SYNC_IDENTITY_FLAWS: readonly ["not-http-url", "userinfo", "query", "fragment", "credential", "too-long", "not-canonical"];
+export type MemorySyncIdentityFlaw = (typeof MEMORY_SYNC_IDENTITY_FLAWS)[number];
+/** 铸点的答:身份,或首个缺陷。 */
+export type MemorySyncIdentityReading = {
+    readonly identity: string;
+} | {
+    readonly flaw: Exclude<MemorySyncIdentityFlaw, "not-canonical">;
+};
+/** 唯一铸点(纯函数)。值 → 规范化身份,或首个缺陷。 */
+export declare function readMemorySyncIdentity(raw: string): MemorySyncIdentityReading;
+/** 「声明的身份」座位(中心声明 / 会话触发的 `target` / 中心入站的 `peer`):值必须**就是**它自己的规范化身份。`undefined` = 合格。 */
+export declare function declaredMemorySyncIdentityFlaw(raw: string): MemorySyncIdentityFlaw | undefined;
+/** 一个拒因词的规则句(穷举;新词不补 = 编译红)。只说规则,不含值。 */
+export declare function memorySyncIdentityRule(flaw: MemorySyncIdentityFlaw): string;
+/**
+ * 起服座位(env 键)的拒句:`memory sync: <键> <规则句>[: <出路>]`。形的四词走 URL 形拒句的铸点(值只到 origin);其余三词值不回显 ——
+ * `not-canonical` 例外地给出**规范形**(它已过凭据判官,是运维要写下的那一串;仍经展示铸点)。
+ */
+export declare function buildMemorySyncIdentityBootRefusal(envKey: string, raw: string, flaw: MemorySyncIdentityFlaw, exit: string): string;
+//# sourceMappingURL=memory-sync-identity.d.ts.map

package/dist/memory-sync-identity.js

@@ -0,0 +1,57 @@
+import { carriesCredential } from "@sema-agent/core";
+import { httpUrlRule, pathBaseUrlFlaws } from "@sema-agent/settings-schema";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
+import { buildHttpUrlRefusal } from "./url-refusal.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export const MEMORY_SYNC_IDENTITY_FLAWS = ["not-http-url", "userinfo", "query", "fragment", "credential", "too-long", "not-canonical"];
+export function readMemorySyncIdentity(raw) {
+    const shape = pathBaseUrlFlaws(raw)[0];
+    if (shape !== undefined)
+        return { flaw: shape };
+    const u = new URL(raw);
+    const identity = `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+    if (carriesCredential(identity))
+        return { flaw: "credential" };
+    if (identity.length > MEMORY_SYNC_PEER_COLUMN_CHARS)
+        return { flaw: "too-long" };
+    return { identity };
+}
+export function declaredMemorySyncIdentityFlaw(raw) {
+    const r = readMemorySyncIdentity(raw);
+    if ("flaw" in r)
+        return r.flaw;
+    return r.identity === raw ? undefined : "not-canonical";
+}
+export function memorySyncIdentityRule(flaw) {
+    switch (flaw) {
+        case "not-http-url":
+        case "userinfo":
+        case "query":
+        case "fragment":
+            return httpUrlRule(flaw);
+        case "credential":
+            return "carries a credential (a token-shaped part of its path) — a sync identity travels verbatim in every request body and cursor and is published on the capability face, so it is refused, never cleaned";
+        case "too-long":
+            return `is longer than ${MEMORY_SYNC_PEER_COLUMN_CHARS} characters once normalized (the central peer column holds at most ${MEMORY_SYNC_PEER_COLUMN_CHARS})`;
+        case "not-canonical":
+            return "is not in canonical form (lower-case scheme and host, no default port, no trailing slash)";
+    }
+}
+export function buildMemorySyncIdentityBootRefusal(envKey, raw, flaw, exit) {
+    switch (flaw) {
+        case "not-http-url":
+        case "userinfo":
+        case "query":
+        case "fragment":
+            return buildHttpUrlRefusal(`memory sync: ${envKey}`, raw, [flaw]);
+        case "credential":
+            return `memory sync: ${envKey} holds a credential — ${memorySyncIdentityRule(flaw)}: ${exit}`;
+        case "too-long":
+            return `memory sync: ${envKey} ${memorySyncIdentityRule(flaw)}: use a shorter base URL`;
+        case "not-canonical": {
+            const r = readMemorySyncIdentity(raw);
+            return `memory sync: ${envKey} ${memorySyncIdentityRule(flaw)} — what is declared is what is published and compared, so it is not normalized for you: set it to ${JSON.stringify("identity" in r ? buildDisplaySafeUrl(r.identity) : "")}`;
+        }
+    }
+}
+//# sourceMappingURL=memory-sync-identity.js.map

package/dist/memory-sync.d.ts

@@ -1,8 +1,13 @@
 import { type MemoryBackend, type MemoryEntry, type PatchReport } from "@sema-agent/core";
 import type { MemorySyncStore } from "./plugins/memory-sync-store-pg.js";
+import { type MemorySyncIdentityFlaw } from "./memory-sync-identity.js";
 /** 一轮同步请求(验型后的干净形状——`parseMemorySyncRequest` 是唯一铸造点)。 */
 export interface MemorySyncRequest {
-    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)= 客户端 transport 的身份(本仓的客户端腿:规范化的中心基址,`memory-sync-client.ts` `memorySyncPeerOf`)。 */
+    /** 主张:客户端游标的 `peerIncarnation` 原样(这份基线是对着本中心哪一份状态取的);缺席 = 没有主张(首轮,或 7.61.0 之前写下的游标)。
+     *  ⓪ 在任何读写之前与分区化身比。 */
+    peerIncarnation?: string;
+    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)= 客户端到达本中心用的同步身份(规范化基址)。验型时已过同步身份的唯一铸点
+     *  (`memory-sync-identity.ts`,「声明的身份」座位:必须已是规范形、不带凭据);路由随后与本中心声明的身份按串比(不等 ⇒ 409,零写)。 */
     peer: string;
     /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;
@@ -35,34 +40,51 @@ export interface MemorySyncResponse {
         id: string;
         baseRev: string;
     }>;
-    /** 本轮落库的新基线(草案偏离②)——客户端应用完 pull 半场后把它持久化为自己的游标。 */
+    /** 本轮落库的新基线(草案偏离②)——客户端应用完 pull 半场后把它持久化为自己的游标。`incarnation` = 答这一轮的分区化身(⓪;
+     *  有主张时恒等于主张),客户端存成游标的 `peerIncarnation`。 */
     cursor: {
         peer: string;
+        incarnation: string;
         baseRevs: Record<string, string>;
         updatedAtMs: number;
     };
     /** S2.5 分批腿:serverEntries 被 pull.limit 截断时为 true(缺席=未截断)。客户端续轮直到缺席。 */
     pullTruncated?: true;
 }
+/** ⓪ 拒答:请求的主张不是本分区的化身,或带非空基线却没有主张 —— 答本分区的化身,什么都没读、什么都没写。路由按 200 原样发(引擎读它成游标拒)。 */
+export interface MemorySyncRefusal {
+    refused: "baseline_incarnation";
+    incarnation: string;
+}
+/** 一轮的答:结果或拒答(两者都是 2xx 体)。 */
+export type MemorySyncAnswer = MemorySyncResponse | MemorySyncRefusal;
 /** 一轮 push 的条目数上限 = core REMOTE_HARVEST_MAX_FILES 同款口径(一个 scope 的文件面上限 500;
  *  同步一轮打满全集也在此内)。deletes 上限同基数放宽(全集删除也要能一轮表达)。 */
 export declare const MEMORY_SYNC_MAX_ENTRIES = 500;
 export declare const MEMORY_SYNC_MAX_DELETES = 2000;
+/** 验型的答:干净形,或体的形错(HTTP 422),或 `peer` 不是声明的同步身份(HTTP 400 `request.field_invalid`,`field: "peer"`,拒因词 = 铸点的闭集,不回显值)。 */
 type ParseResult = {
     ok: true;
     value: MemorySyncRequest;
 } | {
     ok: false;
     error: string;
+} | {
+    ok: false;
+    peerFlaw: MemorySyncIdentityFlaw;
 };
 /** Shape-validate + NORMALIZE the request body (picked-not-spread:只挑认识的字段重建,body 上的
  *  多余键绝不透传进数据面)。`scope` = 路径上已过 owner 门的 scope——每个条目的 scope 必须逐字
  *  等于它(否则一个 owner-gated 路由就成了跨租户写门)。 */
 export declare function parseMemorySyncRequest(body: unknown, scope: string): ParseResult;
+/** ⓪ 栅栏收口:写完之后分区化身已不是开头那一只 —— 分区在这一轮中被重置。路由按 500 答(客户端零本地写)。 */
+export declare class MemorySyncPartitionReset extends Error {
+    constructor(scope: string);
+}
 /**
- * One full sync round for one (scope, peer). `backend` = 中心侧 entry plane(DB 权威),`cursors` =
- * per-(scope,peer) 游标面(sync_cursors)。纯数据参数进(路由已完成鉴权/owner 门/验型),响应形状出。
+ * One full sync round for one (scope, peer). `backend` = 中心侧 entry plane(DB 权威),`sync` = 同步店
+ * (分区化身 + per-(scope,peer) 游标面)。纯数据参数进(路由已完成鉴权/owner 门/验型),答出(结果或 ⓪ 拒答)。
  */
-export declare function performMemorySync(backend: MemoryBackend, cursors: Pick<MemorySyncStore, "putCursor">, scope: string, req: MemorySyncRequest, now?: () => number): Promise<MemorySyncResponse>;
+export declare function performMemorySync(backend: MemoryBackend, sync: Pick<MemorySyncStore, "putCursor" | "partitionIncarnation">, scope: string, req: MemorySyncRequest, now?: () => number): Promise<MemorySyncAnswer>;
 export {};
 //# sourceMappingURL=memory-sync.d.ts.map