@sema-agent/server 7.141.0 → 7.142.0

package/dist/http/server.d.ts

@@ -464,7 +464,8 @@ export interface ServiceSeamDeps {
     }>;
     /** 142-S5 §1.4: per-scope memory export reader (main.ts wires `exportMemoryScope` over the DB memory
      *  backend). Enables GET /v1/memory/export — present ONLY on a DB memory plane (MEMORY_ENGINE_BACKEND=
-     *  pg|mysql); absent / file posture ⇒ 501 (single-user file memory exports by copying the memory dir). */
+     *  pg|mysql); absent ⇒ 501 (single-user file memory exports by copying the memory dir). The gate and the capability bit
+     *  `memoryExport` read ONE fact (`capability-facts.ts` `memoryExport`) — whether this face is wired, never the backend name. */
     memoryExport?: (scope: string) => Promise<MemoryEntry[]>;
     /**
      * [ref](core 5.57.0 `routePairingStatus`)—— **key↔URL 配对读面**:`GET /v1/models` 每行的
@@ -480,8 +481,10 @@ export interface ServiceSeamDeps {
     /** 142-S2.5(设计 §2.5;裁定 plan 随数据走,core 零运行时半场):one full sync round for one
      *  (scope, peer) — main.ts wires `performMemorySync` over the DB memory backend + the sync-cursor
      *  store. Enables POST /v1/memory/sync/:scope — present ONLY on a DB memory plane
-     *  (MEMORY_ENGINE_BACKEND=pg|mysql); absent / file posture ⇒ 501 honestly (a single-user file plane
-     *  IS the TOC side of a sync — it has no central-authority half to serve). */
+     *  (MEMORY_ENGINE_BACKEND=pg|mysql); absent ⇒ 501 honestly (a single-user file plane
+     *  IS the TOC side of a sync — it has no central-authority half to serve). [ref]: the face also needs the center's
+     *  declared sync identity (`config.memorySyncServeIdentity`) — the gate and the capability bit `memorySyncServe` read ONE
+     *  fact (`capability-facts.ts` `memorySyncServe`). */
     memorySync?: (scope: string, syncReq: MemorySyncRequest) => Promise<MemorySyncResponse>;
     /** [ref] v2-c(core 5.40.0 `MemoryEngine.exportMemoryScopes`):治理完备包的**携出**面。main.ts 把它接到
      *  装配好的 memory engine 上。启用 `POST /v1/memory/export`(operator-only)。
@@ -538,8 +541,10 @@ export interface ServiceSeamDeps {
      * [ref] —— 本**部署**的记忆同步腿(客户端半场):`MEMORY_SYNC_URL` 设了且 file 记忆引擎亮着、执行器起了才在场(`boot/stores.ts`)。
      * `GET /v1/sessions/:id/memory-status` 的 `memorySync` 格只读它的 `parked()` —— 停驻事实的唯一读口(写者 = 执行器的轮,运维行 `memory_sync_layer_parked` 读同一份);
      * 缺席 ⇒ 那一格缺席(没有同步腿)。与 `memoryAutoConsolidationArmed` 同类:部署事实,不随会话、不随层座。
+     * [ref]:会话记忆同步触发口(`POST /v1/sessions/:id/memory/sync`)读它的 `peer`(目标比对)与 `syncOnce`(一轮,交回每层每次调用;从不 reject)——
+     * 能力事实 `sessionMemorySync` 的第一格就是它在不在。
      */
-    memorySyncLeg?: Pick<MemorySyncRunner, "parked">;
+    memorySyncLeg?: Pick<MemorySyncRunner, "parked" | "peer" | "syncOnce">;
     /**
      * [ref] / [ref] + 车PI 修复轮 ④ —— 记忆整理阀门的**生效判决**(boot 第 4 段 `createConsolidationValve`:显式词,或出厂缺省按
      * 装配结果派生)。配置目录那一行(`GET /v1/config/catalog` 的 `MEMORY_CONSOLIDATION_DRIVER` `effectiveValue`)读它 —— 那一列的契约是
@@ -698,10 +703,11 @@ export interface ServiceDeploymentDeps {
     /** [ref] ②:caps `centerWiring` 的读面(`capabilities/center-wiring.ts` `createCenterWiringReader`;入参 = 请求的已验 principal)。
      *  缺席 = 没接中心(或测试夹具)⇒ 键整个缺席。 */
     centerWiring?: (principal: string | undefined) => import("../capabilities/center-wiring.js").CenterWiring;
