@sema-agent/server 7.29.0 → 7.30.0

package/dist/boot/shutdown.js

@@ -18,7 +18,7 @@ import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
 /** 注册 SIGTERM/SIGINT/SIGHUP 收尾链。**必须在 listen 之后调用**(见文件头「位置即契约」)。 */
 export function installShutdownHandlers(ctx) {
-    const { config, logger, server, reaper, fleetReconcile, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, } = ctx;
+    const { config, logger, server, reaper, fleetReconcile, retentionLane, releaseRetentionLease, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, } = ctx;
     let closing = false;
     /** #219:parent 监视腿(装配在本函数尾,`config.parentPid` 在场才建)。声明提前只为让 hardShutdown
      *  能把它一并停掉 —— 文件头契约 3 同族(收尾期不再有后台 tick)。 */
@@ -29,6 +29,21 @@ export function installShutdownHandlers(ctx) {
         closing = true;
         clearInterval(reaper);
         clearInterval(fleetReconcile.timer); // #261:契约 3 同族——收尾期不再有对账 tick 打向正在关闭的池
+        // #270 车2:契约 3 同族,且这一条最要紧——留存 tick 起飞的是跨十余张表的**破坏性**事务。
+        // 🔴 **四步的次序都是承重的**(codex 对抗复审 R1/R2 两轮各修一半,均验真后改):
+        //    停表 → 等在飞那一轮落地 → 让租 → `backend.close()`。
+        //  · `clearInterval` 只挡新 tick,不等当前这一轮;停表之后紧跟着就让租 ⇒ 新副本立刻接租,而本副本
+        //    还在删同一个域的数据 —— 一个由**正常** SIGTERM/SIGINT 稳定触发的双执行者窗口(R1);
+        //  · 而让租之后若不等就关池,这一轮会被从底下抽掉连接、半途而废(R2 —— 见下方 server.close 回调)。
+        //  · 进程若在整条链跑完之前就退了,租约不会被让出 ⇒ 下一位等满 TTL —— 那是**安全**的那一侧。
+        // 三步的产物是一条**可等的** promise —— 下面 `server.close()` 的回调必须等它落地才 `backend.close()`。
+        const retentionTeardown = retentionLane === undefined
+            ? Promise.resolve()
+            : retentionLane
+                .stop()
+                .then(() => releaseRetentionLease?.())
+                .then(() => undefined)
+                .catch(() => undefined);
         fleetReconcile.reconciler.stop(); // 摘总线订阅(观察者已停,扇出不该再喂它)
         parentWatch?.stop(); // #219:契约 3 同族——收尾期不再探父进程
         storeLiveProbe?.stop(); // #131-2:契约 3 同族——收尾期不再有探针 tick 打向正在关闭的池
@@ -60,7 +75,11 @@ export function installShutdownHandlers(ctx) {
         }
         void fleetClient?.stop(); // stop heartbeat + flush final usage window + best-effort DELETE deregistration
         server.close(() => {
-            void (backend ? backend.close() : Promise.resolve()).finally(() => process.exit(0));
+            // 🔴 `backend.close()` 必须排在留存收尾**之后**(codex 对抗复审 R2-[high],验真后修):
+            // 那一轮打的是跨十余张表的破坏性事务,把连接池从它底下抽掉 = 这一轮自己半途而废
+            // (比"让租早了"更重:让租早了只是**可能**双执行者,池被抽掉是必然的半成品)。
+            // 兜底仍在:下面那条 15s `finalExit` 无条件退出,一轮卡死的 sweep 拖不住停机。
+            void retentionTeardown.then(() => (backend ? backend.close() : Promise.resolve())).finally(() => process.exit(0));
         });
         // 对抗复查 B-4(HIGH):the exit above only fires after backend.close() SETTLES — a wedged pool teardown
         // (dead DB, hung socket) kept the "force-terminated" process alive indefinitely (the 10s closeAllConnections

package/dist/config-types.d.ts

@@ -29,6 +29,20 @@ export interface MemoryEmbedderConfig {
     /** 可选 Bearer(自托管 TEI/vllm/ollama 通常不需要;公有云端点需要)。 */
     apiKey?: string;
 }
+/**
+ * #270 §4 —— 托管留存的**灰度档**闭集。`as const` 数组是词表的唯一真源(config 解析、能力位、审计行
+ * 的 `mode` 列共读它);两词之外的值在启动期响亮拒 —— 一个拼错的档位静默落回 `audit-only` 会让运维
+ * 以为在删、其实没删,而拼成别的方向就是反过来那件更坏的事。
+ */
+export declare const RETENTION_MODES: readonly ["audit-only", "enforce"];
+export type RetentionMode = (typeof RETENTION_MODES)[number];
+/** #270 §3/§4 —— sweep lane 的节律与灰度档(语义与三问见 {@link ServiceConfigFlat.retentionSweep})。 */
+export interface RetentionSweepConfig {
+    /** `audit-only` = 照跑照判、只记 `audit_only` 行,**不调任何破坏性方法**;`enforce` = 真删。默认前者。 */
+    mode: RetentionMode;
+    /** sweep 节律(秒)。`0` = **关**(默认);租约 TTL = 2×本值。 */
+    intervalSec: number;
+}
 /** A sema-registry MCP server resolved to a core spec (env-NAME refs already → real values) plus the
  *  scenarios it applies to (empty = all). `resolveSpec` filters by scenario and passes `spec` to core. */
 export interface ScopedMcpServer {
@@ -704,6 +718,13 @@ export interface ServiceConfigFlat {
      * managed 店时,启动会打一条 `retention_policy_not_executed` 的响亮 warn。
      */
     retentionPolicy?: RetentionPolicy;
+    /**
+     * #270 车2 —— 托管留存 **sweep lane** 的两个旋钮(设计稿 `DESIGN-270-retention-lane.md` §3/§4)。
+     * `retentionPolicy` 说的是「保留多久」(一句声明),本格说的是「谁在什么节律上按那句话删」。
+     * **恒在场**(不是可选块):两根都有文档化的缺省,而缺省本身是一条要能被读出来的姿态 ——
+     * `{mode:"audit-only", intervalSec:0}` = 「lane 关着,真开起来也先只记账」。
+     */
+    retentionSweep: RetentionSweepConfig;
     /** Tool names that require operator approval before running (F4). Empty = no approval gate. */
     approvalRequire: string[];
     /** Principals allowed to act as OPERATORS on the F4 approval queue (`/v1/approvals`): list ANY
@@ -1284,7 +1305,7 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  三者都是 operator 在配置面写下的**治理声明**(与 autonomy/commandPolicy 同族),不是存储旋钮
  *  ——`retentionPolicy` 尤其容易被误归 store 组:它的消费点是 core 的启动期能力校验与将来的调度面,
  *  config 这一层它只是一句声明。 */
-export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "retentionPolicy" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
+export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
 export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes" | "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */

package/dist/config-types.js

@@ -1,2 +1,7 @@
-export {};
+/**
+ * #270 §4 —— 托管留存的**灰度档**闭集。`as const` 数组是词表的唯一真源(config 解析、能力位、审计行
+ * 的 `mode` 列共读它);两词之外的值在启动期响亮拒 —— 一个拼错的档位静默落回 `audit-only` 会让运维
+ * 以为在删、其实没删,而拼成别的方向就是反过来那件更坏的事。
+ */
+export const RETENTION_MODES = ["audit-only", "enforce"];
 //# sourceMappingURL=config-types.js.map

package/dist/config.d.ts

@@ -5,7 +5,8 @@ import type { ServiceConfig, ServiceConfigFlat, ServiceConfigGroups } from "./co
  *  every existing `from "./config.js"` importer compiles unchanged (pure-type consumers should prefer
  *  importing config-types.js directly — a type-only leaf, no loader baggage). */
 export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, MemoryEmbedderConfig, // #228:embedder 坐标(plugins/memory-embedder.ts 消费同一属主类型)
-A2aServeConfig, A2aServeSkill, } from "./config-types.js";
+A2aServeConfig, A2aServeSkill, RetentionMode, RetentionSweepConfig, } from "./config-types.js";
+export { RETENTION_MODES } from "./config-types.js";
 /** Parse the AUTONOMY env into a validated autonomy mode. Unset/empty → undefined (unmanaged → no extra
  *  tightening). An UNKNOWN value FAILS at startup rather than silently becoming a no-op (a typo'd `AUTONOMY=readonly`
  *  must not silently leave a deployment ungoverned — fail-loud, same discipline as numEnv). Exported so the HOT
@@ -186,6 +187,19 @@ export declare function findCcRuleFormNames(names: readonly string[]): Unmatchab
 export declare function findUnmatchableToolNames(names: readonly string[]): UnmatchableToolName[];
 /** {@link findUnmatchableToolNames} 的成句形——三条腿的文案同源(只有前缀/出口不同)。 */
 export declare function formatUnmatchableToolNames(source: string, bad: readonly UnmatchableToolName[]): string;
+/**
+ * design/170 件B/C/D —— 三条**部署治理声明**的 env 解析(auth 域的一段,fail-loud 全在这里)。
+ *
+ * 三条的词表真源都在 core(`ComplianceProfile` / `ComplianceCapability` / `LOCKED_KEY_REGISTRY`),本函数
+ * 只负责「env 文本 → 闭集值」这一步,并且**每一步坏值都拒启**:这三根旋钮全在安全/治理轴上,一个静默
+ * 不生效的档位或一个拼错的锁键,是「以为在管、其实没管」——比没配更贵(#210 A 档 + design/170 §3.4)。
+ *
+ * 半配也拒:`COMPLIANCE_ADDITIONAL_DENIES` 没有 profile 可收紧时是一句无处安放的话,静默丢掉它等于
+ * 让 operator 以为多禁了一条(与 `MEMORY_EMBEDDER_*` 的半配拒启同族)。
+ */
+/** #270 车2 —— sweep 节律的上界(秒)。`setInterval` 的 delay 是 32 位有符号毫秒(2^31-1);越界会被
+ *  Node **重置成 1ms**,理由与拒启判据见调用点。导出供判据与文档单点引用。 */
+export declare const RETENTION_SWEEP_INTERVAL_MAX_SEC: number;
 /** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */
 export declare const CONFIG_GROUP_KEYS: {
     readonly [G in keyof ServiceConfigGroups]: readonly (keyof ServiceConfigFlat)[];

package/dist/config.js

@@ -8,6 +8,8 @@ import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { isV2ScopeKey } from "./memory-scope.js"; // A-002.4: v2 scope 前缀词表的单一属主(纯谓词,无反向依赖)
 import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js"; // P1-2: 方言词表叶模块(config 不得值引 capabilities 层)
+import { RETENTION_MODES } from "./config-types.js"; // #270 车2:留存灰度档的闭集词表(值导入 —— config-types 是纯叶,无装载环)
+export { RETENTION_MODES } from "./config-types.js";
 function csv(name) {
     return (process.env[name] ?? "")
         .split(",")
@@ -1613,8 +1615,11 @@ function parseMemoryDomain(ctx) {
  * 半配也拒:`COMPLIANCE_ADDITIONAL_DENIES` 没有 profile 可收紧时是一句无处安放的话,静默丢掉它等于
  * 让 operator 以为多禁了一条(与 `MEMORY_EMBEDDER_*` 的半配拒启同族)。
  */
+/** #270 车2 —— sweep 节律的上界(秒)。`setInterval` 的 delay 是 32 位有符号毫秒(2^31-1);越界会被
+ *  Node **重置成 1ms**,理由与拒启判据见调用点。导出供判据与文档单点引用。 */
+export const RETENTION_SWEEP_INTERVAL_MAX_SEC = Math.floor((2 ** 31 - 1) / 1000);
 function parseGovernanceDeclarations() {
-    const out = {};
+    const out = { retentionSweep: { mode: "audit-only", intervalSec: 0 } };
     /**
      * codex 对抗复审 F1(high,验真后采纳)——**「未定义」与「定义了但是空」必须分开**。
      *
@@ -1668,6 +1673,42 @@ function parseGovernanceDeclarations() {
     if (retentionRaw !== undefined) {
         out.retentionPolicy = { maxAgeDays: parseNumOrFailNonNegative("RETENTION_MAX_AGE_DAYS", retentionRaw) };
     }
+    // ── #270 车2:执行面的两根旋钮(策略说"保留多久",这两根说"谁在什么节律上按它删")。
+    //
+    // 🔴 灰度档是**闭集**,拼错即拒(#157 词表纪律)。静默落回 `audit-only` 会让运维以为在删而其实没删;
+    //    静默落成另一档就是反方向那件更坏的事。词表从 config-types 的 `RETENTION_MODES` 单点读,
+    //    能力位/审计行的 `mode` 列与它同源。
+    const modeRaw = requireNonBlank("RETENTION_MODE", process.env.RETENTION_MODE);
+    if (modeRaw !== undefined) {
+        if (!RETENTION_MODES.includes(modeRaw)) {
+            throw new Error(`RETENTION_MODE must be one of ${RETENTION_MODES.join("|")}, got ${JSON.stringify(modeRaw)} — a misspelled rollout stage ` +
+                `would run as the DEFAULT stage, i.e. an operator who wrote "enforce" with a typo would watch a retention lane that ` +
+                `deletes nothing and believe it is deleting (the reverse typo is worse still).`);
+        }
+        out.retentionSweep.mode = modeRaw;
+    }
+    // 🔴 节律必须是**非负整数秒**:`Math.round` 掉一个小数会把"配错了"变成"配得有点怪但跑起来了",而
+    //    这条腿是每小时一拍的后台删除活 —— `0.5` 只可能是把毫秒/分钟当成秒写的手滑。`0` 是显式关(默认)。
+    const sweepRaw = requireNonBlank("RETENTION_SWEEP_INTERVAL_SEC", process.env.RETENTION_SWEEP_INTERVAL_SEC);
+    if (sweepRaw !== undefined) {
+        const n = parseNumOrFailNonNegative("RETENTION_SWEEP_INTERVAL_SEC", sweepRaw);
+        if (!Number.isInteger(n)) {
+            throw new Error(`env RETENTION_SWEEP_INTERVAL_SEC=${n} must be a whole number of seconds (0 = the lane is off)`);
+        }
+        // 🔴 上界 = `setInterval` 的 32 位 delay 上限(codex 对抗复审 R1-[high],验真属实)。
+        // 病:delay 超过 2^31-1 ms 时 Node 打一条 `TimeoutOverflowWarning` 并把它**重置成 1ms** —— 一个想
+        // 「约 25 天扫一次」的 enforce 部署于是变成几乎连续扫库,而这条腿每一拍发的都是跨十余张表的
+        // **破坏性**事务。夹取在这里同样是错的补偿(悄悄改小 = 换一个运维没要的策略),拒启才是
+        // ——与 `RETENTION_MAX_AGE_DAYS` 那根「删数据的旋钮不许 NaN 流通」同一条判据。
+        // 顺带这条上界也保住了 TTL 算术:`intervalSec*1000*RETENTION_LEASE_TTL_FACTOR + Date.now()` 在
+        // 本上界内离 `Number.MAX_SAFE_INTEGER` 还差九个数量级。
+        if (n > RETENTION_SWEEP_INTERVAL_MAX_SEC) {
+            throw new Error(`env RETENTION_SWEEP_INTERVAL_SEC=${n} exceeds ${RETENTION_SWEEP_INTERVAL_MAX_SEC} (setInterval's 32-bit delay ceiling, ~24.8 days) — ` +
+                `Node would silently RESET an overflowing delay to 1ms, turning an "occasional" retention sweep into a nearly continuous stream of ` +
+                `destructive transactions. Pick an interval at or below the ceiling.`);
+        }
+        out.retentionSweep.intervalSec = n;
+    }
     return out;
 }
 /** 域:auth(身份/凭证/绑址)—— service token 面、CORS、principal 头与开关、JWT 锚、autonomy、绑址。 */
@@ -2283,7 +2324,7 @@ const MEMORY_GROUP_KEYS = [
 ];
 const AUTH_GROUP_KEYS = [
     "authToken", "authTokens", "allowUnauthedWrites", "corsOrigins", "principalHeader", "requirePrincipal", "autonomy",
-    "commandPolicy", "compliancePosture", "lockedConfigKeys", "retentionPolicy",
+    "commandPolicy", "compliancePosture", "lockedConfigKeys", "retentionPolicy", "retentionSweep",
     "operatorPrincipals", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
     "principalJwtMaxTtlSec", "bindHost", "bindHostSource",
 ];

package/dist/http/routes/capabilities.js

@@ -8,6 +8,22 @@ import { resolveStreamApprovalGate } from "../../tool-approval.js";
 import { projectMemoryEngineCapability } from "../../memory-posture.js";
 import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import { gatedPrincipal } from "../principal-gate.js";
+/**
+ * #270 车2 —— 能力位 `retention` 的**唯一**判据(`{mode, maxAgeDays} | null`)。
+ *
+ * 谓词为什么可以只看 config 而不合取"执行器在场"(「说 yes ⟺ 面真能用」的结构性论证):
+ * `intervalSec > 0` 且没有真执行器的那台**根本起不来** —— `boot/retention-lane.ts` 的
+ * `assertRetentionLaneWirable` 在 boot 期就拒了(policy 缺 / 执行器缺 / 有店声明 "none" 三条臂,
+ * 且**不看 locked**)。所以在一个已经在应答 HTTP 的进程里,那个合取式恒真;再写一遍只会让读者以为
+ * 这里还有第二道门。policy 在场仍显式合取:它是 `maxAgeDays` 那一格的来源。
+ */
+function retentionAdvertisement(config) {
+    const sweep = config.retentionSweep; // 见调用点注:遗留双重断言 config 可能真缺这一格
+    const policy = config.retentionPolicy;
+    if (sweep === undefined || sweep.intervalSec <= 0 || policy === undefined)
+        return null;
+    return { mode: sweep.mode, maxAgeDays: policy.maxAgeDays };
+}
 export async function handleCapabilities(req, res, url, ctx) {
     const miss = { fell: false };
     await handleCapabilitiesBody(req, res, url, ctx, miss);
@@ -405,6 +421,20 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             // ⚠️ 辖域=**列举面**:名册回的是 content-free 投影(handle/name/agentType/status/三个时间戳);
             // 要子代产物正文走 `/v1/runs/:id/subagents/:handle/output`(那条口有它自己的谓词 `subagentOutput`)。
             agentRoster: Boolean(deps.backgroundAgentStore),
+            // #270 车2:**托管留存**的部署事实(设计稿 §7 能力位)。`null` = sweep lane 关着(缺省);
+            // 在场 = `{mode, maxAgeDays}` —— 两格都是**部署事实不是秘密**(策略数值本来就要告诉用户"你的
+            // 数据留多久"),消费端(web admin 面 / test)按位渲染。
+            //
+            // 🔴 谓词为什么可以只看 config 而不合取"执行器在场"(「说 yes ⟺ 面真能用」的结构性论证):
+            // `intervalSec > 0` 且没有真执行器的那台**根本起不来** —— `boot/retention-lane.ts` 的
+            // `assertRetentionLaneWirable` 在 boot 期就拒了(policy 缺 / 执行器缺 / 有店声明 "none" 三条臂,
+            // 且**不看 locked**)。所以在一个已经在应答 HTTP 的进程里,这个合取式恒真;再写一遍只会让读者
+            // 以为这里还有第二道门。policy 缺席仍显式合取:它是那句 `{mode, maxAgeDays}` 里第二格的来源。
+            // ⚠️ `retentionSweep` 在类型上是**必填**(`loadConfig` 恒产出它),这里仍显式判在场:本仓还有一批
+            // 遗留测试用 `as unknown as ServiceDeps["config"]` 手搓 config 字面量 —— 那种双重断言把字段检查
+            // 整个关掉,于是一个必填字段在它们手里可以真的缺席。缺席臂的方向是**保守**的(`null` = 本部署
+            // 没有托管留存),不是放宽,所以它不是一处静默 fail-open;生产路径根本到不了这一臂。
+            retention: retentionAdvertisement(deps.config),
             sessionList: Boolean(deps.sessionStorage?.listSessions ?? deps.runStore?.listSessions),
             sessionSearch: Boolean(deps.sessionStorage?.listSessions ?? deps.runStore?.listSessions), // GET /v1/sessions?q= (all lister backends carry it)
             sessionFork: Boolean(deps.sessionStorage?.fork),

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

@@ -7,5 +7,18 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
+/**
+ * #271 件3(#275 A2 车立的欠账,[4163] 我方认领)—— `GET /v1/memory/export` 的 keyset 分页上限。
+ *
+ * 在此之前本面是**整盘导出**:一个几千条目的盘就是一个几 MB 的响应体,壳侧(sema-web 只读页)
+ * 无从分次要 —— 那是它真实撞到的天花板。分页是 **additive** 的:`?limit=` 缺席 ⇒ 旧契约逐字不变
+ * (全量数组、响应键一个不多),所以现行消费端零破坏;要分页的调用方自己带 `limit` 进来。
+ *
+ * ⚠️ 诚实记档:本面的分页封的是**回体**(wire 天花板),不是 DB 读 —— reader
+ * (`exportMemoryScope`)仍是整 scope 一次读出。真正的下推需要 core 的 `MemoryBackend.listHeaders`
+ * 长出分页参数(上游接缝,源头修复纪律:不在本层用别的口硬凑)。壳侧的痛点(响应体大小/首屏)由
+ * 本形解决,库侧的读放大另案。
+ */
+export declare const MEMORY_EXPORT_MAX_LIMIT = 500;
 export declare function handleMemoryPolicy(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 //# sourceMappingURL=memory-policy.d.ts.map

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

@@ -3,6 +3,40 @@ import { parseMemorySyncRequest } from "../../memory-sync.js";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 const ORG_PREFIX = "org:";
+/**
+ * #271 件3(#275 A2 车立的欠账,[4163] 我方认领)—— `GET /v1/memory/export` 的 keyset 分页上限。
+ *
+ * 在此之前本面是**整盘导出**:一个几千条目的盘就是一个几 MB 的响应体,壳侧(sema-web 只读页)
+ * 无从分次要 —— 那是它真实撞到的天花板。分页是 **additive** 的:`?limit=` 缺席 ⇒ 旧契约逐字不变
+ * (全量数组、响应键一个不多),所以现行消费端零破坏;要分页的调用方自己带 `limit` 进来。
+ *
+ * ⚠️ 诚实记档:本面的分页封的是**回体**(wire 天花板),不是 DB 读 —— reader
+ * (`exportMemoryScope`)仍是整 scope 一次读出。真正的下推需要 core 的 `MemoryBackend.listHeaders`
+ * 长出分页参数(上游接缝,源头修复纪律:不在本层用别的口硬凑)。壳侧的痛点(响应体大小/首屏)由
+ * 本形解决,库侧的读放大另案。
+ */
+export const MEMORY_EXPORT_MAX_LIMIT = 500;
+/** 游标 = 条目 `id` 的不透明 base64url(声明序=id 升序;id 是 entry 平面的 PK ⇒ 唯一,单键即全序,
+ *  不像 roster 的 `(spawnedAt, handle)` 需要 tiebreak)。`before` / `nextBefore` 是本仓分页的
+ *  **同一套词**(roster 先例):调用方只把上一页的 `nextBefore` 原样回传,不解读内容。 */
+function encodeExportCursor(c) {
+    return Buffer.from(JSON.stringify(c)).toString("base64url");
+}
+function decodeExportCursor(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(raw, "base64url").toString());
+    }
+    catch (err) {
+        return { ok: false, why: `not decodable base64url JSON (${err instanceof Error ? err.name : "unknown error"})` };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { ok: false, why: "cursor payload is not an object" };
+    const { id } = parsed;
+    if (typeof id !== "string" || id.length === 0)
+        return { ok: false, why: "cursor payload lacks a non-empty `id`" };
+    return { ok: true, cursor: { id } };
+}
 /** 本面是否让目录参与判决。闭集穷举 switch:新增第三个模式是**编译**错误,不会静默落进某个默认臂
  *  ——这条门在授权轴上,静默默认值正是它不许有的东西。 */
 function directoryDecidesThisFace(mode) {
@@ -100,16 +134,59 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.memory_store_required", "memory export requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
             return;
         }
-        const scope = new URL(req.url ?? "", "http://x").searchParams.get("scope"); // route-level `url` is query-stripped
+        const q = new URL(req.url ?? "", "http://x").searchParams; // route-level `url` is query-stripped
+        const scope = q.get("scope");
         if (!scope) {
             sendError(res, 400, "request.query_invalid", "missing ?scope=<key>");
             return;
         }
         if (sendScopeGateRefusal(res, await gateMemoryScope(deps, principal, scope, "read")))
             return;
+        // 分页参数的验型排在**属主门之后**(与 roster 的「先门后参」同序):越界者恒 404,再坏的查询串
+        // 也不许把它换成 400 —— 那就是一格「这个 scope 存在」的信号。
+        const limitRaw = q.get("limit");
+        if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= MEMORY_EXPORT_MAX_LIMIT)) {
+            sendError(res, 400, "request.query_invalid", `limit must be a decimal integer in 1..${MEMORY_EXPORT_MAX_LIMIT}`);
+            return;
+        }
+        const beforeRaw = q.get("before");
+        // 🔴 `before` 必须与 `limit` 同行(codex 对抗复审 H2):否则「缺席 limit = 旧契约逐字不变」有两个
+        // 破口 —— 合法游标会让调用方拿到**过滤过的**子集却按全量读,坏游标会把旧行为的 200 全量变 400。
+        // 取**响亮拒**而不是「静默忽略 before」:后者让「分页时忘了带 limit」的调用方悄悄收到整盘,
+        // 正是本件要消灭的那个天花板。两个参数都不带的旧调用**一个字节都没碰到这条腿**。
+        if (beforeRaw !== null && limitRaw === null) {
+            sendError(res, 400, "request.query_invalid", "before requires an explicit limit — without one this endpoint returns the whole scope by contract");
+            return;
+        }
+        const decoded = beforeRaw === null ? undefined : decodeExportCursor(beforeRaw);
+        if (decoded !== undefined && !decoded.ok) {
+            sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+            return;
+        }
         try {
             const entries = await deps.memoryExport(scope);
-            sendJson(res, 200, { scope, exportedAt: new Date().toISOString(), entries });
+            // 🔴 缺席 limit = **旧契约逐字不变**:同一个数组、同一个顺序、响应键一个不多(sema-web 现行
+            // 消费零破坏)。分页面才排序/切片 —— 两条腿在真部署上给出同一个序(reader 是
+            // exportMemoryScope,两方言读面都 ORDER BY id),但冻结面不靠"碰巧相同",它就不动。
+            if (limitRaw === null) { // `before` 无 limit 已在上面 400 掉 ⇒ 这里等价于「两个分页参数都不在场」
+                sendJson(res, 200, { scope, exportedAt: new Date().toISOString(), entries });
+                return;
+            }
+            // 声明序 = **id 升序**(entry 平面的既有确定序;id 是 PK ⇒ 唯一,单键游标无同值 tiebreak 洞)。
+            // 本面自己排,不继承 reader 的顺序:游标的正确性(无重无漏)是本面的承诺,不是上游的巧合。
+            const sorted = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            const after = decoded?.ok === true ? sorted.filter((e) => e.id > decoded.cursor.id) : sorted;
+            const page = after.slice(0, Number(limitRaw)); // limitRaw 在此必然在场且已验型(上面两道门)
+            const last = page[page.length - 1];
+            const hasMore = last !== undefined && after.length > page.length;
+            sendJson(res, 200, {
+                scope,
+                exportedAt: new Date().toISOString(),
+                entries: page,
+                // `truncated` 与 `nextBefore` 同生同灭,但**两个都要有**:前者回答「这是全量吗」(缺席 limit
+                // 的旧契约给的就是全量,所以带 limit 时必须显式说不是),后者回答「从哪儿接着要」。
+                ...(hasMore ? { truncated: true, nextBefore: encodeExportCursor({ id: last.id }) } : {}),
+            });
         }
         catch (err) {
             deps.logger?.warn?.("memory_export_failed", { scope, err: String(err) });

package/dist/http/routes/retention-ops.d.ts

@@ -0,0 +1,36 @@
+/**
+ * #270 车2 —— **托管留存的 operator 治理面**(设计稿 `docs/DESIGN-270-retention-lane.md` §5/§6)。
+ *
+ *   · `PUT    /v1/ops/retention/holds/:domain` —— 放置 legal hold;
+ *   · `DELETE /v1/ops/retention/holds/:domain` —— 解除;
+ *   · `GET    /v1/ops/retention/audit?domain=&limit=&before=` —— 审计读面(keyset 分页)。
+ *
+ * 形态与 `routes/adoption.ts` 同族:**部署级动作**,不是常驻业务面 ⇒ billable=false(零模型工作)、
+ * operator-only、没有 SQL 后端的部署上诚实 501。门序也逐字同它:身份(401)→ 授权(403)→ 能力(501)
+ * → 验型(400)——授权在能力之前,一个够不着任何东西的调用方不该从「有没有 SQL 后端」上读出部署形态。
+ *
+ * ── 🔴 hold 的写形是**唯一**的一条纪律(车1 交接件②,逐字)────────────────────────────────────
+ * 放置与解除都走 `setHold`(同一 PK 的 upsert 改 `held` 列),**绝不 INSERT/DELETE 行**。
+ * `retention_hold` 的行同时是**域级互斥哨兵**:车1 的三条破坏性事务首步锁读它,而
+ * `SELECT … FOR UPDATE` **锁不住一条不存在的行**(TiDB 无 gap lock;PG READ COMMITTED 同病)。
+ * 删掉行 = 下一个 PUT 与一条在飞的删除事务又能同时读到「没有 hold」⇒ operator 拿到成功回执之后数据
+ * 仍被删。本模块因此**结构上**够不着删行:它拿到的 `RetentionLaneStore` 接口上根本没有那个方法。
+ *
+ * ── 域(domain)的两个边界 ──────────────────────────────────────────────────────────────────
+ *  · **无主桶**:域键 `""`(`session_meta.owner` 为 NULL/空串的那一桶)在单用户部署里是**唯一**的域。
+ *    路径段允许为空(`/v1/ops/retention/holds/`)正是为了它 —— 不给它一条路 = 单用户部署根本放不了
+ *    legal hold,而那是这条面最该管用的部署形态之一。这也是为什么路由正则是 `([^/]*)` 而不是 `+`。
+ *  · **列宽**:`retention_hold.domain` 是 `VARCHAR(190)`。超宽在**铸行之前**拒(与 adoption 的
+ *    `checkAdoptionWidths` 同一条判据):一次静默截断会让 hold 落在一个**别的**域上。
+ *
+ * ── 审计行为什么放置/解除都要写 ────────────────────────────────────────────────────────────
+ * hold 本身就是一次留存治理动作,不留痕的 hold 是审计漏洞(设计稿 §5 逐字)。行**每次成功调用都写**,
+ * 而不是"只在状态真的翻转时写":审计表记的是**发生过的动作**(operator 在某时刻按了这个按钮),不是
+ * 状态机的边。一次对已冻结域的重复 PUT 同样是一次需要留痕的操作。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleRetention(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=retention-ops.d.ts.map

package/dist/http/routes/retention-ops.js

@@ -0,0 +1,190 @@
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { RETENTION_AUDIT_DEFAULT_LIMIT, RETENTION_AUDIT_MAX_LIMIT } from "../../plugins/retention-lane-store-sql.js";
+/** hold 路径。**`*` 不是 `+`**:空段 = 无主桶(见文件头「域的两个边界」)。 */
+const HOLD_RE = /^\/v1\/ops\/retention\/holds\/([^/]*)$/;
+const AUDIT_PATH = "/v1/ops/retention/audit";
+/** `retention_hold.domain` / `retention_audit.domain` 的列宽(车1 的 DDL:`VARCHAR(190)`)。 */
+const DOMAIN_MAX_CHARS = 190;
+/** hold 备注的上界。`note` 列是 TEXT(不会截断),但一个无界的 operator 输入不该原样进一张**追加式**
+ *  的治理表 —— 4000 字符足够写清案号与出处,再长的属于工单系统。 */
+const NOTE_MAX_CHARS = 4000;
+/** operator 面的**唯一**授权文案(三条路由同受众、同理由 ⇒ 同一句;分成三句只会让 freeze 表长三倍
+ *  而消费端读到的判据一模一样)。 */
+const OPERATOR_ONLY_MESSAGE = "managed-retention governance is an operator-only deployment action";
+/**
+ * 审计游标 = `{id}` 的不透明 base64url。
+ *
+ * 🔴 排序键是**自增 `id` 单列**,不是 roster 那样的二元组:`id` 本身全序且唯一,二元组存在的全部理由
+ * (同毫秒兄弟行无 tiebreak ⇒ 漏页/重页)在这张表上结构性不存在。游标形仍照 roster 逐字同姿势
+ * (base64url JSON / 判别式解码 / 400 带**类名** detail)—— 消费端跨端点的游标处理代码因此同形。
+ */
+function encodeCursor(c) {
+    return Buffer.from(JSON.stringify(c)).toString("base64url");
+}
+function decodeCursor(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(raw, "base64url").toString());
+    }
+    catch (err) {
+        // 只带错误的**类名**,不回显 payload 片段(与 agents-roster 的同款纪律:被误粘进查询串的凭据
+        // 不该经由错误文案再走一圈)。
+        return { ok: false, why: `not decodable base64url JSON (${err instanceof Error ? err.name : "unknown error"})` };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { ok: false, why: "cursor payload is not an object" };
+    const { id } = parsed;
+    if (typeof id !== "number" || !Number.isInteger(id) || id < 0)
+        return { ok: false, why: "cursor payload lacks a non-negative integer `id`" };
+    return { ok: true, id };
+}
+export async function handleRetention(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleRetentionBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleRetentionBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    const holdMatch = req.method === "PUT" || req.method === "DELETE" ? HOLD_RE.exec(path) : null;
+    const isAudit = req.method === "GET" && path === AUDIT_PATH;
+    if (!holdMatch && !isAudit) {
+        miss.fell = true;
+        return;
+    }
+    // 门序 = operator 面的既有口径(routes/adoption.ts 逐字):身份 → 授权 → 能力 → 验型。
+    const principal = gatedPrincipal(req, deps.config); // direct-door safe:验证过的身份,不是可伪造的头
+    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", OPERATOR_ONLY_MESSAGE);
+        return;
+    }
+    const store = deps.backend?.retentionLane?.();
+    if (!store) {
+        // ⚠️ 文案里用**单引号**写 `retention:'none'`:文案冻结门的字面提取器不认带反斜杠转义的双引号串
+        //    (`"([^"\n\\]*)"`),一个 `\"` 会让这条站点对那道门隐形 —— 那不是"过了门",是绕过门。
+        sendError(res, 501, "capability.retention_store_required", "managed retention requires a SQL store backend (DB_BACKEND=mysql|pg) — the local/file backend declares retention:'none' and holds nothing to govern");
+        return;
+    }
+    if (holdMatch) {
+        await handleHold(req, res, ctx, store, holdMatch[1] ?? "", principal);
+        return;
+    }
+    await handleAuditRead(req, res, store);
+}
+/** 放置(PUT)/ 解除(DELETE)—— 两支共用一条 upsert(见文件头的唯一纪律)。 */
+async function handleHold(req, res, ctx, store, rawDomain, principal) {
+    const domain = ctx.helpers.safeDecode(rawDomain);
+    if (domain === null) {
+        // 复用既有的 `request.id_invalid`(sessions/attachments/adoption 同族),不为一条新路由铸第二个
+        // 同义码 —— 附录 A 判据②:只有消费端真会分支时才铸新码。
+        sendError(res, 400, "request.id_invalid", "invalid retention domain segment");
+        return;
+    }
+    if (domain.length > DOMAIN_MAX_CHARS) {
+        sendError(res, 400, "request.field_invalid", "the retention domain does not fit the hold table's identity column", {
+            detail: `domain is ${domain.length} characters; retention_hold.domain holds at most ${DOMAIN_MAX_CHARS}`,
+        });
+        return;
+    }
+    const held = req.method === "PUT";
+    let note;
+    if (held) {
+        // 体是**可选**的(`PUT …/holds/acme` 不带体是合法的最小放置)。空体走 `{}`。
+        let raw;
+        try {
+            raw = await ctx.helpers.readJson(req);
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        if (raw !== undefined && raw !== null && raw !== "") {
+            if (typeof raw !== "object" || Array.isArray(raw)) {
+                sendError(res, 400, "request.body_shape", "invalid retention hold body — expected an object with an optional `note` string");
+                return;
+            }
+            const n = raw.note;
+            if (n !== undefined) {
+                if (typeof n !== "string") {
+                    sendError(res, 400, "request.body_shape", "invalid retention hold body — expected an object with an optional `note` string");
+                    return;
+                }
+                if (n.length > NOTE_MAX_CHARS) {
+                    // 铸行之前拒:静默截断会把一条**被改写过的**审计事实写进一张追加式的表。
+                    sendError(res, 400, "request.field_invalid", "the retention hold note is longer than this face accepts", {
+                        detail: `note is ${n.length} characters; the limit is ${NOTE_MAX_CHARS}`,
+                    });
+                    return;
+                }
+                note = n;
+            }
+        }
+    }
+    const nowMs = Date.now();
+    const placedBy = principal ?? "operator"; // 单用户 turnkey 部署没有 principal 这个概念(见 explicitOperatorOk)
+    // 🔴 状态变更与治理审计行走**同一个事务**(codex 对抗复审 R1-[high],验真后修)。两次独立提交下,
+    // 第二步失败会留下一次**无审计的状态变更** —— DELETE 那一支尤其重:冻结已解除、sweep 从下一拍起就能
+    // 删这个域的数据,而账上没有任何 `hold_released` 行说明是谁在什么时候解的。
+    // `mode`/`policyDays` 记的是**这一刻的部署事实**:一条 hold 行不带策略档,事后没人说得清"当时是在
+    // 什么留存策略下冻结的"。`fencingToken` 诚实留空 —— 它只属于 sweep 轮次,operator 动作不在任何一轮里。
+    await store.setHoldAudited({
+        domain,
+        held,
+        ...(held ? { placedBy } : {}),
+        ...(note !== undefined ? { note } : {}),
+        nowMs,
+        audit: {
+            domain,
+            action: held ? "hold_placed" : "hold_released",
+            mode: ctx.deps.config.retentionSweep?.mode ?? "audit-only",
+            policyDays: ctx.deps.config.retentionPolicy?.maxAgeDays ?? 0,
+            fencingToken: null,
+            deleted: 0,
+            skipped: 0,
+            tombstones: 0,
+        },
+    });
+    sendJson(res, 200, held ? { domain, held: true, placedBy, placedAtMs: nowMs } : { domain, held: false });
+}
+/** 审计读面(keyset 分页;窗与游标语义见文件头)。 */
+async function handleAuditRead(req, res, store) {
+    const q = new URL(req.url ?? "", "http://x").searchParams;
+    const limitRaw = q.get("limit");
+    if (limitRaw !== null && !(/^[0-9]+$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= RETENTION_AUDIT_MAX_LIMIT)) {
+        sendError(res, 400, "request.query_invalid", `limit must be a decimal integer in 1..${RETENTION_AUDIT_MAX_LIMIT}`);
+        return;
+    }
+    const limit = limitRaw === null ? RETENTION_AUDIT_DEFAULT_LIMIT : Number(limitRaw);
+    const beforeRaw = q.get("before");
+    const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
+    if (decoded !== undefined && !decoded.ok) {
+        // 文案冻结在 wire 上(api-error-text-freeze 的一行);`detail` 是 additive 的**为什么**,
+        // 供调用方自诊(它描述的是调用方自己传进来的串,零跨租户信息)。
+        sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+        return;
+    }
+    const domainRaw = q.get("domain");
+    if (domainRaw !== null && domainRaw.length > DOMAIN_MAX_CHARS) {
+        sendError(res, 400, "request.query_invalid", `domain must be at most ${DOMAIN_MAX_CHARS} characters`);
+        return;
+    }
+    // 多取一行用来判「还有没有下一页」——不进结果。`hasMore` 因此是**事实**而不是"limit 满了就猜有"。
+    const scanned = await store.listAudit({
+        ...(domainRaw !== null ? { domain: domainRaw } : {}),
+        limit: Math.min(limit + 1, RETENTION_AUDIT_MAX_LIMIT + 1),
+        ...(decoded?.ok === true ? { beforeId: decoded.id } : {}),
+    });
+    const hasMore = scanned.length > limit;
+    const rows = hasMore ? scanned.slice(0, limit) : scanned;
+    const last = rows[rows.length - 1];
+    sendJson(res, 200, {
+        rows,
+        ...(hasMore && last !== undefined ? { nextBefore: encodeCursor({ id: last.id }) } : {}),
+    });
+}
+//# sourceMappingURL=retention-ops.js.map