@sema-agent/server 7.10.0 → 7.12.0

package/dist/governance-ask-marks.js

@@ -1,13 +1,19 @@
 /**
  * [2942]/[2943] `governanceForced` 的**判定缝** —— operator 治理层产的 ask 在 server 进程内的标记通道。
  *
- * 🔴 为什么需要一条 out-of-band 通道(侦察结论,亲验装树 core 5.16.x dist):
- * `PermissionResult.decisionReason`(`"rule" | "mode" | "hook" | "safety" | "classifier"`)**到不了帧铸点**。
+ * 🔴 为什么需要一条 out-of-band 通道(侦察结论,亲验装树 core dist;5.16.x 首次落笔,5.23.0 复核仍成立):
+ * `PermissionResult.decisionReason`(闭集,词表以 core 的 `DecisionReason` 为准 —— 本文**刻意不复述**那
+ * 张表:复述出来的词表会随 core 加员静默过期,而这段话的论点与表里有几个词无关)**到不了帧铸点**。
  * core 在 `dist/core/runner/prepare-task.js` 的 ask 铸造点(`resolveAsk({...})`,三处继承臂 + 主臂)只把
  * `toolName / toolCallId / args / preview / message / askSourceIdentity() / riskAxesOf() / requiresRealApproval`
  * 装进 `AskRequest`;`decisionReason` 连同整个 `PermissionResult` 一起留在 core 内部。`AskRequest` 的类型面
  * (`dist/core/tool-policy.d.ts:78`)也确认没有这个键。所以「映射 decisionReason ⇒ governanceForced」这条
  * 缝在**当前 core 上不存在**——它不是没接线,是没有这个字段可读。
+ * ([3372] 提货批复核)core 5.23.0 给这个闭集加了 `org_rule` / `org_unavailable` 两个**治理来源**的词
+ * (design/182 org 层)。这看着像是本表终于有了上游判据,其实**不是**:①`AskRequest` 的类型面在 5.23.0
+ * 上逐字未变,那两个词仍然到不了帧铸点(缝还是不存在);②即便够得着,它们说的是**组织**发布的快照,
+ * 与本键的语义(**本部署运维治理层**产的 ask)不是一回事,直接映射会把两种来源混成一个标记。本仓无
+ * org 层装配口(`ToolGateInput.orgRules` 无声明点),该臂当前不可达。
  *
  * 另一侧同样不可用:`riskAxes.irreversible` 在 shellGate 上场时对**每一次** shell 调用都为真(core
  * `prepare-task.js:1620-1631` 无条件 `irreversibilityTier.set("Bash"/"Monitor", …)`),与「这只 ask 是谁

package/dist/http/route-ctx.d.ts

@@ -15,7 +15,7 @@
  * 本文件对 server.ts 的引用一律 `import type`(tsc 擦除,非装载边)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { TaskStream, TaskSpec, TaskResult, QuestionAnswer, CheckpointToken, ResumeOutcome, Runner } from "@sema-agent/core";
+import type { ApprovalSettledBy, TaskStream, TaskSpec, TaskResult, QuestionAnswer, CheckpointToken, ResumeOutcome, Runner } from "@sema-agent/core";
 import type { FlatServiceDeps, RequestAuth } from "./server.js";
 import type { TaskRequestBody, DecideBinding } from "./wire-types.js";
 import type { IdempotencyCache } from "./idempotency.js";
@@ -120,8 +120,11 @@ export interface RouteLegs {
     prepareSpec(req: IncomingMessage, res: ServerResponse): Promise<PreparedTaskSubmission | null>;
     /** 同步腿的终局记账(计费/配额/指标),tasks 域用。 */
     finalizeTaskResult(result: TaskResult, principal: string | undefined, objective: string, sessionId: string | undefined): void;
