@sema-agent/server 7.140.0 → 7.142.0

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,19 +8,13 @@ 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;
 /**
- * 起服日志行 `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 值一律经它 —— 两只判官
  * (引擎的出口脱敏与本仓的展示形状律)不是同一份实现,本仓的那一只若遮了引擎放行的一段,这一行带遮记号而不是逐字(响亮,不漏)。
  */
@@ -46,6 +40,16 @@ export declare function createMemorySyncTransport(opts: {
 /** 一层的游标文件路径:引擎根 `memoryEngineDir`(= `RunnerDeps.memoryEngineDir` 的那一个值)下 `sync-cursors/<scope 摘要>.json`。一层一只,不随对端变、不随店变。
  *  落在子目录里:与更早的根下一层文件名 `sync-cursor-<peer>.json` 的空间不相交。 */
 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";
@@ -56,7 +60,7 @@ 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 写任何游标之前先跑完本步。别的读写错 ⇒ 抛(这一轮整轮失败、下一轮再搬)。
@@ -65,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;
@@ -86,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;
 }

package/dist/memory-sync-client.js

@@ -1,27 +1,20 @@
 import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, readdir, rename, rmdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { carriesCredential, syncMemoryScope, } from "@sema-agent/core";
+import { 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,10 +46,54 @@ function scopeDigest(scope) {
 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))
@@ -79,18 +116,18 @@ 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 {
         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) {
@@ -190,7 +227,7 @@ export async function relocateSyncCursorsM31(memoryEngineDir, 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(memoryEngineDir, scope));
@@ -221,7 +258,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;
@@ -229,15 +266,24 @@ export function createMemorySyncRunner(opts) {
         let subRound = 0;
         for (;;) {
             subRound += 1;
-            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 } : {}),
-            });
+            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;
+            }
+            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))
@@ -251,7 +297,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;
@@ -272,7 +318,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", {
@@ -289,26 +335,47 @@ export function createMemorySyncRunner(opts) {
         return result;
     };
     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 = [];
-        for (const scope of layersOfRound()) {
+        const parkedNow = [];
+        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 });
-                opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(memoryEngineDir, scope), err: String(err) });
+                calls.push({ scope, thrown: err });
+                if (err instanceof MemorySyncLayerParked)
+                    parkedNow.push({ scope, wayOut: err.wayOut });
+                logLayerFailure(reason, scope, err);
             }
         }
-        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 };
+        parkedLayers = Object.freeze(parkedNow);
+        return { calls };
     };
     let chain = Promise.resolve();
     let pending = 0;
@@ -322,11 +389,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)
@@ -342,7 +412,7 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(memoryEngineDir, scope), 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,10 @@
 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`)。 */
+    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)= 客户端到达本中心用的同步身份(规范化基址)。验型时已过同步身份的唯一铸点
+     *  (`memory-sync-identity.ts`,「声明的身份」座位:必须已是规范形、不带凭据);路由随后与本中心声明的身份按串比(不等 ⇒ 409,零写)。 */
     peer: string;
     /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;
@@ -48,12 +50,16 @@ export interface MemorySyncResponse {
  *  同步一轮打满全集也在此内)。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 必须逐字

package/dist/memory-sync.js

@@ -1,6 +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";
+import { declaredMemorySyncIdentityFlaw } from "./memory-sync-identity.js";
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
 export function parseMemorySyncRequest(body, scope) {
@@ -8,8 +8,11 @@ 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 > 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` };
+    if (typeof peer !== "string")
+        return { ok: false, error: "peer must be a string — the sync identity the client reaches this center at" };
+    const peerFlaw = declaredMemorySyncIdentityFlaw(peer);
+    if (peerFlaw !== undefined)
+        return { ok: false, peerFlaw };
     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)" };