-    /** The member git-credential plane's one reading (`sandbox-git-plane.ts`; stage 5 computes it once — config premises + the boot's secret
-     *  seat answer + the static patch judge). Caps `credentialPlane.sandboxGit` projects it as is. Absent = not built by the composition root
-     *  (a fixture) ⇒ the same judge on config alone, the seat counted as not asked. */
-    sandboxGitPlane?: import("../sandbox-git-plane.js").SandboxGitPlane;
+    /** The member git-credential plane's read function (`sandbox-git-plane.ts` `createSandboxGitPlaneSeat`'s `now`: the judge over the boot readings — the
+     *  secret seat answer stage 5 settles, the static patch judge — and the live config, whose `sandboxGit` block hot-swaps with each effective-config commit).
+     *  Caps `credentialPlane.sandboxGit` calls it on every read and projects the answer as is. Absent = not built by the composition root (a fixture) ⇒
+     *  the same judge on config alone, the seat counted as not asked. */
+    sandboxGitPlane?: () => import("../sandbox-git-plane.js").SandboxGitPlane;
     /**
      * 本进程起服装上的**运维声明** mod 包数(部署座装配口 `assembleDeploymentMods` 的 `loaded.length`;本服务自铸的注册不算)。一个事实两个出口,同读这一格:
      * `/health` 的 `mods: { deploymentPackages }` 与 `/v1/capabilities` 的 `modsDeploymentPackages: true` —— 都只在 > 0 时在场;0 / 缺席(没声明,或不是由

package/dist/http/server.js

@@ -18,7 +18,7 @@ import { cascadeConfig } from "./run-meta.js";
 export { cascadeConfig };
 import { coarseStatusForState, errorCodeForExit } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
-import { sendError, sendHttpError, sendSessionError, logRequestError } from "./send.js";
+import { sendError, sendHttpError, sendOpenFaceFault, logRequestError } from "./send.js";
 import { createRequestGuards } from "./request-guards.js";
 import { sqlEngineSeatIssue } from "../sql-engine-posture.js";
 import { parkDecisionStoreRefusal } from "../orchestration/workflow-park-decision.js";
@@ -169,13 +169,11 @@ export function createHttpServer(rawDeps) {
                 res.end();
                 return;
             }
-            if (sendSessionError(res, err, "open"))
-                return;
             if (err instanceof SessionForkInProgressError) {
                 sendError(res, 409, err.code, err.message);
                 return;
             }
-            sendError(res, 500, "internal.error", "internal error");
+            sendOpenFaceFault(res, err);
         });
     });
     const deviceLane = facts.deviceLane(deps);

package/dist/http/submit-replay.d.ts

@@ -18,9 +18,10 @@
  *
  * ## 回执两形(按提交腿)
  *  · `durable`(`POST /v1/runs`、A2A `message/send`)—— `202 { taskId, sessionId, status }`(这条腿首答的既有形);
- *  · `sync`(`POST /v1/tasks`;`/v1/tasks/stream` 把同一份体放进 `done.result`)—— `200 { …run 行读面, replay: true }`
- *    (读面 = `GET /v1/runs/:id` 的 200 体,同一只投影口 `readRunFace`)。同步腿的首答是引擎结果,而重放时手里只有行;
- *    `replay: true` 是这一形的判别位。
+ *  · `sync`(`POST /v1/tasks`;`/v1/tasks/stream` 把同一份体放进 `done.result`)—— `200 { …首答的信封, replay: true }`:
+ *    首答的信封由 `http/sync-submit-body.ts` 铸(`buildSyncSubmitBody`),重放经同文件的 `syncSubmitBodyOfRow` 读行 ——
+ *    终局 / 停驻行上有结果 ⇒ 与首答同形(结果的键在顶层,`result` 是串);行上没有结果可交(首投还在跑)⇒ 轮询回执 `{ taskId, sessionId, status }`。
+ *    `replay: true` 是重放的判别位(本函数叠上,不在信封里)。
  */
 import type { RunIdemBinding, RunRecord } from "../plugins/store-contracts.js";
 import type { RunStore } from "../plugins/store-backend.js";

package/dist/http/submit-replay.js