-    /** approvals 决策腿:session → pending checkpoint → markResuming CAS → 驱动续跑。 */
-    resumeCheckpoint(sessionId: string, decision: "approve" | "deny", reason: string | undefined, req?: IncomingMessage, answer?: QuestionAnswer, binding?: DecideBinding, onResumeCommitted?: (overrideSessionId?: string) => Promise<void>): Promise<{
+    /** approvals 决策腿:session → pending checkpoint → markResuming CAS → 驱动续跑。
+     *  `settledBy` = **这次结算的出处**(core `ApprovalSettledBy`),必填:本腿有两个调用方(HTTP
+     *  `/decide` = 人;内部 D-D SLA deny-sweep = 窗到期),而函数内部分辨不出谁在叫它 —— 必填参数把
+     *  「漏报出处」变成编译错,不是一条下游把「没人答」渲染成「有人拒」的静默假出处。 */
+    resumeCheckpoint(sessionId: string, decision: "approve" | "deny", reason: string | undefined, settledBy: ApprovalSettledBy, req?: IncomingMessage, answer?: QuestionAnswer, binding?: DecideBinding, onResumeCommitted?: (overrideSessionId?: string) => Promise<void>): Promise<{
         status: number;
         body: object;
     }>;

package/dist/http/routes/adoption.d.ts

@@ -0,0 +1,26 @@
+/**
+ * design/183 §4.3 —— **收编面**(operator lane):`POST /v1/adoption` 发起、`GET /v1/adoption/:id` 读状态。
+ *
+ * 形态:一次性的**部署级动作**,不是常驻业务面 —— 所以它 billable=false(零模型工作)、operator-only、
+ * 且在没有 SQL 后端的部署上诚实 501(收编重绑的是多租身份轴,local 后端根本没有那个轴)。
+ *
+ * ── 三条拒的分家(183 §7.3 拒绝可判别)──────────────────────────────────────────────────────────
+ *  · `adoption.source_already_bound` (409):同一个源已绑到**别的**目的地 = 二次收编/多租转让,
+ *    183 D7 明确拒,非本协议射程。与「已收编回执」不同形 —— 后者是 200。
+ *  · `adoption.destination_conflict` (409):目的地侧已有与源侧重叠的逻辑键。**响应列出冲突表族**,
+ *    运维据此知道该去清理哪张表;源/目的地两侧字节零变更。
+ *  · `adoption.destination_unrepresentable` (409):目的地身份装不进这次收编会**派生**出来的某个键
+ *    (典型:memory 的 `proj:` 键 = 新 tenant 段 + 原有项目段后缀,合起来越过列宽)。与上一条分家的理由:
+ *    运维的动作完全不同 —— 那条要去清理另一个 principal 的行,这条要换一个更短的目的地身份。
+ *  · `not_found.adoption` (404):operator 拿着一个不存在的 id 来读。
+ *
+ * 幂等:同参数重跑秒回**同一份** `AdoptionReceipt`(`immutableReport` 逐字节恒同 —— 它在 phase 6
+ * 一次落库,此后原样回放)。并发同参 POST 由 `adoption_log.from_principal` 的 UNIQUE 仲裁:恰一行落库,
+ * 两条连接拿到同一个 adoptionId、同一份回执。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleAdoption(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=adoption.d.ts.map

package/dist/http/routes/adoption.js

@@ -0,0 +1,120 @@
+import { createAdoptionRunner } from "../../adoption/runner.js";
+import { AdoptionRequestSchema } from "../../adoption/wire.js";
+import { checkAdoptionWidths } from "../../adoption/plan.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+const ADOPTION_ID_RE = /^\/v1\/adoption\/([^/]+)$/;
+/** 结局 → wire。**拒从不走 200 回执包络**(见顶注三条拒的分家)。
+ *  成功码写死 200(不收 `okStatus` 参数):一个**表达式**状态码会让 errorCode 归一门读不出这是成功面,
+ *  而且本面本来就只有一个成功码 —— 同参重跑必须与首次同形,重跑创建不了任何东西。 */
+function sendOutcome(res, out) {
+    switch (out.kind) {
+        case "receipt":
+            sendJson(res, 200, { adoptionId: out.adoptionId, ...out.receipt });
+            return;
+        case "source_already_bound":
+            sendError(res, 409, "adoption.source_already_bound", "this source principal is already bound to a different adoption target", {
+                adoptionId: out.adoptionId,
+                fromPrincipal: out.fromPrincipal,
+                boundTo: out.boundTo,
+            });
+            return;
+        // 闭集穷举:`AdoptionRejectCode` 加一个成员而这里没加臂 ⇒ **编译红**(拒绝码是 wire 契约,
+        // 不许有一个走到默认臂的静默码)。
+        case "rejected":
+            switch (out.code) {
+                case "adoption.destination_conflict":
+                    sendError(res, 409, "adoption.destination_conflict", "the destination principal already holds rows sharing a logical key with the source", {
+                        adoptionId: out.adoptionId,
+                        detail: out.detail,
+                        conflicts: out.conflicts,
+                    });
+                    return;
+                case "adoption.destination_unrepresentable":
+                    sendError(res, 409, "adoption.destination_unrepresentable", "the destination principal does not fit every key this adoption would derive from it", {
+                        adoptionId: out.adoptionId,
+                        detail: out.detail,
+                    });
+                    return;
+            }
+            return;
+    }
+}
+export async function handleAdoption(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleAdoptionBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleAdoptionBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson } = ctx.helpers;
+    const isPost = req.method === "POST" && url === "/v1/adoption";
+    const idMatch = req.method === "GET" ? ADOPTION_ID_RE.exec(url) : null;
+    if (!isPost && !idMatch) {
+        miss.fell = true;
+        return;
+    }
+    // 门序 = operator 面的既有口径:身份(401)→ 授权(403)→ 能力(501)→ 验型(400)。
+    // 授权在能力之前:一个够不着任何东西的调用方不该从「有没有 SQL 后端」上读出部署形态。
+    const principal = gatedPrincipal(req, deps.config); // direct-door safe: verified identity, never the spoofable header
+    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", "adoption is an operator-only deployment action");
+        return;
+    }
+    const store = deps.backend?.adoptionLog?.();
+    if (!store) {
+        sendError(res, 501, "capability.adoption_store_required", "adoption requires a SQL store backend (DB_BACKEND=mysql|pg)");
+        return;
+    }
+    const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "tidb", now: Date.now, logger: deps.logger });
+    if (idMatch) {
+        const id = ctx.helpers.safeDecode(idMatch[1]);
+        if (id === null) {
+            // 复用既有的 `request.id_invalid`(sessions/attachments 同族),不为一条新路由铸第二个同义码
+            // ——附录 A 的判据②:只有消费端真会分支时才铸新码。
+            sendError(res, 400, "request.id_invalid", "invalid adoption id");
+            return;
+        }
+        const out = await runner.get(id);
+        if (!out) {
+            sendError(res, 404, "not_found.adoption", "adoption not found");
+            return;
+        }
+        sendOutcome(res, out);
+        return;
+    }
+    let raw;
+    try {
+        raw = await readJson(req);
+    }
+    catch {
+        sendError(res, 400, "request.invalid_json", "invalid JSON body");
+        return;
+    }
+    const parsed = AdoptionRequestSchema.safeParse(raw);
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "invalid adoption body — expected {fromPrincipal, toPrincipal} as non-empty strings");
+        return;
+    }
+    const { fromPrincipal, toPrincipal } = parsed.data;
+    // 🔴 列宽校验在**铸行之前**(codex R1-F3):合法长度的 principal 也可能装不进最窄的那根被写列,
+    // 而那种失败若发生在腿的中途,phase 会永远停在 INTENT —— 每次重发和每次 boot 扫描都再撞一次同样的墙。
+    const tooWide = checkAdoptionWidths(fromPrincipal, toPrincipal);
+    if (tooWide !== undefined) {
+        sendError(res, 400, "request.field_invalid", "the adoption principals do not fit every identity column and derived key this adoption must write", { detail: tooWide });
+        return;
+    }
+    if (fromPrincipal === toPrincipal) {
+        // 183 §8 的「nothing to adopt」分支:同名不是一次无操作的成功,它是一个提错了的请求
+        // ——铸一行 adoption_log 会永久占掉那个 from 的 UNIQUE 名额(D7 之后再也收编不了),所以拒在入库之前。
+        sendError(res, 400, "request.field_invalid", "fromPrincipal and toPrincipal are the same — nothing to adopt");
+        return;
+    }
+    const out = await runner.start(fromPrincipal, toPrincipal);
+    sendOutcome(res, out);
+}
+//# sourceMappingURL=adoption.js.map

