@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/memory-face-fault-reply.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 记忆面的**一只收尾**:「定店 / 读控制面时说不清」这一个故障源的两种形 —— 本服务的层拒 `MemoryLayerRefusal` 与 core 的控制面损坏
+ * `ControlPlaneCorruptError` —— 在 HTTP 上的答法,唯一一处;外加记忆动词的**层座**读法。
+ *
+ * ## 规则(一条)
+ * 一只记忆面的 catch 只调 {@link sentMemoryFaceFault} 一次,先于它自己的码表(两形都是类判别、与 core 的带码拒不相交:层拒的 `code` 是本服务的
+ * `request.memory_layer`,控制面损坏没有 `code`)。挂不挂哪一形不由各面记 —— 两种形同一个故障源(定店 / 读控制面),哪一只面都可能收到哪一形,
+ * 组合是全面律,不按今天能不能构造出来挑面。两只单件是本模块私有的(不导出 ⇒ 面上不可能只挂一半);`instanceof` 判别只住这里。
+ * 调用面(九只):导出 / 导入包 · 外源三口 · 整理 run · 整理状态 · 合规两口(运维)· 记忆导出 · 记忆同步 · 会话记忆状态 · 会话记忆抹除。
+ *
+ * ## 层拒 ⇒ 400 `request.memory_layer`
+ * 一次记忆请求只落一只店(店的那一半在 `src/memory-scope-stores.ts`):请求点名的层读不出 / 点名的几层分住两只店 / 两店部署上没点名层 ——
+ * 请求可以改对,服务器没坏。
+ *
+ * ## 控制面损坏 ⇒ 500 `internal.memory_control_plane_corrupt`
+ * core 的 fail-closed 信号:记忆引擎的控制面(账本 / 事务日志 / 清标账 / 治理账 / 作用域登记簿)说不清,它宁可不答,也不在一个说不清的账上拼一个答案。
+ * 消费端按 `errorCode` 分支,运维有具体动作(修 / 重建之后重试)。
+ *
+ * ## 文案按受众分(码与状态不分;与 `memory-compliance-failure-reply.ts` 同一条规则):受众拿到的句子 = 它看得的材料
+ *  · operator ⇒ 原句上 wire(层拒点名部署配置的层与哪几层住在哪只店;控制面损坏点名**哪一张**账坏了、带宿主路径 —— 过了 operator 门的受众拿它不是泄露);
+ *  · 层属主(中心记忆导出 / 同步上过了层属主门、但不是 operator 的调用方:本人的 user 层 / 本人的项目层 / org 目录成员)⇒ 层拒原句(这两面只点名
+ *    一层,层拒句只带请求自己的层键与引擎的读法句,不带部署配置的层);控制面损坏换固定句(原句带宿主路径),原句整句交 `withheld` 落运维行;
+ *  · 会话所有者 ⇒ 固定句(只说怎么办),原句整句交 `withheld` 落运维行。层拒的固定句面无关(两形都真:点名的层读不出 / 本部署配置的层读不出);
+ *    控制面损坏的固定句按面分(受众闭集的面位,穷举 `switch`):
+ *      - `erase`:一码两义都真 —— 操作前账本读不出 ⇒ 什么都没发生;落定后残留枚举失败 ⇒ 抹除已提交、重放收敛(core 原话)。不许诺零删除,
+ *        指路「运维修好后用同一个 requestId 重发」;
+ *      - `status`:读面,只说「控制面读不清,运维修好后再读」—— 不许诺零删除、不提 requestId。
+ *    本层**不**嗅 core 文案去分辨哪一义(拿上游自由文本当判别式是第二真源)。
+ *
+ * ## 层座的读法({@link readLayerSeat})
+ * 不点名层的动词(条目 id / 会话 id / 店级账本)多一个可选的 `scope`:GET 口在查询串(`?scope=<层键>`),POST 口在体里(`"scope": "<层键>"`);
+ * 点名的层只用来定店,动词本身的语义不变。缺席 ⇒ 没点名;在场 ⇒ 必须是非空串,否则 400 `request.field_invalid`、面一次都不调
+ * (空串与非串不是「没点名」—— 静默当缺席会把请求答在另一只店上)。
+ *
+ * 每处 `sendError` 的码与固定句都写**字面量**:错误码目录门(`test/error-code-catalog-live.test.ts`)与文案冻结门(`test/api-error-text-freeze.test.ts`)
+ * 扫的是源码字面量,变量态的码 / 句对它们隐形。
+ */
+import type { ServerResponse } from "node:http";
+import type { MemoryLayerSeat } from "../memory-operator-faces.js";
+/** 会话所有者受众:面位(控制面损坏的固定句按它分)+ `withheld`(被换成固定句的原句落到那里 —— 运维材料不许丢)。 */
+type SessionOwnerAudience<F extends string> = {
+    readonly kind: "session_owner";
+    readonly face: F;
+    readonly withheld: (coreMessage: string) => void;
+};
+/** 层属主受众(中心记忆导出 `export` / 同步 `sync`;过了层属主门而不是 operator 的调用方)。 */
+type LayerOwnerAudience = {
+    readonly kind: "layer_owner";
+    readonly face: "export" | "sync";
+    readonly withheld: (coreMessage: string) => void;
+};
+/** 读记忆面收尾的受众(闭集)。会话所有者两面:自助抹除 `erase` · 会话记忆状态 `status`;层属主一类(中心导出 / 同步)。 */
+export type MemoryFaceAudience = {
+    readonly kind: "operator";
+} | LayerOwnerAudience | SessionOwnerAudience<"erase"> | SessionOwnerAudience<"status">;
+/**
+ * 层座:`present` = 键在不在(查询串 `has` / 体 `in`),`value` = 它的值。缺席 ⇒ `undefined`;非空串 ⇒ `{ layer }`;
+ * 其余 ⇒ 已答 400 `request.field_invalid`,返回 `null`(调用方 `return`)。
+ */
+export declare function readLayerSeat(res: ServerResponse, present: boolean, value: unknown): MemoryLayerSeat | undefined | null;
+/**
+ * `err` 是这一个故障源的两形之一 ⇒ 已应答,返回 true:层拒 ⇒ 400 `request.memory_layer`;控制面损坏 ⇒ 500 `internal.memory_control_plane_corrupt`
+ * (文案按受众)。否则 false,一个字节都不写(调用方接着走它自己的码表)。
+ */
+export declare function sentMemoryFaceFault(res: ServerResponse, err: unknown, audience: MemoryFaceAudience): boolean;
+export {};
+//# sourceMappingURL=memory-face-fault-reply.d.ts.map