@@ -1,5 +1,5 @@
 import { runRowReadable } from "./owner-access.js";
-import { readRunFace } from "./run-read-face.js";
+import { syncSubmitBodyOfRow } from "./sync-submit-body.js";
 import { refusalBody } from "./refusal-body.js";
 export function isRunExistsConflictBody(body) {
     return typeof body === "object" && body !== null && body.errorCode === "conflict.run_exists";
@@ -19,7 +19,7 @@ export async function replayOfExistingRun(row, caller, face, deps, runStore) {
         case "durable":
             return { status: 202, body: { taskId: row.taskId, sessionId: row.sessionId, status: row.status } };
         case "sync":
-            return { status: 200, body: { ...(await readRunFace(deps, runStore, row)), replay: true } };
+            return { status: 200, body: { ...syncSubmitBodyOfRow(deps, row), replay: true } };
         default: {
             const unknown = face;
             throw new Error(`replayOfExistingRun: unknown submit face ${String(unknown)}`);

package/dist/http/sync-submit-body.d.ts

@@ -25,14 +25,19 @@
  * (`observability/run-terminal.ts`),调用方铸一次交进来;本函数只负责「体长什么样」。凭据(`paused.token` /
  * `failed.nestedPause.token`)因此在进本函数之前就已摘掉,幂等缓存存的正是本函数的产物,重放体同体同脱。
  */
-import type { ParkedRunStatus, PersistedTaskResult } from "../plugins/store-contracts.js";
-/** park 中的 run 在同步 200 体上带的 poll 回执三键(修前 park 体的全部内容,值逐字不变)。 */
-export interface SyncParkReceipt {
+import { type ParkedRunStatus, type PersistedTaskResult, type RunRecord } from "../plugins/store-contracts.js";
+import { type RunFaceDeps } from "./run-read-face.js";
+/** 同步 200 体上的 poll 回执三键:一条 run 的 poll 键、会话、对外词。park 体叠在结果之上带它({@link SyncParkReceipt});重放命中一条还没有结果可交的行时,它**就是**整个体({@link syncSubmitBodyOfRow})。 */
+export interface SyncRunReceipt {
     /** 同步腿提交时铸的 durable run id —— `GET /v1/runs/:taskId` 的 poll 键。 */
     taskId: string;
     /** 提交的会话。 */
     sessionId: string;
-    /** 对外词 = `GET /v1/runs/:id` 行上的 `status`(park 两词之一,闭集从 `RUN_STATUS_CLASS` 派生)。 */
+    /** 对外词 = `GET /v1/runs/:id` 行上的 `status`。 */
+    status: RunRecord["status"];
+}
+/** park 中的 run 在同步 200 体上带的 poll 回执三键(修前 park 体的全部内容,值逐字不变);`status` 是 park 两词之一(闭集从 `RUN_STATUS_CLASS` 派生)。 */
+export interface SyncParkReceipt extends SyncRunReceipt {
     status: ParkedRunStatus;
 }
 /**
@@ -40,4 +45,16 @@ export interface SyncParkReceipt {
  * 返回的是纯数据(无方法、无闭包)⇒ `build*`。
  */
 export declare function buildSyncSubmitBody<R extends PersistedTaskResult>(exitResult: R, parkReceipt?: SyncParkReceipt): R | (R & SyncParkReceipt);
+/**
+ * **同键重放读行的出口** —— 同一条 run 的同步 200 体,首答与重放读**同一只信封**:终局行 / 停驻行上有结果 ⇒ 经 {@link buildSyncSubmitBody} 铸
+ * (终局 = 结果本身;停驻 = 结果 + 回执三键),与首答的三个 200 出口逐字同形 —— 首答恒 = 「出口封口 + 脱敏后的引擎结果」,那份对象就是落在行上的那一份
+ * (调用方铸一次、既落行又进体),重放读到的是它被读入口(同一只 {@link runRowExitResult},`GET /v1/runs/:id` 的 `result` 读的也是它)再封再脱的样子。
+ * 行上没有结果可交(首投还在跑、在别的副本上没落定;或终局行的结果已被收割清空)⇒ 首答在这一刻**不存在**,体只剩 {@link SyncRunReceipt} 三键 —— 去 `GET /v1/runs/:taskId` 轮询,
+ * 不把「读面」塞进同步体里充首答(失联折叠与读面同一只判据 {@link runRowStale}:折成 `failed`)。
+ *
+ * 首答体上另有两类**本次请求**的附注(`notice` / `warnings`,见 `routes/tasks.ts` 的 `withSyncSubmitKeys`):重放在 `prepareSpec` 之前就答了,
+ * 结构上不知道本次请求带没带 verify / cascade、放行侧选择器里有没有空条目 ⇒ 重放体没有它们。判别位 `replay: true` 由重放出口(`submit-replay.ts`)叠上,不在信封里。
+ * 纯数据 ⇒ `build*` 的近亲;名字取 `…OfRow`(行 → 体的读法),与 `buildSyncSubmitBody` 同文件同铸点。
+ */
+export declare function syncSubmitBodyOfRow(deps: RunFaceDeps, row: RunRecord): ReturnType<typeof buildSyncSubmitBody> | SyncRunReceipt;
 //# sourceMappingURL=sync-submit-body.d.ts.map

package/dist/http/sync-submit-body.js

@@ -1,4 +1,17 @@
+import { isParkedRunStatus, isTerminalRunStatus } from "../plugins/store-contracts.js";
+import { runRowExitResult, runRowStale } from "./run-read-face.js";
 export function buildSyncSubmitBody(exitResult, parkReceipt) {
     return parkReceipt === undefined ? exitResult : { ...exitResult, ...parkReceipt };
 }
+export function syncSubmitBodyOfRow(deps, row) {
+    const stale = runRowStale(deps, row);
+    const exit = stale ? undefined : runRowExitResult(row);
+    if (exit !== undefined) {
+        if (isTerminalRunStatus(row.status))
+            return buildSyncSubmitBody(exit);
+        if (isParkedRunStatus(row.status))
+            return buildSyncSubmitBody(exit, { taskId: row.taskId, sessionId: row.sessionId, status: row.status });
+    }
+    return { taskId: row.taskId, sessionId: row.sessionId, status: stale ? "failed" : row.status };
+}
 //# sourceMappingURL=sync-submit-body.js.map

package/dist/identity-source.d.ts

@@ -12,9 +12,13 @@
  * 3. **缺席一种读法**:`null` = 这一行**没有「属主在受理时验过的凭据」的记录** —— 三列存在之前写下的行、没有任何验过凭据的受理(无鉴权写面
  *    `ALLOW_UNAUTHED_WRITES`)、以及别人替属主按下的那一跑(受理请求验过的主体不是这一行的属主:唤醒 / 决定投递铸的新一跑)。读者一律按「不合格」处置
  *    (fail-closed),不分辨三种成因;存量行不回填(没有事实可回填)。
+ * 4. **令牌声明装不进它的列就不记**(不截断:截断 = 两个不同的值折成一个):`sso` 臂从验过的令牌铸元组时,某一格装不进它的列宽({@link RUN_IDENTITY_CLAIM_COLUMNS})
+ *    ⇒ 那一格「未记录」—— 可空的格(化身号)记 `null`;必填的格(scope)装不下就铸不出合形元组 ⇒ 无元组。两格结果不同来自元组的型,不是两条规则:
+ *    同一只判({@link runIdentityClaimOverflow})、同一行告警 `run_identity_claim_unrecorded { claim, chars, max }`(凭据门的铸点发;只名与长度,不带值)。
  *
- * 化身号 `principalInc`:令牌 `sub_inc` 声明原样,经契约包 `VerifiedIdentity.principalInc` 读(settings-schema 14.7.0 加的可选字段,已提货:验证腿随身份带出);本版接线未做 ⇒ 恒 `null`,
- * 接线点在 `admitRunIdentity` 的 `sso` 臂(不在本仓另定一份读法)。
+ * 化身号 `principalInc`:令牌 `sub_inc` 声明原样(契约包 `VerifiedIdentity.principalInc`)。来源链只有一条 —— 验证器读出 → 注入边界再判形(`auth-bridge.ts` 的
+ * `admitBridgeIdentity`)→ 入口预认证挂 request-local(`security.ts` 的 `setSsoPrincipalInc`)→ 凭据门 `admitRunIdentity` 的 `sso` 臂铸进元组(律 4)→ 建行原样写入。
+ * `null` 化身号只有一种读法:**未记录**(契约 §12.8「缺 ⇒ 化身号未记录」)—— 存量行、令牌没带、装不下,三种成因同一读法。
  */
 /** 验过的身份来源的**闭集**(序 = 判定次序 = `/health.auth.kinds` 的出现序;加一个来源 = 加一个词,读它的各只穷举 `switch` 不接就编译红)。 */
 export declare const IDENTITY_SOURCES: readonly ["service_token", "sso", "direct_door_jwt"];
@@ -36,6 +40,21 @@ export type RunIdentity = {
 export declare const RUN_IDENTITY_SCOPE_MAX_CHARS = 190;
 /** `identity_principal_inc` 的列宽(字符):化身号是签发方插入时铸的不透明随机串(与会话化身同宽)。 */
 export declare const RUN_IDENTITY_PRINCIPAL_INC_MAX_CHARS = 64;
+/** 令牌声明 → 它落的那一列的列宽(字符;律 4 的判读这一张)。 */
+export declare const RUN_IDENTITY_CLAIM_COLUMNS: {
+    readonly scope: 190;
+    readonly principalInc: 64;
+};
+export type RunIdentityClaim = keyof typeof RUN_IDENTITY_CLAIM_COLUMNS;
+/**
+ * 律 4 的判:这一格令牌声明装不装得进它的列(按码点数,与两方言 VARCHAR 同口径)。装得下 ⇒ `undefined`;装不下 ⇒ 告警行 `run_identity_claim_unrecorded` 的载荷
+ * (`claim` 名 + 码点数 + 列宽,不带值)。调用方按格的型处置:可空格记 `null`,必填格无元组。
+ */
+export declare function runIdentityClaimOverflow(claim: RunIdentityClaim, value: string): {
+    readonly claim: RunIdentityClaim;
+    readonly chars: number;
+    readonly max: number;
+} | undefined;
 /**
  * `task_run` 三列的列定义 —— 两方言各一段,**唯一属主**:中央建表语句(`tidb-pool.ts` / `pg-pool.ts` 的 `CREATE TABLE task_run`)内插这同一段;
  * 存量库缺列时起服列册对账(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE task_run ADD COLUMN …` 由同一份建表语句解析生成 ⇒

package/dist/identity-source.js

@@ -1,6 +1,12 @@
 export const IDENTITY_SOURCES = ["service_token", "sso", "direct_door_jwt"];
 export const RUN_IDENTITY_SCOPE_MAX_CHARS = 190;
 export const RUN_IDENTITY_PRINCIPAL_INC_MAX_CHARS = 64;
+export const RUN_IDENTITY_CLAIM_COLUMNS = { scope: RUN_IDENTITY_SCOPE_MAX_CHARS, principalInc: RUN_IDENTITY_PRINCIPAL_INC_MAX_CHARS };
+export function runIdentityClaimOverflow(claim, value) {
+    const chars = [...value].length;
+    const max = RUN_IDENTITY_CLAIM_COLUMNS[claim];
+    return chars > max ? { claim, chars, max } : undefined;
+}
 export const RUN_IDENTITY_COLUMNS = {
     mysql: [
         "identity_source VARCHAR(32) NULL",

package/dist/memory-incident-sink.d.ts

@@ -14,14 +14,17 @@
  * consolidation),run-local 腿把整族印成 `engine_error` 并用 `String(err)` 抹掉 `err.code`。
  *
  * ## 形(一处定义,四处引用)
- * `memory_engine_incident` + `{ sessionId?, code, detail }`,并计 `memory_engine_incident_total{code}`。
+ * `memory_engine_incident` + `{ sessionId?, code?, detail }`,并计 `memory_engine_incident_total{code?}`。
  * 🔴 `code` 是**结构化字段**而不是被折进散文:它是运维唯一能按名告警的那一位,而这一族里最要紧的几条
- * (一次性布局搬家、无主根内容、控制面写失败)一辈子只发生一次 —— 折平就等于没说。无码的成员
- * (core 里有大量不带 `.code` 的记忆相 Error)落 `null` / 计数标签 `"none"`,**不编**一个码。
+ * (一次性布局搬家、无主根内容、控制面写失败)一辈子只发生一次 —— 折平就等于没说。
+ * 码的读法与 `boot/runner-deps.ts` 的 `onError` 汇点其余七条行**同一只**(`terminal.ts` 的 `codeFieldOf`:不抛的读口 + 码判官 `isCodeToken`):是码才带;
+ * 无码(core 里有大量不带 `.code` 的记忆相 Error)、不是串 / 空串、非 `Error` 抛出物、读取时抛、或带的不是码(超长 / 含空白 / 凭据形 —— 引擎错上的 `code` 是别人写的串)⇒ 行里**没有** `code` 键、
+ * 计数**没有** `code` 标签:不编码,也不写 `null` / `"none"` 之类的占位。
  *
- * ⚠️ 与 `main.ts` 三只 **operator 面**引擎座(`memory_compliance_incident` / `memory_origin_incident` /
- * `memory_consolidation_incident`)**刻意不合并**:那三条的事件名回答「哪一张操作面」,是三个产品面的
- * 分辨位;本工厂回答「引擎事故席」,是同一件事的四个落点。合并会丢掉前者的分辨位。
+ * ⚠️ 与三只 **operator 面**引擎座(`memory_compliance_incident` / `memory_origin_incident` /
+ * `memory_consolidation_incident`)**事件名刻意不合并**:那三条的事件名回答「哪一张操作面」,是三个产品面的
+ * 分辨位;本工厂回答「引擎事故席」,是同一件事的四个落点。合并会丢掉前者的分辨位。三座有自己的工厂
+ * {@link createOperatorFaceIncidentSink}(事件名由装配处点名),`code` 位与本工厂读同一只 `codeFieldOf`。
  */
 import type { Logger } from "./observability/logger.js";
 import type { Metrics } from "./observability/metrics.js";
@@ -34,4 +37,14 @@ export interface MemoryEngineIncidentSinkDeps {
 export declare function createMemoryEngineIncidentSink(deps: MemoryEngineIncidentSinkDeps): (err: unknown, ctx?: {
     sessionId?: string;
 }) => void;
+/** 三只 operator 面引擎座的事件名(闭集):事件名回答「哪一张操作面」—— 出处 / 抹除合规 · 外源标记人面 · 整理三面,由装配处点名。 */
+export type OperatorFaceIncidentEvent = "memory_compliance_incident" | "memory_origin_incident" | "memory_consolidation_incident";
+/**
+ * operator 面引擎座(各面工厂的 `onIncident` 形参:`(err: Error & { code?: string }) => void`)的唯一落点形:`<事件名>` + `{ code?, detail }`。
+ * 这三座此前各在装配处写一份 `{ code: err.code ?? null, detail }` —— 引擎错上的 `code` 是别人写的串,什么都照写(凭据形也进行),无码写 `null` 占位;
+ * 现在 `code` 位读 `codeFieldOf`(与 `onError` 汇点其余各行、{@link createMemoryEngineIncidentSink} 同一只):是码才带,其余键缺席;`detail` 句只经运维文本座。
+ */
+export declare function createOperatorFaceIncidentSink(deps: Pick<MemoryEngineIncidentSinkDeps, "logger">, event: OperatorFaceIncidentEvent): (err: Error & {
+    code?: string;
+}) => void;
 //# sourceMappingURL=memory-incident-sink.d.ts.map

package/dist/memory-incident-sink.js

@@ -1,14 +1,18 @@
 import { redactIncarnations } from "./session-incarnation.js";
+import { codeFieldOf } from "./terminal.js";
+import { seatText } from "./trace/exit-seat.js";
 export function createMemoryEngineIncidentSink(deps) {
     return (err, ctx) => {
-        const code = err?.code;
-        const codeText = typeof code === "string" && code !== "" ? code : undefined;
+        const codeField = codeFieldOf(err);
         deps.logger.warn("memory_engine_incident", {
             ...(ctx?.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}),
-            code: codeText ?? null,
+            ...codeField,
             detail: redactIncarnations(String(err)),
         });
-        deps.metrics?.inc("memory_engine_incident_total", { code: codeText ?? "none" });
+        deps.metrics?.inc("memory_engine_incident_total", { ...codeField });
     };
 }
+export function createOperatorFaceIncidentSink(deps, event) {
+    return (err) => deps.logger.warn(event, { ...codeFieldOf(err), detail: seatText("operator-log-text", err.message) });
+}
 //# sourceMappingURL=memory-incident-sink.js.map

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

@@ -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 };
@@ -123,7 +116,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 +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;
@@ -290,6 +283,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 +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;
@@ -324,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", {
@@ -342,35 +336,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 +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)
@@ -404,7 +412,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