package/dist/http/routes/approvals-assistant.js

@@ -637,7 +637,8 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     }
                 }
                 : undefined;
-            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, req, answer, binding, grantOnCommit);
+            // #204 件6①:出处 = `"human"` —— 这条腿是运维**亲自**在 HTTP 上给的终局(approve/deny 两向都是)。
+            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, "human", req, answer, binding, grantOnCommit);
             if (remember && deps.approvalExemptionStore) {
                 sendJson(res, out.status, { ...out.body, rememberApplied });
                 return;

package/dist/http/routes/capabilities.js

@@ -81,6 +81,40 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             // the old caps honestly hides the affordances (the adaptation was pre-announced).
             memory: false,
             memoryWrite: false,
+            // design/177 —— org 共享记忆库只读面。判据**逐字**等于 server.ts 里那个域的挂载合取式(供给面 ∧
+            // org 折叠面),所以"说 yes ⟺ 面真能用"是结构性的:少一个,域不挂载、这里也翻假,消费方看到的
+            // 与它真能打通的永远一致。折叠面缺席时刻意不报 true —— 一个没有成员性判据的共享读面比没有更糟。
+            sharedMemory: Boolean(deps.sharedMemoryStore && deps.orgMemoryDirectory),
+            // design/183 form b:收编面(operator lane)。谓词 = **两项合取**,逐项对着 handleAdoption 的
+            // 拒绝臂写:①`adoptionLog` 工厂在场(local backend 刻意不实现——单用户数据根没有多租身份轴可
+            // 重绑)⇒ 否则 501;②operator 名单**非空** ⇒ 否则 `explicitOperatorOk` 对任何身份都返回 false,
+            // 那条路由**恒 403**。
+            // 🔴 第二项是 [3397]-4(黑板 cli 审计)逮到的真缺口:旧谓词只查 ① ⇒ 「装了 SQL 后端但没配
+            // OPERATOR_PRINCIPALS」的部署位报 true、路由恒 403 —— 本仓「says yes ⟺ route works」被实测证否。
+            // 空名单在这条轴上**刻意**不走 `isOperator` 的「人人都是 operator」旧义(那是一道世界可写的门,
+            // 见 principal-gate.ts 的 `explicitOperatorOk` 头注),所以补的是能力位、不是放宽授权。
+            adoption: Boolean(deps.backend?.adoptionLog) && deps.config.operatorPrincipals.length > 0,
+            // [3397]-5:`GET /v1/outcomes`(design/73 §7.2 机械信号只读聚合)。此前**有 501 拒而无能力位** ——
+            // 消费端只能 trial-by-501,与本仓「gate-don't-trial-by-501」的姿势相反。谓词逐项对着该路由的
+            // 拒绝臂:①可查询的账面在场(`outcomeSink.summary`;File sink 只写 JSONL,没有查询面 ⇒ 501);
+            // ②多租户下 operator 名单非空(单用户形无此门 —— 唯一的用户就是 operator,路由那侧的
+            // `if (deps.config.requirePrincipal)` 逐字如此)。②与 adoption 是**同一族**缺口,同批一起补。
+            outcomeLedger: Boolean(deps.outcomeSink?.summary) && (deps.config.requirePrincipal !== true || deps.config.operatorPrincipals.length > 0),
+            // #154 车二 + #203 §2:规则车道(cc-import 两口 + 撤销面两口 + respond 的 persistRule 兑付口)。
+            // 谓词与 `/v1/rules/*` 全族的 501 同源:ruleConsent lane 在场 ⟺ 总开关未被显式关 ∧ 规则店 wired
+            // (SQL 双方言,或 #203 起 local 的 File 三面束)。说 yes ⟺ **四口都活**,不是「有一口活」。
+            permissionRules: Boolean(deps.ruleConsent),
+            // #205 SDK 车上游请托二连(2026-08-10):
+            //  · `permissionRulesRevoke` —— 撤销面两口(GET/DELETE /v1/rules)**存在性**的独立信号。谓词与
+            //    `permissionRules` 同源,但**在场性**本身就是版本信号:≤7.11.0 的 worker `permissionRules` 已为
+            //    true 而这两口 404(位早于路由),消费端无从区分「面没开」与「版本太老」——本位缺席 = 老版本,
+            //    探 404 即可;在场 = 路由已铸。不折进 `permissionRules`:那个位的成文语义(「四口都活」)在
+            //    ≤7.11.0 的已发布包上已经是谎,只能加位不能改位。
+            permissionRulesRevoke: Boolean(deps.ruleConsent),
+            //  · `oneShot` —— server 消费 `TaskRequest.oneShot`(缺席不写透传 + 非 boolean 400)。旧 server 对
+            //    未知键静默容忍 ⇒ 调用方声明了一次性形却拿不到 core 的 block-wait 指引而不自知;本位在场 = 键
+            //    真被消费。恒 true(消费不依赖任何可选设施)。
+            oneShot: true,
             // CLI surfaces: /v1/policy is always served (config surface); /v1/usage returns real
             // cumulative spend only when a per-principal quota is configured (else enabled:false).
             policy: true,
@@ -127,14 +161,27 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             // routes (same gate as steer — the verbs share the registry + run store; retain-off runs 409 resume.retain_off).
             subagentResume: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
             // TaskRequest.settings (client per-request SemaSettings stamp) → projected into the engine TIGHTEN-ONLY
-            // (deny-wins, after the deployment + operator baseline). v1 wires permissions + permissionMode (default/
-            // acceptEdits/plan — `bypassPermissions` is NEVER honored from settings) + model + outputStyle.
+            // (deny-wins, after the deployment + operator baseline). v1 wires permissions + permissionMode + model +
+            // outputStyle.
+            // 🔴 保鲜(design/201 施工期自查):旧文「`bypassPermissions` is NEVER honored from settings」是
+            // **pre-[816] 拍照,已作废** —— `parseTaskSettings` 自 [816]/[820] 起白名单收**五**模式,bundle 形的
+            // bypass 与顶层键同权(两者的优先序由 `effectivePermissionMode` 单点裁定)。语义不是「开门」而是
+            // 「不加模式派生的那道门」:部署/运维基线在此之外合成,settings 掀不掉(tightenTaskSpec deny-wins)。
+            // 留着那句过期的否定句比留个欠账更伤:消费方会据此以为 bundle 形 bypass 无效而改用别的写法。
             // `env`([2400] X-8):与真消费点同谓词——resolve-spec 的 setSessionShellEnv 只在 cwdHonored
             // (单用户 host lane)注入 shell env;其余 lane 收到即警告忽略。此前硬编码 false 是「TaskSpec 无
             // per-task env 注入」时代的陈旧断言(R-survey shellEnv seam 落地后失真=说没有但其实有,活能力被藏)。
             // `hooks`(hook-runner 阶段一):TRUE 当本部署会真跑 hook 命令 = 单用户闸(hook 命令跑在
             // worker host,class ② 能力授予;resolveSpec 的 taskHooks 装配同一谓词)。多租户 = false(收到警告忽略)。
             taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: cwdHonored(deps.config), hooks: deps.config.requirePrincipal !== true },