package/dist/http/memory-face-fault-reply.js

@@ -0,0 +1,71 @@
+import { ControlPlaneCorruptError } from "@sema-agent/core";
+import { MemoryLayerRefusal } from "../memory-scope-stores.js";
+import { assertNever } from "./route-ctx.js";
+import { sendError } from "./send.js";
+export function readLayerSeat(res, present, value) {
+    if (!present)
+        return undefined;
+    if (typeof value === "string" && value.length > 0)
+        return { layer: value };
+    sendError(res, 400, "request.field_invalid", "scope must be a non-empty memory layer key when present — it names the layer whose memory store this request is answered on");
+    return null;
+}
+export function sentMemoryFaceFault(res, err, audience) {
+    if (err instanceof MemoryLayerRefusal) {
+        sendLayerRefusal(res, err, audience);
+        return true;
+    }
+    if (err instanceof ControlPlaneCorruptError) {
+        sendControlPlaneCorrupt(res, err, audience);
+        return true;
+    }
+    return false;
+}
+function sendLayerRefusal(res, err, audience) {
+    switch (audience.kind) {
+        case "operator":
+        case "layer_owner":
+            sendError(res, 400, "request.memory_layer", err.message);
+            return;
+        case "session_owner":
+            audience.withheld(err.message);
+            sendError(res, 400, "request.memory_layer", "the memory store this request reaches cannot be told — the `scope` in the request is not a memory layer this deployment can read, or this deployment's own memory layer configuration cannot be read; resend without `scope` (or with a readable layer), or ask the operator");
+            return;
+        default:
+            return assertNever(audience);
+    }
+}
+function sendControlPlaneCorrupt(res, err, audience) {
+    switch (audience.kind) {
+        case "operator":
+            sendError(res, 500, "internal.memory_control_plane_corrupt", err.message);
+            return;
+        case "layer_owner":
+            audience.withheld(err.message);
+            switch (audience.face) {
+                case "export":
+                    sendError(res, 500, "internal.memory_control_plane_corrupt", "memory export could not be completed — the memory store of this layer could not be read cleanly (its memory control plane is damaged); ask the operator to repair it, then retry");
+                    return;
+                case "sync":
+                    sendError(res, 500, "internal.memory_control_plane_corrupt", "memory sync could not be completed — the memory store of this layer could not be read cleanly (its memory control plane is damaged); ask the operator to repair it, then retry the round");
+                    return;
+                default:
+                    return assertNever(audience);
+            }
+        case "session_owner":
+            audience.withheld(err.message);
+            switch (audience.face) {
+                case "erase":
+                    sendError(res, 500, "internal.memory_control_plane_corrupt", "session memory erasure could not be completed — this deployment's memory control plane could not be read cleanly (depending on where it stopped, either nothing was changed or the deletions were already committed and a replay finishes them); ask the operator to repair it, then resend with the same requestId");
+                    return;
+                case "status":
+                    sendError(res, 500, "internal.memory_control_plane_corrupt", "session memory status could not be read — this deployment's memory control plane could not be read cleanly; ask the operator to repair it, then read the status again");
+                    return;
+                default:
+                    return assertNever(audience);
+            }
+        default:
+            return assertNever(audience);
+    }
+}
+//# sourceMappingURL=memory-face-fault-reply.js.map

