@sema-agent/server 7.45.0 → 7.46.0-rc.2

package/dist/http/routes/memory-consolidation.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { ControlPlaneCorruptError } from "@sema-agent/core";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export const MEMORY_CONSOLIDATION_STATUS_PATH = "/v1/admin/memory/consolidation";
+export const MEMORY_CONSOLIDATION_RUN_PATH = "/v1/admin/memory/consolidation/run";
+const RunRequestSchema = z.object({ scope: z.string().optional() }).strict();
+function buildRunSummary(r) {
+    return {
+        runId: r.runId,
+        scope: r.scope,
+        resumed: r.resumed,
+        outcome: r.outcome,
+        converged: r.converged,
+        cycles: r.cycles.length,
+        cyclesDone: r.cyclesDone,
+        productsCommitted: r.productsCommitted,
+        entriesSuperseded: r.entriesSuperseded,
+        plans: r.planIds.length,
+        model: r.model,
+        contractVersion: r.contractVersion,
+        usage: r.usage,
+        repairs: r.repairs,
+        writeFailures: r.writeFailures.length,
+        residueProducts: r.residue.length,
+        ...(r.planArchive !== undefined ? { planArchive: r.planArchive } : {}),
+        notices: r.notices.map((n) => ({ noticeCode: n.code, message: n.message })),
+        ...(r.announceFailures !== undefined && r.announceFailures.length > 0 ? { announceFailures: r.announceFailures.length } : {}),
+    };
+}
+function buildRunRowSummary(row) {
+    return {
+        runId: row.runId,
+        scope: row.scope,
+        state: row.state,
+        ...(row.outcome !== undefined ? { outcome: row.outcome } : {}),
+        startedAt: row.startedAt,
+        ...(row.settledAt !== undefined ? { settledAt: row.settledAt } : {}),
+        attempt: row.attempt,
+        cyclesDone: row.cyclesDone,
+        entriesSuperseded: row.entriesSuperseded,
+        plans: row.planIds.length,
+        model: row.model,
+        contractVersion: row.contractVersion,
+        usage: row.usage,
+        repairs: row.repairs,
+        writeFailures: row.writeFailures.length,
+        residueProducts: row.residue?.length ?? 0,
+        ...(row.planArchive !== undefined ? { planArchive: row.planArchive } : {}),
+        ...(row.nextEligibleAt !== undefined ? { nextEligibleAt: row.nextEligibleAt } : {}),
+    };
+}
+function decideScope(given, configured) {
+    if (given !== undefined) {
+        const trimmed = given.trim();
+        if (trimmed === "")
+            return { refusal: "blank" };
+        if (configured.length > 0 && !configured.includes(trimmed))
+            return { refusal: "off-roster" };
+        return { scope: trimmed };
+    }
+    if (configured.length === 1)
+        return { scope: configured[0] };
+    return { refusal: configured.length === 0 ? "none-configured" : "ambiguous" };
+}
+function codeOf(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const { code } = err;
+    return typeof code === "string" ? code : undefined;
+}
+export async function handleMemoryConsolidation(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleMemoryConsolidationBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleMemoryConsolidationBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    const isRun = req.method === "POST" && path === MEMORY_CONSOLIDATION_RUN_PATH;
+    const isStatus = req.method === "GET" && path === MEMORY_CONSOLIDATION_STATUS_PATH;
+    const faces = deps.memoryConsolidation;
+    if ((!isRun && !isStatus) || faces === undefined) {
+        miss.fell = true;
+        return;
+    }
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && !principal) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+        sendError(res, 403, "auth.operator_only", "memory consolidation is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable these endpoints)");
+        return;
+    }
+    if (isStatus) {
+        const q = new URL(req.url ?? "", "http://x").searchParams.get("scope") ?? undefined;
+        const decided = decideScope(q, faces.scopes);
+        const scope = "scope" in decided ? decided.scope : undefined;
+        const row = scope !== undefined ? faces.lastRun(scope) : undefined;
+        sendJson(res, 200, {
+            enabled: true,
+            seat: faces.seat,
+            model: faces.model,
+            scopes: faces.scopes,
+            ...(scope !== undefined ? { scope } : {}),
+            ...(row !== undefined ? { lastRun: buildRunRowSummary(row) } : {}),
+        });
+        return;
+    }
+    const parsed = RunRequestSchema.safeParse(await ctx.helpers.readJson(req));
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "invalid memory consolidation request — expected an object with an optional `scope` string");
+        return;
+    }
+    const decided = decideScope(parsed.data.scope, faces.scopes);
+    if ("refusal" in decided) {
+        switch (decided.refusal) {
+            case "blank":
+                sendError(res, 400, "request.body_shape", "invalid memory consolidation request — `scope` must be a non-empty string naming the memory scope to fold");
+                return;
+            case "none-configured":
+                sendError(res, 400, "request.body_shape", "invalid memory consolidation request — `scope` is required: this deployment configured no MEMORY_CONSOLIDATION_SCOPES, so there is no single library to default to, and one consolidation run reads a WHOLE scope (~1e5 prompt tokens). Send a `scope`, or set MEMORY_CONSOLIDATION_SCOPES to the one scope this worker folds");
+                return;
+            case "off-roster":
+                sendError(res, 400, "request.body_shape", `invalid memory consolidation request — this worker declares the scopes it folds in MEMORY_CONSOLIDATION_SCOPES (${faces.scopes.join(", ")}) and the requested scope is not one of them; a stale or mistyped scope would spend a whole-library distillation on a different library and supersede its entries. Send one of the declared scopes, add this one to MEMORY_CONSOLIDATION_SCOPES, or unset that knob to fold any scope on request`);
+                return;
+            case "ambiguous":
+                sendError(res, 400, "request.body_shape", `invalid memory consolidation request — a scope is required: MEMORY_CONSOLIDATION_SCOPES lists more than one scope (${faces.scopes.join(", ")}) and the server never picks which library to spend a whole-library distillation on`);
+                return;
+            default: {
+                const unreachable = decided.refusal;
+                throw new Error(`unhandled consolidation scope refusal: ${String(unreachable)}`);
+            }
+        }
+    }
+    try {
+        const r = await faces.run(decided.scope);
+        sendJson(res, 200, buildRunSummary(r));
+    }
+    catch (err) {
+        const coreCode = codeOf(err);
+        if (coreCode !== undefined) {
+            sendError(res, 409, "memory.consolidation_refused", `memory consolidation refused (${coreCode}): ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (err instanceof ControlPlaneCorruptError) {
+            sendError(res, 500, "internal.memory_control_plane_corrupt", err.message);
+            return;
+        }
+        ctx.deps.logger?.warn?.("memory_consolidation_run_failed", { scope: decided.scope, err: String(err) });
+        sendError(res, 500, "internal.error", "memory consolidation run failed");
+    }
+}
+//# sourceMappingURL=memory-consolidation.js.map

package/dist/http/routes/memory-origin.d.ts

@@ -0,0 +1,124 @@
+/**
+ * design/316 件② —— **外源标记人面的 operator 三口**(core 5.59.0 `MemoryEngine.listExternalOriginEntries` /
+ * `listOriginClearances` / `clearEntryOrigin`,design/336 §13-4①②)。
+ *
+ *   · `GET  /v1/memory/origin/external?scopes=a,b` —— 点名 scope 里每一条带外源标记的条目 + 出处账;
+ *   · `GET  /v1/memory/origin/clearances`          —— 清标审计账(**白名单投影**,见下);
+ *   · `POST /v1/memory/origin/entries/:entryId/clear` `{requestId, reason}` —— 审计化的 UN-MARK 阀门。
+ *
+ * ── 为什么是 operator-only ─────────────────────────────────────────────────────────────────────
+ * 与件③(memory-compliance.ts)、#264 的 bundle 两口同族:
+ *  · 前两口是**跨租户治理读**:一次调用取回任意 scope 的条目 + 每条的完整出处账(贡献会话 id、污染
+ *    理由、托管链事件),按定义超出任何单个 principal 的自助边界;
+ *  · clear 是**治理写面**,而且是记忆域里语义最重的一次表态 —— 它把「这条记忆来自外部、用前先核」
+ *    这句披露**替宿主担保掉**。core 的原话是 the host's explicit vouching starts the entry's unmarked
+ *    life:签字的人必须是部署的操作员,不是任何一个租户。
+ * 缺 principal 的形照 sibling operator 端点(adoption / retention-ops / memory-bundle / memory-compliance)401。
+ *
+ * ── 门序(逐字同 routes/memory-compliance.ts)─────────────────────────────────────────────────
+ * 身份(401)→ 授权(403)→ 能力(501)→ 验型(400)。**授权在能力之前**:一个够不着任何东西的调用方
+ * 不该从「这个部署有没有记忆引擎」上读出部署形态。
+ *
+ * ── 能力面:501 的判据与件③ **同一条**(同码同文案族,不同族名)────────────────────────────────
+ * 三口都真的读引擎控制面,而且 clear 的写前托管行是崩溃窗内条目字节的**唯一一份** —— 判在挂载期
+ * (`createMemoryOriginFaces` 返 undefined ⇒ 三口整个不挂),全文见 `src/memory-operator-faces.ts` 头注。
+ * 码复用 `capability.memory_engine_required`(消费端分支相同:换部署形态),文案自成一句 —— 与 bundle /
+ * compliance 两族刻意不同字,因为要查的旋钮不是同一个(那两族自己的头注就吃过复用文案的亏)。
+ *
+ * ── `scopes` 为什么必须由调用方给(F-13 的诚实形)──────────────────────────────────────────────
+ * 🔴 本仓**今天没有任何 scope 枚举读面**。core 5.59.0 长出了 `listMemoryScopes`(#437③:File 腿在场、
+ * SQL 腿是 core 候升件,且带「backend 是否支持枚举」判别位——不支持**永不读作零**),但本仓尚未接线。
+ * 于是 v1 的形是:scope 名**显式提供**,缺参 400 并**指路来源**。
+ * 为什么不给一个默认名单(比如「本部署配过的那些」):污染审计的价值全在**发现链闭合**,而不完备是
+ * **静默**的 —— 空数组与「这些 scope 干净」在 wire 上同形。一个猜出来的名单会让 operator 读到一份
+ * 自称干净、其实只查了一半的账。所以本口的答案永远只对**它被点名的那些 scope**成立,这句话写进 400
+ * 文案、写进附录 A、也写进端点文档:**never read an empty answer as "the store is clean"**。
+ *
+ * ── `GET …/clearances` 为什么是**白名单**而不是透传(F-7)───────────────────────────────────────
+ * 与件③ 的两个账(透传)**刻意相反**,判据仍是那一条「新键静默上 wire 危险吗」:
+ *  · `OriginClearanceRow.entryText` = 被清标条目的**完整正文托管字节**。core 逐字:a crash between the
+ *    tombstone batch and the re-record batch leaves this as the only copy —— 它是**崩溃恢复席**,而恢复
+ *    的手段是**再调一次 `clearEntryOrigin`**(引擎从行里自己重放),不是让人把字节读出来贴回去。
+ *    把整条记忆的正文放上一个审计列表面,等于给每一次「看看清标记录」都附赠一份全文导出;
+ *  · 而这份账**新长一个键**时,静默上 wire 恰恰是危险的那一侧(它是托管面,不是事实陈述面)。
+ * ⇒ 显式白名单 + **编译期差集门**(`test/wire-whitelist-exhaustiveness.test.ts` 的 `KnownExcluded`
+ *   = `entryText`,逐字写理由):core 加一个键 ⇒ TS2344 ⇒ 由人处置,而不是悄悄上 wire 或悄悄漏掉。
+ * 🔴 白名单是**深**的,不是只做一层(codex 对抗复审 [high] 抓的第一版病):嵌套的 `origin` 也逐键投影
+ *   —— 一层白名单 + 一个整只透传的嵌套对象,等于给这条排除留了一个后门,全文见 {@link buildOriginWire}。
+ * 🔴 **剥了不等于不说**:投影补一个 `custodyBytes`(托管字节数)。这是 #196 absence-reports-not-silent-green
+ *   在本口的落法 —— operator 判「这个 pending 行还揣着一条记忆吗」只需要这一位;悄悄把整个托管概念从
+ *   审计面上抹掉,会让一个**必须由人处置**的崩溃恢复席看上去不存在。
+ *
+ * ── 拒因族:**闭集逐码 switch**(#123 码族)────────────────────────────────────────────────────
+ * 见 {@link sentClearCode} 的头注(逐码状态与理由、以及 core 真形与 design/316 稿面的**一处偏差**)。
+ *
+ * 计费/lane:三口都是**部署级治理动作**,零模型工作 ⇒ `billable=false`(与 adoption / retention-ops /
+ * memory-bundle / memory-compliance 同族,申明在 test/billable-route-declaration.test.ts)。
+ *
+ * ── 改写门(`isCredentialGatedRewrite`):**三口全进** ──────────────────────────────────────────
+ * 该门自 #277 起的判据是「持久改写 **或** 授权唯一输入是 principal 头的跨租户治理读」:
+ *  · `POST …/clear` 落在**前**一项:它把一条条目的外源披露**永久摘掉**(墓碑 + 同 id 重录),伪造一个
+ *    在册 operator 头即可让任意租户的一条外来记忆看上去是本店自产的 —— 而记忆是模型每次挂载都读的面;
+ *  · `GET …/external` 落在**后**一项,而且是这一族里爆炸半径最大的读:一次调用取回**任意 scope**的
+ *    条目 + 每条的完整出处账(贡献会话 id、污染理由、仓内 ingest 路径与内容哈希、托管链事件)。判据与
+ *    `POST /v1/memory/export`(#277 收进门的那条纯读)逐字同构:它没有属主门兜底,operator 头过了就直接答。
+ *  · `GET …/clearances` —— 🔴 **本车第一版把它留在门外,codex 对抗复审 [high] 推翻,亲验后采信**。
+ *    那一版的理由是「投影后不含条目正文,爆炸半径差一个量级」,而这个理由**用错了基准**:本门的判据
+ *    从来不是「含不含正文」,而是「授权的**唯一**输入是 principal 头」∧「没有属主门兜底」。按那条判据,
+ *    一口**整部署**的清标账(每个租户的 scope+slug、entryId、rev、operator 手写的自由文本 `reason`、
+ *    requestId、时间线)比已经在门里的**单条** `GET …/:entryId/provenance` 爆炸半径更大,不是更小;而
+ *    `reason` 是自由文本 —— 它完全可能把条目内容摘一句进去,连「不含正文」这个前提本身都不牢。
+ *    与 `POST /v1/memory/export` / `GET …/provenance` 两次改判是同一条论证:把它留在门外只为守住一句
+ *    自己写的措辞,是把措辞看得比它要保护的东西更重。
+ * ⚠️ 三条都是**逐条式**入门,不是 `/v1/memory/origin/` 前缀吃(写口那一臂才是前缀,方向宁紧):这个
+ *    前缀下将来长出的读口未必都够判据,逐口论证过才入门 —— 这正是本门「闭」的那一半。代价与补偿如实
+ *    成文:无凭证部署上三口都答 503 `auth.service_token_required`,补偿是**既有旋钮零新增**(配
+ *    `SERVICE_AUTH_TOKEN` 走正路,或本地开发显式 `ALLOW_UNAUTHED_WRITES=true`)。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type OriginClearanceRow } from "@sema-agent/core";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const MEMORY_ORIGIN_EXTERNAL_PATH = "/v1/memory/origin/external";
+export declare const MEMORY_ORIGIN_CLEARANCES_PATH = "/v1/memory/origin/clearances";
+/** 带参写口 ⇒ 名册门走 `ROUTE_LABEL_PATTERNS`(server.ts),不是 LITERALS。 */
+export declare const MEMORY_ORIGIN_CLEAR_RE: RegExp;
+/**
+ * 一条清标行 → wire 的**显式白名单**(F-7)。全文理由见文件头「为什么是白名单」。
+ *
+ * 被剥的 core 键**只有一个**:`entryText`(完整正文托管字节),而且**剥了要说** —— `custodyBytes` 是它
+ * 留在审计面上的那句披露(0 = 这行没揣着字节;>0 = 崩溃恢复席里还有一条记忆的正文,pending 行要人处置)。
+ * 嵌套的 `origin` 不是「被剥」而是**被深投影**(三键之外的成员剥值留名,见 {@link buildOriginWire})。
+ * 🔴 **不要**给这个函数标 `: Record<string, unknown>` 返回型:那会让 `keyof ReturnType<…>` 塌成 `string`,
+ * 编译期差集门当场变成恒真(vacuous)—— `buildImportReportWire` 的头注里踩过这个坑,而本车在 `origin`
+ * 那只投影上**又踩了一次**(标了具体返回型,门读标注不读字面量),所以这条钉现在有两处案底。
+ */
+export declare function buildClearanceRowWire(r: OriginClearanceRow): {
+    events: {
+        detail?: string | undefined;
+        eventId: string;
+        at: number;
+        to: "failed" | "done";
+        requestId: string;
+    }[];
+    custodyBytes: number;
+    tombstonedAt?: number | undefined;
+    requestId: string;
+    reason: string;
+    at: number;
+    status: "pending" | "failed" | "done";
+    originUnknownKeys?: string[] | undefined;
+    clearanceId: string;
+    entryId: string;
+    scope: string;
+    slug: string;
+    baseRev: string;
+    origin: {
+        at: number;
+        cause?: "static" | "unattributed" | "observed" | "derived" | undefined;
+        taint: "external";
+    };
+};
+export declare function handleMemoryOrigin(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=memory-origin.d.ts.map

package/dist/http/routes/memory-origin.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { ControlPlaneCorruptError } from "@sema-agent/core";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export const MEMORY_ORIGIN_EXTERNAL_PATH = "/v1/memory/origin/external";
+export const MEMORY_ORIGIN_CLEARANCES_PATH = "/v1/memory/origin/clearances";
+export const MEMORY_ORIGIN_CLEAR_RE = /^\/v1\/memory\/origin\/entries\/([^/]+)\/clear$/;
+const ClearRequestSchema = z.object({
+    requestId: z.string().min(1),
+    reason: z.string(),
+});
+function sentClearCode(res, coreCode, message) {
+    switch (coreCode) {
+        case "memory.origin_clear_unattributed":
+            sendError(res, 422, "memory.origin_clear_unattributed", message);
+            return true;
+        case "memory.origin_clear_invalid":
+            sendError(res, 422, "memory.origin_clear_invalid", message);
+            return true;
+        case "memory.origin_clear_unknown":
+            sendError(res, 409, "memory.origin_clear_unknown", message);
+            return true;
+        case "memory.origin_clear_not_marked":
+            sendError(res, 409, "memory.origin_clear_not_marked", message);
+            return true;
+        case "memory.origin_clear_challenged":
+            sendError(res, 409, "memory.origin_clear_challenged", message);
+            return true;
+        case "memory.origin_clear_conflict":
+            sendError(res, 409, "memory.origin_clear_conflict", message);
+            return true;
+        case "memory.origin_clear_failed":
+            sendError(res, 409, "memory.origin_clear_failed", message);
+            return true;
+        case "memory.origin_clear_pending":
+            sendError(res, 409, "memory.origin_clear_pending", message);
+            return true;
+        default:
+            return false;
+    }
+}
+function codeOf(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const { code } = err;
+    return typeof code === "string" ? code : undefined;
+}
+function sentClassifiedFailure(res, ctx, face, err) {
+    if (face === "clear") {
+        const coreCode = codeOf(err);
+        if (coreCode !== undefined && sentClearCode(res, coreCode, err instanceof Error ? err.message : String(err)))
+            return true;
+    }
+    if (err instanceof ControlPlaneCorruptError) {
+        sendError(res, 500, "internal.memory_control_plane_corrupt", err.message);
+        return true;
+    }
+    ctx.deps.logger?.warn?.(`memory_origin_${face}_failed`, { err: String(err) });
+    return false;
+}
+function buildClearanceEventWire(e) {
+    return {
+        eventId: e.eventId,
+        at: e.at,
+        to: e.to,
+        requestId: e.requestId,
+        ...(e.detail !== undefined ? { detail: e.detail } : {}),
+    };
+}
+function buildOriginWire(o) {
+    return { taint: o.taint, ...(o.cause !== undefined ? { cause: o.cause } : {}), at: o.at };
+}
+function originUnknownKeysOf(o) {
+    const known = new Set(["taint", "cause", "at"]);
+    const extra = Object.keys(o).filter((k) => !known.has(k)).sort();
+    return extra.length > 0 ? extra : undefined;
+}
+export function buildClearanceRowWire(r) {
+    const originUnknownKeys = originUnknownKeysOf(r.origin);
+    return {
+        clearanceId: r.clearanceId,
+        entryId: r.entryId,
+        scope: r.scope,
+        slug: r.slug,
+        baseRev: r.baseRev,
+        origin: buildOriginWire(r.origin),
+        ...(originUnknownKeys !== undefined ? { originUnknownKeys } : {}),
+        requestId: r.requestId,
+        reason: r.reason,
+        at: r.at,
+        status: r.status,
+        ...(r.tombstonedAt !== undefined ? { tombstonedAt: r.tombstonedAt } : {}),
+        events: r.events.map(buildClearanceEventWire),
+        custodyBytes: Buffer.byteLength(r.entryText, "utf8"),
+    };
+}
+function parseScopes(raw) {
+    const out = [];
+    for (const one of raw) {
+        for (const seg of one.split(",")) {
+            const s = seg.trim();
+            if (s !== "" && !out.includes(s))
+                out.push(s);
+        }
+    }
+    return out.length > 0 ? out : null;
+}
+export async function handleMemoryOrigin(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleMemoryOriginBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleMemoryOriginBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    const isExternal = req.method === "GET" && path === MEMORY_ORIGIN_EXTERNAL_PATH;
+    const isClearances = req.method === "GET" && path === MEMORY_ORIGIN_CLEARANCES_PATH;
+    const clearMatch = req.method === "POST" ? MEMORY_ORIGIN_CLEAR_RE.exec(path) : null;
+    if (!isExternal && !isClearances && clearMatch === null) {
+        miss.fell = true;
+        return;
+    }
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && !principal) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+        sendError(res, 403, "auth.operator_only", "memory origin marking and clearance are operator-only deployment actions");
+        return;
+    }
+    const faces = deps.memoryOriginFace;
+    if (faces === undefined) {
+        sendError(res, 501, "capability.memory_engine_required", "memory origin marking and clearance are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the clearance ledger and its write-ahead custody rows live in that plane, and on a backend without it they would land on one replica's local disk");
+        return;
+    }
+    if (isExternal) {
+        const scopes = parseScopes(new URL(req.url ?? "", "http://x").searchParams.getAll("scopes"));
+        if (scopes === null) {
+            sendError(res, 400, "request.query_invalid", "`scopes` is required and must name at least one memory scope (comma-separated, e.g. `?scopes=user:alice,org:acme`) — this deployment has no scope-enumeration read face yet, so name the same scope keys you use on `GET /v1/memory/export?scope=`; an answer here covers ONLY the scopes you named and an empty result must never be read as \"the store is clean\"");
+            return;
+        }
+        try {
+            sendJson(res, 200, { scopes, entries: await faces.listExternal(scopes) });
+        }
+        catch (err) {
+            if (!sentClassifiedFailure(res, ctx, "external", err))
+                sendError(res, 500, "internal.error", "memory external-origin listing failed");
+        }
+        return;
+    }
+    if (isClearances) {
+        try {
+            sendJson(res, 200, { clearances: faces.listClearances().map(buildClearanceRowWire) });
+        }
+        catch (err) {
+            if (!sentClassifiedFailure(res, ctx, "clearances", err))
+                sendError(res, 500, "internal.error", "memory origin clearance listing failed");
+        }
+        return;
+    }
+    const entryId = ctx.helpers.safeDecode(clearMatch[1]);
+    if (entryId === null) {
+        sendError(res, 400, "request.id_invalid", "invalid memory entry id");
+        return;
+    }
+    const raw = await ctx.helpers.readJson(req);
+    const parsed = ClearRequestSchema.safeParse(raw);
+    if (!parsed.success) {
+        if (parsed.error.issues.some((i) => i.path.length > 0 && i.path[0] === "requestId")) {
+            sendError(res, 400, "request.request_id_required", "memory origin clearance requires a non-empty `requestId` string — it is the audit attribution of WHO cleared this marker and the server never mints one for you");
+            return;
+        }
+        sendError(res, 400, "request.body_shape", "invalid memory origin clearance request — expected an object with a non-empty `requestId` and a `reason` string (whether an EMPTY reason is acceptable is the engine's judgment, not this layer's)");
+        return;
+    }
+    try {
+        const receipt = await faces.clear(entryId, { requestId: parsed.data.requestId, reason: parsed.data.reason });
+        ctx.deps.logger?.info?.("memory_origin_cleared", {
+            principal: principal ?? null,
+            entryId,
+            clearanceId: receipt.clearanceId,
+            claimedRequestId: parsed.data.requestId,
+            landedSlug: receipt.landedSlug,
+        });
+        sendJson(res, 200, receipt);
+    }
+    catch (err) {
+        if (!sentClassifiedFailure(res, ctx, "clear", err))
+            sendError(res, 500, "internal.error", "memory origin clearance failed");
+    }
+}
+//# sourceMappingURL=memory-origin.js.map

package/dist/http/routes/rules.js

@@ -105,7 +105,7 @@ async function handleRulesBody(req, res, url, ctx, miss) {
             sendError(res, 413, "request.payload_too_large", "too many allow entries across the submitted settings layers");
             return;
         }
-        sendJson(res, 200, { preview: prepared.preview, ticket: prepared.ticket, expiresAtMs: prepared.expiresAtMs });
+        sendJson(res, 200, { preview: prepared.preview, ...(prepared.ticket !== undefined ? { ticket: prepared.ticket, expiresAtMs: prepared.expiresAtMs } : {}) });
         return;
     }
     const parsed = CcImportRedeemBodySchema.safeParse(rawBody);

package/dist/http/routes/side-query.js

@@ -18,6 +18,7 @@ const MODEL_ROLE_TABLE = {
     advisor: true,
     verifier: true,
     classifier: true,
+    consolidate: true,
 };
 function isModelRole(value) {
     return typeof value === "string" && Object.hasOwn(MODEL_ROLE_TABLE, value);

package/dist/http/server.d.ts

@@ -1,6 +1,6 @@
 import http from "node:http";
 import type { IncomingMessage } from "node:http";
-import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry, type MemoryExportBundle, type MemoryImportReport, type SideQuerySpec, type SideQueryResult, type Brain } from "@sema-agent/core";
+import { type Runner, type TaskSpec, type TaskResult, type WorkflowRunStore, type MemoryEntry, type MemoryExportBundle, type MemoryImportReport, type EntryProvenanceAccount, type MemoryErasureAttestation, type MemoryEntryOrigin, type OriginClearanceRow, type ConsolidationRunReceipt, type ConsolidationDriverRunRow, type SideQuerySpec, type SideQueryResult, type Brain } from "@sema-agent/core";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
 import { type RestartSignal, type SessionMirrorRuling } from "../config-center/facade.js";
@@ -26,6 +26,7 @@ import type { QuotaTracker } from "../observability/cost-quota.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "../budget.js";
 import { scopedIdempotencyKey } from "./idempotency.js";
 export { scopedIdempotencyKey };
+import type { ConsolidationSeatLabel } from "../boot/memory-consolidation.js";
 import { streamApprovals, isQuestionAnswer } from "./routes/approvals-assistant.js";
 export { streamApprovals, isQuestionAnswer };
 import { cascadeConfig } from "./run-meta.js";
@@ -176,7 +177,7 @@ export interface ServiceStoreDeps {
     backend?: StoreBackend;
     /** #154 车二:**持久化权限规则的同意车道**(core design/179 三步协议的宿主半场)。
      *  在场 ⇔ 规则店真装配(`backend.permissionRule()` 有值)⇒ `POST /v1/rules/cc-import/{prepare,redeem}`
-     *  可用、ask 帧才投 `ruleSuggestions`;缺席 ⇒ 两口 501、帧上零候选(发一格无处可兑的「不再询问」
+     *  可用、ask 帧才投 `ruleOffers`;缺席 ⇒ 两口 501、帧上零候选(发一格无处可兑的「不再询问」
      *  = wire 谎言,比缺席更坏)。 */
     ruleConsent?: RuleConsentLane;
 }
@@ -324,6 +325,70 @@ export interface ServiceSeamDeps {
     memoryBundleImport?: (bundle: unknown, opts?: {
         expectedScopes?: readonly string[];
     }) => Promise<MemoryImportReport>;
+    /** design/316 件③(core 5.57.0 `MemoryEngine.provenanceOf` / `eraseMemoryEntries`):出处 / 抹除合规面。
+     *  启用 `GET /v1/memory/entries/:entryId/provenance` 与 `POST /v1/memory/erase`(两口 operator-only)。
+     *  main.ts 把它接到 `createMemoryComplianceFaces` 的产物上。
+     *  🔴 缺席有两个成因,与 {@link memoryBundleExport} **同码不同判据**(同码是因为消费端分支相同:换部署
+     *  形态;判据不同是因为要查的旋钮不同):①记忆引擎没接线;②引擎接了但后端**不自带控制面归属**
+     *  (`controlPlaneRoot`)——本仓两只 SQL 记忆孪生即此形,core 那时会把控制面落到副本本地盘上,与
+     *  stateless replicas 正面冲突。②在**挂载期**判掉(工厂返 undefined),理由全文见
+     *  src/memory-operator-faces.ts 头注。
+     *  🔴 `erase` 的入参是 `unknown` 而不是 `EraseMemoryEntriesInput`:HTTP 层拿到的是一个**未校验**的对象,
+     *  三选一选择子的整体判决是 core 的单一属主面(`erasureRequestInvalid`)。写成具体类型就得在路由里断言
+     *  一次「它是合法输入」——那句断言是假的,而且正好把类型检查关灯。 */
+    memoryCompliance?: {
+        provenanceOf: (entryId: string) => Promise<EntryProvenanceAccount>;
+        erase: (input: unknown, opts?: {
+            allowedScopes?: readonly string[];
+        }) => Promise<MemoryErasureAttestation>;
+    };
+    /** design/316 件②(core 5.59.0 `MemoryEngine.listExternalOriginEntries` / `listOriginClearances` /
+     *  `clearEntryOrigin`):**外源标记人面**。启用 `GET /v1/memory/origin/external`、
+     *  `GET /v1/memory/origin/clearances`、`POST /v1/memory/origin/entries/:entryId/clear`(三口 operator-only)。
+     *  main.ts 把它接到 `createMemoryOriginFaces` 的产物上。
+     *  🔴 缺席的两个成因与 {@link memoryCompliance} **逐字同一条**(同码 `capability.memory_engine_required`,
+     *  消费端分支相同:换部署形态):①记忆引擎没接线;②引擎接了但后端**不自带控制面归属**
+     *  (`controlPlaneRoot`)。②在**挂载期**判掉(工厂返 undefined)。这一族的理由比合规两口更硬:清标的
+     *  写前托管行(`OriginClearanceRow.entryText`)在墓碑已落、重录未成的崩溃窗内是那条记忆**唯一的一份**
+     *  ——落在副本本地盘上 = pod 重建即永久丢失。全文见 src/memory-operator-faces.ts 头注。
+     *  🔴 `listClearances` 是**同步**的(core 的读面就是一次严格 sidecar 读),且账本损坏时**抛**
+     *  `ControlPlaneCorruptError` —— 那是 fail-closed 信号,不是空数组。 */
+    memoryOriginFace?: {
+        listExternal: (scopes: readonly string[]) => Promise<Array<{
+            id: string;
+            slug: string;
+            scope: string;
+            origin: MemoryEntryOrigin;
+            provenance: EntryProvenanceAccount;
+        }>>;
+        listClearances: () => OriginClearanceRow[];
+        clear: (entryId: string, input: {
+            requestId: string;
+            reason: string;
+        }) => Promise<{
+            entryId: string;
+            clearanceId: string;
+            origin: MemoryEntryOrigin;
+            landedSlug: string;
+        }>;
+    };
+    /** design/378(core 5.58.0 `runMemoryConsolidationDriver`):记忆 **consolidation 阀门**的操作面。
+     *  启用 `POST /v1/admin/memory/consolidation/run` 与 `GET /v1/admin/memory/consolidation`(两口 operator-only)。
+     *  main.ts 把它接到 `createMemoryConsolidationFaces` 的产物上。
+     *  🔴 缺席的**唯一**成因是「阀门没开」(`MEMORY_CONSOLIDATION_DRIVER` 不是 `on` —— 出厂缺省):
+     *  阀门开着却结构上跑不了的三种形(引擎没接线 / 后端没有控制面归属 / `MEMORY_PROVENANCE=off`)在
+     *  **启动期**就被拒了(`boot/memory-consolidation.ts`),那些机器根本起不来。⇒ 缺席形是 **404 族**
+     *  (整域不挂),刻意**不是** 501:501 说「换部署形态」,这里的动作是「把旋钮打开」。全文见
+     *  `routes/memory-consolidation.ts` 头注。
+     *  🔴 `seat` 的词表单一真源 = `boot/memory-consolidation.ts` 的 {@link ConsolidationSeatLabel}
+     *  (type-only import,tsc 擦除、非装载边)——在这里再写一遍字面量联合就是第二份会漂的词表。 */
+    memoryConsolidation?: {
+        readonly seat: ConsolidationSeatLabel;
+        readonly model: string;
+        readonly scopes: readonly string[];
+        run(scope: string): Promise<ConsolidationRunReceipt>;
+        lastRun(scope: string): ConsolidationDriverRunRow | undefined;
+    };
     /** design/170 件A §7 —— org 记忆授权目录,`boot/org-memory.ts` 装配的**同一个实例**(准入 seam 与
      *  本面共享它的 TTL 缓存/退避窗/gen 高水位)。memory-policy 面的 `org:` 属主门用它回答成员性:
      *  读面要该 scope 在授权表里、写面另要条目 `write === true`。缺席=本部署没有目录源 ⇒ `org:` 键
@@ -610,6 +675,10 @@ export declare function createHttpServer(rawDeps: ServiceDeps): http.Server & {
  * 「单 URL 多方法」这一种成员,加一条要连同它的域内补门一起过评审。
  */
 export declare function isMethodDispatchedSubmitPath(url: string): boolean;
+/** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源。**单一属主**:`handle()` 的
+ *  凭证门、#329 的 parked 赎回席、以及 design/378 的 consolidation 阀门启动期告警读同一句(手抄迟早
+ *  只改一处,而这条判据决定的是「无凭证部署上写口开不开」)。导出仅为最后一个消费点(main.ts)。 */
+export declare function hasServiceAuth(config: ServiceConfig): boolean;
 export declare function isBillableSubmitPath(url: string): boolean;
 /**
  * A-010.23(#209 件5)—— **改写门**:不烧模型、但在**没有任何 service credential** 的部署形下必须与