+            // design/201 §3 前提②:显式 `permissionMode` 会被翻译成 `spec.shellGate` 档
+            // (bypassPermissions ⇒ off,auto/default/acceptEdits/plan ⇒ classify;表态缺席 ⇒ 不写键)。
+            // **恒 true 且与翻译表同一个 commit** —— 这一位不是"配置在不在",而是"这份二进制里有没有那张表",
+            // 所以 says yes ⟺ 翻译真在,是结构性的(某个 deps 缺席不会让它变假)。
+            // 消费半场:壳(cli #223)据此撤掉它对 `MANUAL_MODE_SHELL_GATE` 的无条件注入。判据必须是
+            // **所连 server 广告本位**,不是壳自身版本 —— 新壳连老 server / 回滚到旧二进制的副本 / 混版 fleet
+            // 三形下,壳看见本位缺席就继续注 env,于是"翻译还没到货但壳已经撤注"那个放宽窗结构上不存在。
+            modeShellGateTranslation: true,
             // [1476] R1 / [1478] R2: TaskRequest.appendSystemPrompt is accepted top-level → TaskSpec.appendSystemPrompt
             // (first-class lane for the shell's product-knowledge block). A shell probes THIS flag: false/absent ⇒ fall
             // back to the settings.outputStyle ride-along (older servers fold that into the same spec field).

package/dist/http/routes/rules.d.ts