package/dist/http/memory-store-refusal-reply.d.ts

@@ -1,5 +1,5 @@
 /**
- * **店形拒**一族(`memory.target_outside_store` / `memory.scope_home_not_directory` / `memory.control_plane_links_unsupported`,族表与判据在 `src/memory-store-refusal.ts`)的
+ * **店形拒**一族(`memory.target_outside_store` / `memory.scope_home_not_directory` / `memory.control_plane_links_unsupported` / `memory.control_plane_strays`,族表与判据在 `src/memory-store-refusal.ts`)的
  * **operator 面 HTTP 映射** + 两受众共用的**运维行** —— operator 面唯一一处码字面量(会话所有者面的逐码臂在 `http/memory-compliance-failure-reply.ts`;引擎加码 ⇒ 两处各补一臂)。挂在每一个触 store 树的 operator 记忆口的已分类收尾上:
  * `routes/memory-compliance.ts`(出处 / 抹除;经 `http/memory-compliance-failure-reply.ts` 的 operator 受众臂)· `routes/memory-origin.ts`(外源列表 / 清标;**不含**只读控制面的清标账列表 ——
  * core 的 wire 表逐字:只碰控制面的面不判,给它挂一条永远收不到的码路径正是附录 A 活触发门要防的形)·

package/dist/http/memory-store-refusal-reply.js

@@ -15,6 +15,9 @@ export function sentMemoryStoreRefusal(res, err, logger) {
         case "memory.control_plane_links_unsupported":
             sendError(res, 409, "memory.control_plane_links_unsupported", refusal.message);
             return true;
+        case "memory.control_plane_strays":
+            sendError(res, 409, "memory.control_plane_strays", refusal.message);
+            return true;
         default: {
             const unhandled = refusal.code;
             throw new Error(`unhandled store-form refusal word: ${String(unhandled)}`);