@@ -0,0 +1,35 @@
+/**
+ * #154 车二 + #203 §2 —— **规则车道的 wire 面**(design/179 §7 的导入半场 + design/203 的撤销半场)。
+ *
+ *   POST   /v1/rules/cc-import/prepare  → 预览 + 一张**一次性、principal 绑定、有期、载荷绑定**的票
+ *   POST   /v1/rules/cc-import/redeem   → 原子消费票 → confirm → 批量兑付进店
+ *   GET    /v1/rules                    → 列出自己名下**活着**的规则(keyset 分页,游标绑 rev)
+ *   DELETE /v1/rules                    → 按 (rule, scope) 内容撤销,**恒经** core `removePersistedRule`
+ *
+ * **lane = principal**(不是 operator):用户导的是**他自己**的规则,一条规则的语义就是「这个人自己
+ * 说过 yes」。operator 在**扩权**这条路上没有位置——他既不该替租户扩权,也不该被要求代人点确认。
+ * 因此**导入两口**只认已验明的 principal,连 `explicitOperatorOk` 的旁路都不给:一个 operator 想给
+ * 自己导规则,用他自己的 principal 走同一条路即可(那时他就是租户)。
+ *
+ * 🔴 **撤销面两口多一条 operator 越权域,而这不是上面那句话的例外,是它的对偶**(design/203 §2 设计题
+ * 一裁定):`?principal=` / body 里的 `principal` 让 operator 读**或收回**任一租户的规则。方向决定授权:
+ * 收回是**收紧**(core 的 `removePersistedRule` 头注逐字:「a host may narrow on a user's behalf, it may
+ * not widen」),而多租户管理员能回收权限正是撤销面的本义。读那一半同样只开给 operator ——
+ * 规则文本里含命令样式,跨 principal 读是信息面泄露,所以**不开第三方 principal 相互读**。
+ * 判据用 `explicitOperatorOk`(空名单 = 全拒),**绝不**从 service token 推断身份:一个共享的部署凭证
+ * 不是一个人。
+ *
+ * **billable = false**:四口都不烧模型(读 settings 文本 / 读写规则行),不进 `isBillableSubmitPath`。
+ *
+ * 🔴 **四类拒绝在 wire 上同形 404**(信任边界 ①):unknown ticket / 别人的 ticket / 过期 / 已用过 ——
+ * 四个成因返回不同的码就是一台存在性 oracle(拿别人的票撞库能探到「它在别处存在」)。分类只进服务端
+ * 日志,不上 wire。同族先例 = run/trace 属主门与 `POST /v1/tasks/:id/asks/:askId/decision` 的 404 姿势。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const RULES_CC_IMPORT_PREPARE_PATH = "/v1/rules/cc-import/prepare";
+export declare const RULES_CC_IMPORT_REDEEM_PATH = "/v1/rules/cc-import/redeem";
+/** 撤销面两口共用的字面路径(GET 列举 / DELETE 撤销)。 */
+export declare const RULES_PATH = "/v1/rules";
+export declare function handleRules(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/http/routes/rules.js

@@ -0,0 +1,293 @@
+import { z } from "zod";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { createLogger } from "../../observability/logger.js";
+// 等待秒数的单一真源在车道:它同时被「放回认领时判这张票还撑不撑得过这段窗」用到(见那侧头注)。
+// scope 的 wire 形也在车道(列举列 / 查询参数 / 删除体 / 游标四处同一份表示,见那侧头注)。
+import { RULE_IMPORT_RETRY_AFTER_SEC, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
+const logger = createLogger();
+export const RULES_CC_IMPORT_PREPARE_PATH = "/v1/rules/cc-import/prepare";
+export const RULES_CC_IMPORT_REDEEM_PATH = "/v1/rules/cc-import/redeem";
+/** 撤销面两口共用的字面路径(GET 列举 / DELETE 撤销)。 */
+export const RULES_PATH = "/v1/rules";
+/** 一页的上下限。50 = 一屏治理列表;200 = 一次响应的上界(一条规则行带 `adds[]`,不是一个标量)。
+ *  与 `GET /v1/sessions` 的 keyset 姿势同族(sessions-list.ts:137 的 `Math.min(100, …)`),数值按本面
+ *  的行宽另定 —— 抄一个数比抄一条理由更容易漂。 */
+const RULES_PAGE_DEFAULT = 50;
+const RULES_PAGE_MAX = 200;
+/** 一层 settings 的上限。一份 CC settings 是人手写的 JSON,不是数据集;16 KiB 宽到装得下几百条 allow,
+ *  窄到一次请求不能拿它当上传通道。层数同理(core v1 只读三层,给 3 就够,多给等于给一个放大面)。 */
+const MAX_LAYER_CONTENT_CHARS = 16_384;
+const MAX_LAYERS = 3;
+/** 🔴 边界必 schema(宪法 [2704])。`.strict()`:多给一个键 = 400,不是静默忽略 —— 一个把 `content`
+ *  拼错成 `contents` 的客户端应该当场知道,而不是拿到一份「零候选」的预览去纳闷。 */
+const CcImportPrepareBodySchema = z
+    .object({
+    layers: z
+        .array(z
+        .object({
+        layer: z.enum(["userSettings", "projectSettings", "localSettings"]),
+        path: z.string().min(1).max(1024),
+        /** 项目层规则的作用域根。**用户自己的**目录标签(它只影响这条规则将来在哪些 cwd 下生效),
+         *  故不做**真实性**校验——server 上没有那棵树可对照,假装校验过才是谎。
+         *  🔴 但**非空**是硬的(codex 交叉复审 round5 [high] 一,验真后修):`root: ""` 会被 core 直接
+         *  变成 `{kind:"project", root:""}`,而空前缀在 `pathWithinRoot` 下**包含每一个 cwd** —— 一条
+         *  项目内规则就此悄悄升成全局规则;更糟的是本仓的读面对空 root 是整桶拒,于是一次「成功」的
+         *  导入会让这位租户**之后每一次**规则读写都失败。 */
+        root: z.string().min(1).max(1024),
+        content: z.string().max(MAX_LAYER_CONTENT_CHARS),
+    })
+        .strict())
+        .min(1)
+        .max(MAX_LAYERS),
+})
+    .strict();
+const CcImportRedeemBodySchema = z.object({ ticket: z.string().min(1).max(190) }).strict();
+/** `DELETE /v1/rules` 的体。`.strict()` 同族理由:把 `scope` 拼错成 `scopes` 的客户端应该当场知道,
+ *  而不是拿到一个「删掉了 global 那条」的意外结果。`principal` = operator 越权域(缺席 = 删自己的)。
+ *  长度上限与 principal 入口上限同源(`PRINCIPAL_MAX_LENGTH = 190`,security.ts);`rule` 的 1024 与
+ *  cc-import 的 `root` 同族(一条规则文本是人写的一行,不是载荷)。 */
+const RuleRevokeBodySchema = z
+    .object({
+    rule: z.string().min(1).max(1024),
+    scope: z.string().min(1).max(1088), // "project:" + root(1024)+ 余量
+    principal: z.string().min(1).max(190).optional(),
+})
+    .strict();
+const RulesCursorSchema = z
+    .object({ rev: z.number().int().nonnegative().safe(), principal: z.string(), scope: z.string(), after: z.string() })
+    .strict();
+function encodeRulesCursor(c) {
+    return Buffer.from(JSON.stringify(c)).toString("base64url");
+}
+/**
+ * 读不出形 ⇒ `{ok:false, why}`,由调用方拒(400)。两条纪律:
+ *  · **刻意不**「读不出就当第一页」(sessions-list 的旧姿势):那条腿的游标只影响顺序,这条腿的游标
+ *    一旦被静默丢弃,客户端会以为自己列完了整份清单。
+ *  · 失败**带着原因出来**而不是塌成一个 `undefined`:调用点把 `why` 写进服务端日志。一个只回默认值的
+ *    catch 是本仓在册的静默降级形(#191 门② SHAPE C)——这里不需要那种便利,原因本来就有用。
+ */
+function decodeRulesCursor(raw) {
+    try {
+        const parsed = RulesCursorSchema.safeParse(JSON.parse(Buffer.from(raw, "base64url").toString()));
+        return parsed.success ? { ok: true, cursor: parsed.data } : { ok: false, why: parsed.error.message };
+    }
+    catch (err) {
+        return { ok: false, why: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** 排序键 —— 与 `RuleConsentLane.listRules` 的 (scope, rule) 二元排序**等价**(两处若各写一份必然漂,
+ *  而漂的表现是分页静默漏行)。分隔符必须**小于**任何可能出现的字符,否则串比较与元组比较会在
+ *  「一个 scope 是另一个的前缀」处分岔(`project:/a` vs `project:/ab`)。用空格是错的 ——
+ *  `Bash(echo hi)` 里就有一个;\u0000 是码点最小的字符,而且规则文本与路径里都不可能出现它。 */
+const rowKey = (r) => `${r.scope}\u0000${r.rule}`;
+export async function handleRules(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleRulesBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleRulesBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson, rateLimited } = ctx.helpers;
+    const isPrepare = req.method === "POST" && url === RULES_CC_IMPORT_PREPARE_PATH;
+    const isRedeem = req.method === "POST" && url === RULES_CC_IMPORT_REDEEM_PATH;
+    // 🔴 判路写**字面量**而不是引 `RULES_PATH`(与 server.ts 的 `ROUTE_LABEL_LITERALS` 那条注同族理由):
+    // 路由名册门与文案接线门的枚举器扫的是 `url === "…"` 的**源码文本**,引常量会让这两口对两道门隐形
+    // ——那不是「过了门」,是绕过门。常量仍导出给测试/SDK 侧当单一真源用。
+    const isList = req.method === "GET" && url === "/v1/rules";
+    const isRevoke = req.method === "DELETE" && url === "/v1/rules";
+    if (!isPrepare && !isRedeem && !isList && !isRevoke) {
+        miss.fell = true;
+        return;
+    }
+    // 🔴 `prepare` 每次调用**都会**落一条 pending 审批记录 + 一张票 —— 它是本域唯一一条「一次请求 = 一行」
+    // 的写面,没有限流就是一条行洪口。与 `POST /v1/tasks/:id/asks/:askId/decision` 同姿势(限流在最前)。
+    // 撤销面两口同罩:`DELETE` 是写(每次铸一个 dot + 一条墓碑),`GET` 是整桶读 —— 两者都不该无限打。
+    if (rateLimited(req, res))
+        return;
+    // 鉴权**先于**可用性(501-before-auth 先例的反面同理):这四口没有可被探测的部署事实,但
+    // principal 是本域的全部授权基础,先立住它再谈别的。
+    const principal = gatedPrincipal(req, deps.config);
+    if (principal === undefined) {
+        sendError(res, 401, "auth.unauthorized", "unauthorized");
+        return;
+    }
+    const lane = deps.ruleConsent;
+    if (lane === undefined) {
+        sendError(res, 501, "capability.rule_store_required", "this deployment has no permission-rule store wired");
+        return;
+    }
+    // ── 撤销面两口(#203 §2)──────────────────────────────────────────────────────────────────────
+    // 放在读体之前:`GET` 没有体,`readJson` 对它是一次白等。
+    if (isList) {
+        await handleRuleList(req, res, principal, lane, deps.config.operatorPrincipals);
+        return;
+    }
+    let rawBody;
+    try {
+        rawBody = await readJson(req);
+    }
+    catch {
+        sendError(res, 400, "request.body_shape", "body must be valid JSON");
+        return;
+    }
+    if (isRevoke) {
+        await handleRuleRevoke(res, rawBody, principal, lane, deps.config.operatorPrincipals);
+        return;
+    }
+    if (isPrepare) {
+        const parsed = CcImportPrepareBodySchema.safeParse(rawBody);
+        if (!parsed.success) {
+            sendError(res, 400, "request.body_shape", "body must be {layers:[{layer,path,root,content}]}");
+            return;
+        }
+        const prepared = await lane.prepareImport(principal, parsed.data.layers);
+        if (!prepared.ok) {
+            // 413(不是 400):族语义就是「体/条目超上限」,与附件/图片同码同状态(附录 A 已成文)。
+            // 帽的位置与理由(为什么单层字节帽不够、为什么帽在**铸票之前**)见 `rules-consent.ts` 的
+            // `MAX_IMPORT_CANDIDATES`。
+            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 });
+        return;
+    }
+    const parsed = CcImportRedeemBodySchema.safeParse(rawBody);
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "body must be {ticket}");
+        return;
+    }
+    const redeemed = await lane.redeemImport(principal, parsed.data.ticket);
+    if (!redeemed.ok) {
+        logger.info("rule import ticket refused", { reason: redeemed.reason, detail: redeemed.detail, retryable: redeemed.retryable === true });
+        // 🔴 codex 交叉复审 round2 [medium](验真后修):**可重试**那一支不能折进 404。
+        // 为什么这不破坏零存在性 oracle:走到这一支的调用方**已经赢下了一次 principal 绑定的认领** ——
+        // 也就是说他已经证明了这张票是他自己的、没过期、没用过。对他说「稍后再试」泄不出任何**别人**的
+        // 存在性(伪造 / 别人的 / 过期 / 已用过 四类仍然同形 404,一个字都没变)。反过来把它折成 404 才是
+        // 真损失:round1 修好的「认领已放回、这张票还能用」在 wire 上被抹掉,客户端按常规 404 处置一丢了之。
+        if (redeemed.retryable === true) {
+            res.setHeader("retry-after", String(RULE_IMPORT_RETRY_AFTER_SEC)); // 体里有等待提示 ⇒ 标准头同值(同 503 族先例)
+            sendError(res, 503, "state.rule_import_retry", "the rule import could not be completed right now; the ticket is still usable — retry", { retryAfterSec: RULE_IMPORT_RETRY_AFTER_SEC });
+            return;
+        }
+        // 同形 404(顶注):四类成因**不上 wire**,只进服务端日志。
+        sendError(res, 404, "not_found.rule_ticket", "no such import ticket");
+        return;
+    }
+    sendJson(res, 200, { result: redeemed.result });
+}
+/**
+ * 解析**目标 principal**(自有域 vs operator 越权域)。
+ *
+ * 🔴 判据链是硬的:①没给 = 自己(最常见的路,零授权提问);②给了但等于自己 = 还是自己(一个把
+ * principal 显式写出来的客户端不该因此被要求当 operator);③给了别人 = **必须** `explicitOperatorOk`。
+ * 第三条用的是 `explicitOperatorOk` 而不是 `isOperator`:后者在 `OPERATOR_PRINCIPALS` 为空时「人人
+ * 都是 operator」,那在跨租户读规则这条轴上是一道世界可写的门(principal-gate.ts 的头注逐字)。
+ * **绝不**从 service token 推断:一个共享的部署凭证不是一个人,而这条口的授权对象是人。
+ */
+function resolveTargetPrincipal(requested, caller, operatorPrincipals) {
+    if (requested === undefined || requested === caller)
+        return { ok: true, principal: caller };
+    if (!explicitOperatorOk(caller, operatorPrincipals))
+        return { ok: false };
+    return { ok: true, principal: requested };
+}
+/** `GET /v1/rules` —— 列出一位 principal 名下**活着**的规则。 */
+async function handleRuleList(req, res, caller, lane, operatorPrincipals) {
+    // `url` 在派发前已被剥掉 query,查询参数只能从 `req.url` 重新取(与 `/v1/outcomes` 同姿势)。
+    const q = new URL(req.url ?? "/", "http://localhost").searchParams;
+    const target = resolveTargetPrincipal(q.get("principal") ?? undefined, caller, operatorPrincipals);
+    if (!target.ok) {
+        sendError(res, 403, "auth.operator_only", "reading another principal's rules is an operator-only action");
+        return;
+    }
+    // limit:非数/越界一律夹取(与 sessions-list 同姿势——一个分页参数写错不该让治理面整个打不开)。
+    const limit = Math.min(RULES_PAGE_MAX, Math.max(1, Number(q.get("limit") ?? RULES_PAGE_DEFAULT) || RULES_PAGE_DEFAULT));
+    // scope 过滤:**给了就必须读得出形**。读不出不当「没过滤」——那会把一次「只看这个项目」的请求
+    // 悄悄变成一次全量列举,而客户端会照单全收当成该项目的清单。
+    const scopeRaw = q.get("scope");
+    const scopeFilter = scopeRaw === null ? undefined : parseRuleScope(scopeRaw);
+    if (scopeRaw !== null && scopeFilter === undefined) {
+        sendError(res, 400, "request.query_invalid", "scope must be 'global' or 'project:<root>' with a non-empty root");
+        return;
+    }
+    const cursorRaw = q.get("cursor");
+    const decoded = cursorRaw === null ? undefined : decodeRulesCursor(cursorRaw);
+    if (decoded !== undefined && !decoded.ok) {
+        logger.info("rules cursor unreadable", { why: decoded.why });
+        sendError(res, 400, "request.query_invalid", "the rules cursor is unreadable — restart the listing without one");
+        return;
+    }
+    const cursor = decoded?.ok === true ? decoded.cursor : undefined;
+    // 过滤键用**规范形**(`serializeRuleScope` 的产物),不是客户端交上来的原串:行上的 scope 是规范的,
+    // 拿一个等价但拼法不同的原串去比会静默过滤成空表。空串 = 未过滤(游标里也用这一个表示)。
+    const filterKey = scopeFilter === undefined ? "" : serializeRuleScope(scopeFilter);
+    const listing = await lane.listRules(target.principal);
+    if (cursor !== undefined && (cursor.rev !== listing.rev || cursor.principal !== target.principal || cursor.scope !== filterKey)) {
+        // 游标绑 (rev, principal, scope)(见 {@link RulesCursor} 头注)。**拒**而不是从头给:静默重置会让
+        // 客户端把第二页当成「接着上一页」,治理面上于是出现一份既漏行又重行的清单,而没有任何人知道。
+        // 三项合并成一句文案是刻意的:对客户端来说处置完全相同(丢掉游标从头列),而把「你换了 principal」
+        // 单独成句会让一个 operator 从别人桶的 rev 上读出信息。
+        sendError(res, 400, "request.query_invalid", "the rules cursor was minted at a different revision — restart the listing", { rev: listing.rev });
+        return;
+    }
+    const matching = listing.rows.filter((r) => (filterKey === "" || r.scope === filterKey) && (cursor === undefined || rowKey(r) > cursor.after));
+    const page = matching.slice(0, limit);
+    const last = page[page.length - 1];
+    const nextCursor = matching.length > limit && last !== undefined
+        ? encodeRulesCursor({ rev: listing.rev, principal: target.principal, scope: filterKey, after: rowKey(last) })
+        : undefined;
+    sendJson(res, 200, { rules: page, rev: listing.rev, ...(nextCursor !== undefined ? { nextCursor } : {}) });
+}
+/** `DELETE /v1/rules` —— 按内容(rule, scope)撤销。 */
+async function handleRuleRevoke(res, rawBody, caller, lane, operatorPrincipals) {
+    const parsed = RuleRevokeBodySchema.safeParse(rawBody);
+    if (!parsed.success) {
+        sendError(res, 400, "request.body_shape", "body must be {rule, scope} with an optional principal");
+        return;
+    }
+    const scope = parseRuleScope(parsed.data.scope);
+    if (scope === undefined) {
+        sendError(res, 400, "request.body_shape", "scope must be 'global' or 'project:<root>' with a non-empty root");
+        return;
+    }
+    const target = resolveTargetPrincipal(parsed.data.principal, caller, operatorPrincipals);
+    if (!target.ok) {
+        // 与读那一半**同码同姿势**:方向(收紧)决定了这条越权域存在,身份判据不因方向而放松。
+        sendError(res, 403, "auth.operator_only", "revoking another principal's rules is an operator-only action");
+        return;
+    }
+    const outcome = await lane.removeRule({ principal: target.principal, rule: parsed.data.rule, scope });
+    switch (outcome.status) {
+        case "removed":
+            // 🔴 `stillLive` **必须上 wire**(design/203 v2 §6 F3)。它为真的意思是「墓碑落了,但这次调用
+            // 期间又落了一次新的批准,规则按 add-wins 仍然活着」——把它折进 200 不说,客户端会把一次
+            // **没有完成**的撤销读成完成,而那正是治理面最不能出错的地方。
+            sendJson(res, 200, { status: "removed", rev: outcome.rev, stillLive: outcome.stillLive });
+            return;
+        case "no-op": {
+            // 幂等:重复删 / 本来就没有,一律 200 `no-op`。**不是 404** —— 一个「这条规则存在过吗」的
+            // 404 就是一台存在性 oracle(operator 越权域下更是跨租户的那种),而删除对「有没有过」
+            // 本来就不该作 oracle。客户端要判「我删到东西了吗」,读 `status` 即可。
+            //
+            // 🔴 `stillLive` 这一支**也要有**(codex 对抗复审 R1-F2,验真后修)。core 的原语在初始快照里
+            // 找不到匹配 dot 时**立刻**回 no-op —— 它不做 removed 那支的读回。于是「快照之后、应答之前落了
+            // 一次批准」的窗口里,规则**是活的**而端点说 no-op,客户端合理地读成「已经没有这条规则了」。
+            // 那与 F3 修好的 removed+stillLive 是**同一个**危害,只是走了另一支。
+            // 处置 = server 自己补一次读回,把**观察到的**事实如实上 wire;两支 200 的键集因此同形,消费端
+            // 一套分支读得通。读回失败不改判(no-op 本身是 core 裁定的)⇒ 保守报 `stillLive:false`?**不**:
+            // 那是编一个结论。读不出来就让它抛,由本域的全局错误臂报 500 —— 一个说不清结果的撤销不该回 200。
+            // 让 core 的原语自己报这一位是更根治的形,已作为上游请托登记(server 不改上游语义,[2862])。
+            const stillLive = (await lane.listRules(target.principal)).rows.some((r) => r.rule === parsed.data.rule && r.scope === serializeRuleScope(scope));
+            sendJson(res, 200, { status: "no-op", rev: outcome.rev, stillLive });
+            return;
+        }
+        case "failed":
+            // core 对 `failed` 的承诺是「读回确认什么都没写」或「读回本身也失败了,结局不定」——两种都是
+            // **重试可改判**的,所以 503 而不是 500。理由与 `state.rule_import_retry` 同族。
+            logger.info("rule revoke failed", { error: outcome.error });
+            sendError(res, 503, "state.rule_remove_failed", "the rule could not be revoked right now — retry, then reconcile with GET /v1/rules");
+            return;
+    }
+}
+//# sourceMappingURL=rules.js.map