@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/principal-gate.js

@@ -1,8 +1,10 @@
 import { timingSafeEqual } from "node:crypto";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
-import { PRINCIPAL_TOKEN_HEADER, sameSessionOwner, verifiedPrincipal, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope, ownerlessRowOpen, mintPrincipal } from "../security.js";
+import { PRINCIPAL_TOKEN_HEADER, verifiedPerson, verifiedSubject, scenarioHeaderOf, scenarioWithoutPrincipalError, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope } from "../security.js";
+import { personOf } from "../owner-brands.js";
 import { IDENTITY_SOURCES, runIdentityClaimOverflow } from "../identity-source.js";
 import { sendError } from "./send.js";
+import { canonicalAddress } from "../net-address.js";
 export function headerStr(v) {
     return Array.isArray(v) ? v[0] : v;
 }
@@ -40,7 +42,8 @@ export function traceTokenPresented(req, config) {
     return !!config.traceToken && authorized(req, config.traceToken);
 }
 export function isLoopbackAddress(addr) {
-    return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
+    const canonical = addr === undefined ? undefined : canonicalAddress(addr);
+    return canonical === "127.0.0.1" || canonical === "::1";
 }
 function identitySourceVerified(kind, req, config) {
     switch (kind) {
@@ -49,7 +52,7 @@ function identitySourceVerified(kind, req, config) {
         case "sso":
             return ssoVerifiedPrincipal(req) !== undefined;
         case "direct_door_jwt":
-            return config.directDoorActive && verifiedPrincipal(req, config) !== undefined;
+            return config.directDoorActive && verifiedPerson(req, config) !== undefined;
         default: {
             const unknownKind = kind;
             throw new Error(`verifiedIdentitySource: unknown identity source ${String(unknownKind)}`);
@@ -97,20 +100,26 @@ export function runIdentityOf(req, config, owner) {
     const admitted = ADMITTED_RUN_IDENTITY.get(req);
     if (admitted === undefined || admitted === null)
         return null;
-    return (gatedPrincipal(req, config) ?? null) === owner ? admitted : null;
+    return (gatedSubject(req, config) ?? null) === owner ? admitted : null;
 }
-export function gatedPrincipal(req, config) {
-    if (bearerPresentedButUnverified(req, config))
+export function gatedSubject(req, config) {
+    if (bearerPresentedButUnverified(req, config)) {
+        if (scenarioHeaderOf(req) !== undefined)
+            throw scenarioWithoutPrincipalError();
         return undefined;
-    const verified = verifiedPrincipal(req, config);
-    return verified === undefined ? undefined : mintPrincipal(verified);
+    }
+    return verifiedSubject(req, config);
+}
+export function gatedPerson(req, config) {
+    const subject = gatedSubject(req, config);
+    return subject === undefined ? undefined : personOf(subject);
 }
 export function principalTokenPresentedButUnverified(req, config) {
     if (!config.directDoorActive)
         return false;
     if (headerStr(req.headers[PRINCIPAL_TOKEN_HEADER]) === undefined)
         return false;
-    return verifiedPrincipal(req, config) === undefined;
+    return verifiedPerson(req, config) === undefined;
 }
 export function sendPrincipalRefusal(res, req, config) {
     if (principalTokenPresentedButUnverified(req, config)) {
@@ -139,72 +148,21 @@ export function sendUnauthorized(res, face) {
         }
     }
 }
-export function runOwnerReadable(principal, owner, config) {
-    if (owner === null)
-        return true;
-    return sameSessionOwner(config, owner, principal ?? null);
-}
-export function hasServiceAuth(config) {
-    return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
-}
-function identitySourceWired(kind, w) {
-    switch (kind) {
-        case "service_token":
-            return hasServiceAuth(w.config);
-        case "sso":
-            return w.webAdminJwtVerifier !== undefined;
-        case "direct_door_jwt":
-            return w.config.directDoorActive;
-        default: {
-            const unknownKind = kind;
-            throw new Error(`identity sources: unknown identity source ${String(unknownKind)}`);
-        }
-    }
+export function devOpenDeployment(config) {
+    return !DEPLOYMENT_SHAPE_PREDICATES.identityBoundary.holds(config);
 }
-export function wiredIdentitySources(w) {
-    return IDENTITY_SOURCES.filter((k) => identitySourceWired(k, w));
-}
-export function devOpenDeployment(w) {
-    return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(w.config);
-}
-export function actsForDeployment(req, config, principal) {
-    return serviceTokenDeclaredActsForDeployment(config) && systemFor(req, config) !== undefined && principal() === undefined;
+export function actsForDeployment(req, config, subject) {
+    if (devOpenDeployment(config))
+        return subject() === undefined && !bearerPresentedButUnverified(req, config) ? "dev_open" : undefined;
+    return serviceTokenDeclaredActsForDeployment(config) && systemFor(req, config) !== undefined && subject() === undefined ? "deployment_token" : undefined;
 }
 export function serviceTokenDeclaredActsForDeployment(config) {
     return config.serviceTokenActsForDeployment === true;
 }
-export function sessionCallerOf(req, w) {
-    const principal = gatedPrincipal(req, w.config);
-    return { principal, fleet: devOpenDeployment(w) || actsForDeployment(req, w.config, () => principal) };
-}
-export function fleetViewOf(req, w, face) {
-    const caller = sessionCallerOf(req, w);
-    const fleetWide = caller.fleet || readOnlyFleetCredential(req, w.config, face);
-    return { fleetWide, gateOwner: fleetWide ? null : caller.principal || null };
-}
-function readOnlyFleetCredential(req, config, face) {
-    switch (face) {
-        case "read":
-            return traceTokenPresented(req, config);
-        case "write":
-            return false;
-        default: {
-            const unknownFace = face;
-            throw new Error(`fleetViewOf: unknown fleet face ${String(unknownFace)}`);
-        }
-    }
-}
-export function sessionOwnerReadable(caller, cell, w) {
-    if (devOpenDeployment(w))
-        return true;
-    if (cell.owner === null)
-        return ownerlessRowOpen(cell, caller);
-    return runOwnerReadable(caller.principal, cell.owner, w.config);
-}
-export function explicitOperatorOk(principal, roster) {
+export function explicitOperatorOk(person, roster) {
     if (roster.operatorSingleUser === true)
         return true;
-    return roster.operatorPrincipals.length > 0 && principal !== undefined && roster.operatorPrincipals.includes(principal);
+    return roster.operatorPrincipals.length > 0 && person !== undefined && roster.operatorPrincipals.includes(person);
 }
 export function operatorRosterPresent(roster) {
     return roster.operatorSingleUser === true || roster.operatorPrincipals.length > 0;

package/dist/http/refusal-body.d.ts

@@ -1,10 +1,22 @@
 /**
  * **全仓唯一的拒体组句器**(零依赖叶子模块 —— `http/checkpoint-ctx.ts` 的续跑折叠也读它,而那个模块经编译产物进随包排空脚本,闭包只许 node 内建 / 引擎包根)。
  *
- * 一只拒 = 三件事:机读码、给人读的句子、拒的机读事实(`field` / `reason` / `count` / `cap` / `detail` …;缺席 = 没有可机读的事实)。
+ * 一只拒 = 三件事:机读码、给人读的句子、拒的机读事实(`field` / `reason` / `count` / `cap` …;缺席 = 没有可机读的事实)。
  * 拒体 = `{ error, errorCode, ...facts }`(机读事实原样随体、排在最后)。整面拒(`http/send.ts` 的 `sendError` / `sendHttpError`)、把同一只拒当**数据**带进 200 体的面板
  * (`GET /v1/sessions/:id/mcp` 的 `scenarioRefusal`)、续跑把一只拒折成 409 的 `resume_blocked_by_policy`(`http/checkpoint-ctx.ts`)读的都是它 —— 同一只拒在几处渲出的成员逐字同。
  * 判据只交这份数据,不自己拼体。
+ *
+ * **版式律(一种)**:机读事实的容器一律在拒体**根上**,容器内部的领域结构原样保留(条目问题的 `problems[]` 每项 `{ code, field, entry, reason }`、
+ * 冲突的 `fields[]`、领养的 `conflicts[]`);拒体根上**没有** `detail` 键(对象、串都没有)—— 「哪一臂」是 `reason`,被拒值的坐标是 `field`,
+ * 给人读的话进句子。引擎 / 外部对象进拒体只经**闭集映射**(先例 {@link resumeRefusalFacts}),不整只摊。
+ * 本层自己铸的请求坐标只有一种写法:{@link fieldCoordinate}。
+ *
+ * **保留键**({@link REFUSAL_RESERVED_KEYS}):事实不得带这几只顶层键。三处读这一张表 ——
+ *  · 组句器 {@link refusalBody}(覆盖 `sendError` 与直接调它的交回形):带保留键 ⇒ 抛;
+ *  · `HttpError` 构造期(`security.ts`):带保留键 ⇒ 构造即抛,落普通 500 臂(早失败);
+ *  · 出线点(`http/send.ts` 的拒体写口,`sendError` / `sendHttpError` 汇合处):按**最终字节**判({@link refusalWireBytes}),不对 ⇒ 不抛、答 500 开面故障。
+ * 挡:一切被执行到、经组句器或经那只写口出线的拒体(含扩宽的 `Record`、展开、断言、外部对象、构造后改写、`toJSON` 劫持)。
+ * 不挡:没被执行到的路径;组句之后、不经那只写口出线的交回体上的就地改写。
  */
 export interface Refusal {
     readonly errorCode: string;
@@ -16,8 +28,29 @@ export type RefusalBody = {
     readonly error: string;
     readonly errorCode: string;
 } & Record<string, unknown>;
-/** 拒体:`{ error, errorCode, ...facts }`。 */
+/**
+ * 事实不得带的顶层键(一张表,三处读 —— 见文件头):`error` / `errorCode` = 体头(事实摊在头之后,同名即盖掉码或句);`detail` = 退役的包装位(版式律:根上没有它);
+ * `toJSON` = 摊上体顶层就接管整只体的序列化(体出线时被换成它的返回值)。
+ */
+export declare const REFUSAL_RESERVED_KEYS: readonly ["error", "errorCode", "detail", "toJSON"];
+export type RefusalReservedKey = (typeof REFUSAL_RESERVED_KEYS)[number];
+/** 一份事实里第一只保留键(按自有可枚举键读 —— 与展开读的是同一组键);没有 ⇒ `undefined`。 */
+export declare function refusalReservedKeyOf(facts: Readonly<Record<string, unknown>>): RefusalReservedKey | undefined;
+/** 带保留键的事实的那一句(组句器与 `HttpError` 构造期同一句;只点名码与键,不带值)。 */
+export declare function refusalReservedKeyMessage(errorCode: string, key: RefusalReservedKey): string;
+/** 拒体:`{ error, errorCode, ...facts }`。事实带保留键 ⇒ 抛(见文件头)。 */
 export declare function refusalBody(r: Refusal): RefusalBody;
+/**
+ * 一只拒出线的**最终字节**(出线点的唯一读法):组句({@link refusalBody})→ 序列化 → 按序列化之后读回的顶层键判,逐只读保留键表 —— 顶层不是对象、
+ * `error` / `errorCode` 不是这只拒的句与码、根上有表里其余的键(`detail` / `toJSON`)⇒ 抛。按字节判而不是按对象判:构造后被改写的事实、`toJSON`、
+ * 读一次变一次的成员(组句前不可枚举、展开途中才变可枚举的键),在这里读到的就是线上的那一份。
+ */
+export declare function refusalWireBytes(r: Refusal): string;
+/**
+ * 请求坐标的 stringify(`settings.hooks` 面的拒体 `field`、拒句里的坐标与 `unknownKeys` 都经它;其余各面的 `field` 今天仍是各面手拼的串,没有改走这里):`root` 之后逐段 —— 数字段 `[n]`;不含 `.` `[` `]` `"`、空白、控制字符的非空串段 `.seg`;
+ * 其余串段 `[<JSON 串>]`(`settings.hooks["Pre.Tool"][0]`)。坐标是不透明定位串,消费方不反解;段里的调用方文本先由各面自己的回显口径收(本函数不脱敏、不截断)。
+ */
+export declare function fieldCoordinate(root: string, segs: readonly (string | number)[]): string;
 /**
  * 引擎拒一次续跑时的**机读事实位** → 拒体的同名事实键(唯一读法;续跑家族的每一只拒答都读它):
  * `detail.code` ⇒ `blockedBy`(挡住它的准入码)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂)·

package/dist/http/refusal-body.js

@@ -1,6 +1,40 @@
+export const REFUSAL_RESERVED_KEYS = ["error", "errorCode", "detail", "toJSON"];
+export function refusalReservedKeyOf(facts) {
+    return REFUSAL_RESERVED_KEYS.find((k) => Object.prototype.propertyIsEnumerable.call(facts, k));
+}
+export function refusalReservedKeyMessage(errorCode, key) {
+    return `refusal ${errorCode}: its facts carry the reserved key "${key}" — a refusal's facts sit at the root of its body beside error / errorCode, never under detail`;
+}
 export function refusalBody(r) {
+    if (r.facts !== undefined) {
+        const reserved = refusalReservedKeyOf(r.facts);
+        if (reserved !== undefined)
+            throw new TypeError(refusalReservedKeyMessage(r.errorCode, reserved));
+    }
     return { error: r.message, errorCode: r.errorCode, ...r.facts };
 }
+export function refusalWireBytes(r) {
+    const bytes = JSON.stringify(refusalBody(r));
+    const back = JSON.parse(bytes);
+    if (back === null || typeof back !== "object" || Array.isArray(back))
+        throw new TypeError(`refusal ${r.errorCode}: its body did not serialize as an object`);
+    const top = back;
+    const onWire = { error: r.message, errorCode: r.errorCode, detail: undefined, toJSON: undefined };
+    for (const key of REFUSAL_RESERVED_KEYS) {
+        const own = onWire[key];
+        if (own === undefined ? Object.hasOwn(top, key) : top[key] !== own) {
+            throw new TypeError(own === undefined ? refusalReservedKeyMessage(r.errorCode, key) : `refusal ${r.errorCode}: its serialized body does not carry its own ${key}`);
+        }
+    }
+    return bytes;
+}
+export function fieldCoordinate(root, segs) {
+    let out = root;
+    for (const seg of segs)
+        out += typeof seg === "number" ? `[${seg}]` : PLAIN_SEGMENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`;
+    return out;
+}
+const PLAIN_SEGMENT = /^[^.[\]"\s\p{Cc}]+$/u;
 export function resumeRefusalFacts(detail) {
     if (typeof detail !== "object" || detail === null)
         return {};

package/dist/http/request-guards.d.ts

@@ -4,12 +4,13 @@
  * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type SessionOwnerCell } from "../security.js";
 import { type RefusalBody } from "./refusal-body.js";
+import type { Person } from "../owner-brands.js";
 import type { FlatServiceDeps } from "./server.js";
 import type { LeaseRefusalAdmission } from "../fleet-lease.js";
 import { type QuotaDecision } from "../observability/cost-quota.js";
 import { type SqlWallSource, type SqlWallsReading } from "../plugins/sql-driver.js";
+import type { TerminalSeat } from "./route-ctx.js";
 /**
  * 受理口对一份提交体的库墙判决:被哪一堵墙拒、量到多少、门限多少。提交体要整只落进库 —— 会话日志的用户消息、durable 审批部署上的续跑输入 ——
  * 所以每堵墙各量各的、**量的是店真正发出去的东西**,`null` 的墙不参与(PG 两堵都是 `null`;InnoDB 的行墙是 `null`、包墙在;TiDB 两堵都在):
@@ -76,30 +77,25 @@ export declare function createRequestGuards(ctx: {
     deps: FlatServiceDeps;
 }): {
     quotaExceeded: (req: IncomingMessage, res: ServerResponse) => boolean;
-    ownerCostQuotaDenied: (principal: string | undefined) => {
+    ownerCostQuotaDenied: (person: Person | undefined) => {
         status: number;
         body: object;
     } | undefined;
-    ownerFleetLeaseDenied: (owner: string | undefined) => Promise<{
+    ownerFleetLeaseDenied: (person: Person | undefined) => Promise<{
         status: number;
         body: object;
     } | undefined>;
-    ownerLeaseDenied: (res: ServerResponse, owner: string | undefined) => Promise<boolean>;
-    ownerQuotaDenied: (res: ServerResponse, owner: string | undefined) => boolean;
-    leaseDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
-    usageWindowDenialFor: (key: string) => Promise<{
+    ownerLeaseDenied: (res: ServerResponse, person: Person | undefined) => Promise<boolean>;
+    ownerQuotaDenied: (res: ServerResponse, person: Person | undefined) => boolean;
+    leaseDenied: (req: IncomingMessage, res: ServerResponse, seat?: TerminalSeat) => Promise<boolean>;
+    usageWindowDenialFor: (person: Person | undefined) => Promise<{
         status: number;
         body: RefusalBody;
         retryAfterSec: number;
     } | undefined>;
-    usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+    usageWindowDenied: (req: IncomingMessage, res: ServerResponse, seat?: TerminalSeat) => Promise<boolean>;
     rateLimited: (req: IncomingMessage, res: ServerResponse) => boolean;
     safeDecode: (seg: string) => string | null;
-    runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
-    sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell) => boolean;
-    runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {
-        sessionId: string | null;
-    }, face: string, notFoundError?: string) => boolean;
     readJson: (req: IncomingMessage) => Promise<unknown>;
     readRawBody: (req: IncomingMessage, max: number) => Promise<Buffer>;
 };

package/dist/http/request-guards.js

@@ -1,15 +1,14 @@
 import { GLOBAL_USAGE_KEY, usageRetryAfterMs } from "@sema-agent/core";
 import { createCodedHttpError, principalFrom } from "../security.js";
-import { RUN_NOT_FOUND_MESSAGE, SESSION_NOT_FOUND_MESSAGE } from "./route-ctx.js";
 import { invalidJsonError, sendError } from "./send.js";
 import { refusalBody } from "./refusal-body.js";
 import { limitFactsUnmeasured } from "../limit-refusal.js";
-import { gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, sendPrincipalRefusal } from "./principal-gate.js";
-import { runRowReadable } from "./owner-access.js";
-import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
+import { gatedPerson } from "./principal-gate.js";
 import { quotaWindowResetsAt } from "../observability/cost-quota.js";
 import { escapedStatementBytes, packetWallStatementBytes, rowWallPayloadBytes } from "../plugins/sql-driver.js";
 import { MAX_JSON_BODY_BYTES } from "../json-body-limit.js";
+import { deliverVia } from "../submission-exit.js";
+import { canonicalAddress } from "../net-address.js";
 export function refuseSubmitBody(walls, body) {
     const rowWall = walls.maxRowBytes;
     const packetWall = walls.maxPacketBytes;
@@ -73,10 +72,10 @@ export function createRequestGuards(ctx) {
     function quotaExceeded(req, res) {
         if (!deps.costQuota)
             return false;
-        const principal = gatedPrincipal(req, deps.config);
-        if (!principal)
+        const person = gatedPerson(req, deps.config);
+        if (!person)
             return false;
-        const d = deps.costQuota.check(principal);
+        const d = deps.costQuota.check(person);
         if (d.allowed)
             return false;
         deps.metrics?.inc("cost_quota_rejected_total");
@@ -86,37 +85,37 @@ export function createRequestGuards(ctx) {
         sendError(res, status, errorCode, error, extra);
         return true;
     }
-    function ownerCostQuotaDenied(principal) {
-        if (!deps.costQuota || !principal)
+    function ownerCostQuotaDenied(person) {
+        if (!deps.costQuota || !person)
             return undefined;
-        const d = deps.costQuota.check(principal);
+        const d = deps.costQuota.check(person);
         if (d.allowed)
             return undefined;
         deps.metrics?.inc("cost_quota_rejected_total");
         return costQuotaRefusalOf(d);
     }
-    async function ownerFleetLeaseDenied(owner) {
-        if (!deps.fleetLease || !owner)
+    async function ownerFleetLeaseDenied(person) {
+        if (!deps.fleetLease || !person)
             return undefined;
-        const adm = await deps.fleetLease.admit(owner);
+        const adm = await deps.fleetLease.admit(person);
         if (adm.ok)
             return undefined;
         deps.metrics?.inc("fleet_lease_rejected_total");
         const refusal = leaseRefusalOf(adm);
         return { status: refusal.status, body: refusal.body };
     }
-    async function ownerLeaseDenied(res, owner) {
-        if (!deps.fleetLease || !owner)
+    async function ownerLeaseDenied(res, person) {
+        if (!deps.fleetLease || !person)
             return false;
-        const adm = await deps.fleetLease.admit(owner);
+        const adm = await deps.fleetLease.admit(person);
         if (adm.ok)
             return false;
         deps.metrics?.inc("fleet_lease_rejected_total");
         sendLeaseRefusal(res, leaseRefusalOf(adm));
         return true;
     }
-    function ownerQuotaDenied(res, owner) {
-        const denial = ownerCostQuotaDenied(owner);
+    function ownerQuotaDenied(res, person) {
+        const denial = ownerCostQuotaDenied(person);
         if (!denial)
             return false;
         const { errorCode, error, ...extras } = denial.body;
@@ -124,20 +123,22 @@ export function createRequestGuards(ctx) {
         sendError(res, denial.status, errorCode, error, extras);
         return true;
     }
-    async function leaseDenied(req, res) {
+    async function leaseDenied(req, res, seat) {
         if (!deps.fleetLease)
             return false;
-        const principal = gatedPrincipal(req, deps.config);
-        if (!principal)
+        const person = gatedPerson(req, deps.config);
+        if (!person)
             return false;
-        const adm = await deps.fleetLease.admit(principal);
+        const adm = await deps.fleetLease.admit(person);
         if (adm.ok)
             return false;
         deps.metrics?.inc("fleet_lease_rejected_total");
-        sendLeaseRefusal(res, leaseRefusalOf(adm));
+        const refusal = leaseRefusalOf(adm);
+        await deliverVia(seat, () => sendLeaseRefusal(res, refusal));
         return true;
     }
-    async function usageWindowDenialFor(key) {
+    async function usageWindowDenialFor(person) {
+        const key = person || GLOBAL_USAGE_KEY;
         const store = deps.usageWindowStore;
         const windows = deps.config.usageWindows;
         if (!store || !windows || windows.length === 0)
@@ -157,18 +158,21 @@ export function createRequestGuards(ctx) {
         const retryAfterSec = Math.max(1, Math.ceil(retryAfterMs / 1000));
         return { status: 429, body: refusalBody({ errorCode: "usage.window_exhausted", message: "usage window exhausted (deployment token governance)", facts: { retryAfterSec } }), retryAfterSec };
     }
-    async function usageWindowDenied(req, res) {
-        const denial = await usageWindowDenialFor(gatedPrincipal(req, deps.config) || GLOBAL_USAGE_KEY);
+    async function usageWindowDenied(req, res, seat) {
+        const denial = await usageWindowDenialFor(gatedPerson(req, deps.config));
         if (!denial)
             return false;
-        res.setHeader("retry-after", String(denial.retryAfterSec));
-        sendError(res, denial.status, denial.body.errorCode, denial.body.error, { retryAfterSec: denial.retryAfterSec });
+        await deliverVia(seat, () => {
+            res.setHeader("retry-after", String(denial.retryAfterSec));
+            sendError(res, denial.status, denial.body.errorCode, denial.body.error, { retryAfterSec: denial.retryAfterSec });
+        });
         return true;
     }
     function rateLimited(req, res) {
         if (!deps.rateLimiter)
             return false;
-        const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? req.socket.remoteAddress ?? "anon";
+        const peer = req.socket.remoteAddress;
+        const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? (peer === undefined ? "anon" : (canonicalAddress(peer) ?? peer));
         const d = deps.rateLimiter.check(key);
         if (d.allowed)
             return false;
@@ -185,44 +189,6 @@ export function createRequestGuards(ctx) {
             return null;
         }
     }
-    function ownerGate(req, res, readable, notFound) {
-        const principal = gatedPrincipal(req, deps.config);
-        if (DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deps.config) && !principal) {
-            sendPrincipalRefusal(res, req, deps.config);
-            return false;
-        }
-        if (!readable(principal)) {
-            notFound();
-            return false;
-        }
-        return true;
-    }
-    function runOwnerOk(req, res, owner) {
-        return ownerGate(req, res, (principal) => runRowReadable(deps.config, principal, owner, "owner"), () => sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE));
-    }
-    function sessionOwnerOk(req, res, cell) {
-        const caller = sessionCallerOf(req, deps);
-        return ownerGate(req, res, () => sessionOwnerReadable(caller, cell, deps), () => sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE));
-    }
-    const sessionAssertAbsentWarned = new Set();
-    function runSessionAcceptOk(req, res, run, face, notFoundError = RUN_NOT_FOUND_MESSAGE) {
-        if (!run.sessionId)
-            return true;
-        const asserted = new URL(req.url ?? "", "http://x").searchParams.get("session");
-        if (asserted === null) {
-            if (!sessionAssertAbsentWarned.has(face)) {
-                sessionAssertAbsentWarned.add(face);
-                console.warn(JSON.stringify({ ts: new Date().toISOString(), level: "warn", msg: "run_face_session_assert_absent", face, note: "caller sent no ?session= on a session-bound run — allowed in the accept phase; the enforcement train will 404 this ([1498]⑥/[1499])" }));
-            }
-            return true;
-        }
-        if (asserted === run.sessionId)
-            return true;
-        if (explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config))
-            return true;
-        sendError(res, 404, "not_found.run", notFoundError);
-        return false;
-    }
     async function readJson(req) {
         const chunks = [];
         let size = 0;
@@ -252,6 +218,6 @@ export function createRequestGuards(ctx) {
         }
         return Buffer.concat(chunks);
     }
-    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
+    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, readJson, readRawBody };
 }
 //# sourceMappingURL=request-guards.js.map

package/dist/http/resume-composition.d.ts

@@ -0,0 +1,37 @@
+/**
+ * **续跑腿接着跑哪一只组合入口** —— 停驻的那条 run 当初是怎么提交的(续跑输入里的提交体),就怎么续:
+ *  · `verify` —— 验证门(core `resumeWithVerification`:续上实现腿,跑完再验、再修);
+ *  · `cascade` —— 梯子(core `resumeCascade`:续上停在门上的那一级,再按门判接着往上爬);入参里的那一级 = 卡上记的组合腿(`CheckpointState.compositionLeg`,
+ *    「as the card records it」—— 引擎拿它对卡,记的不是这一级 ⇒ 续跑前拒 `resume.composition_mismatch`,卡不动);梯子 = 本部署的 `CASCADE_LADDER`
+ *    与提交时同一只 {@link cascadeConfig};
+ *    梯子那一臂另带**原目标上挂的输入**({@link CascadeObjectiveInputs}):续上那一级之后的每一级是原任务的冷重跑,core 要的是原 spec(「objective,
+ *    attachments … included」,自己从续上的那一级剥掉)—— 续跑重建在体那一层剥了它们(一次性动作,`resume-legs.ts` 的一次性键表),这里自提交体照受理口的读法交回;
+ *  · 缺席 —— 普通腿(`resumeStream`)。
+ * 两个入口不并存(受理口拒 `cascade` + `verify` 同在)。读的是提交体与卡,不读店、不抛:提交体说 `cascade` 而卡上没有梯子那一级的记录 ⇒
+ * {@link ResumeCompositionUnlinked}(调用方答 409 —— 那张卡不是这条 run 的梯子停下的,续不了;归属读法让它够不着这里,见 `hostSessionOf`)。
+ */
+import type { CascadeConfig, Checkpoint, CompositionLeg, TaskSpec } from "@sema-agent/core";
+import { type VerifyRoundsSpec } from "./verify-rounds.js";
+import type { TaskRequestBody } from "./wire-types.js";
+/**
+ * 原目标上挂的输入(提交体的 `userAttachments` / `images`,与受理口装配 `boot/resolve-spec.ts` 同一读法:附件在场才带键,图原样)。梯子续跑交给 core 的 spec
+ * 带上它们 —— 续上的那一级 core 自己剥掉附件(耐久续跑不收附件)、续跑路径不读图;之后冷重跑的每一级照原任务收到它们。
+ */
+export type CascadeObjectiveInputs = Pick<TaskSpec, "userAttachments" | "images">;
+/** 续跑腿的组合入口(闭集:加一种入口 ⇒ 读它的 `switch` 编译红)。 */
+export type ResumeComposition = {
+    readonly entry: "verify";
+    readonly rounds: VerifyRoundsSpec;
+} | {
+    readonly entry: "cascade";
+    readonly config: CascadeConfig;
+    readonly parkedLeg: CompositionLeg;
+    readonly objectiveInputs: CascadeObjectiveInputs;
+};
+/** 提交体说 `cascade`,卡上却没有梯子那一级的记录:这张卡续不了这条 run 的梯子。 */
+export interface ResumeCompositionUnlinked {
+    readonly entry: "cascade_unlinked";
+}
+/** 这条 run 的组合入口(见模块头注);`undefined` = 普通腿。 */
+export declare function resumeCompositionOf(body: Pick<TaskRequestBody, "verify" | "verifyRounds" | "maxCostUsd" | "cascade" | "userAttachments" | "images">, card: Pick<Checkpoint, "state">, cascadeLadder: readonly string[]): ResumeComposition | ResumeCompositionUnlinked | undefined;
+//# sourceMappingURL=resume-composition.d.ts.map

package/dist/http/resume-composition.js

@@ -0,0 +1,18 @@
+import { cascadeConfig } from "./run-meta.js";
+import { verifyRoundsFromBody } from "./verify-rounds.js";
+export function resumeCompositionOf(body, card, cascadeLadder) {
+    const rounds = verifyRoundsFromBody(body);
+    if (rounds !== undefined)
+        return { entry: "verify", rounds };
+    if (body.cascade !== true)
+        return undefined;
+    const leg = card.state?.compositionLeg;
+    if (typeof leg !== "object" || leg === null || leg.entry !== "cascade")
+        return { entry: "cascade_unlinked" };
+    const objectiveInputs = {
+        ...(body.userAttachments !== undefined ? { userAttachments: body.userAttachments } : {}),
+        ...(body.images !== undefined ? { images: body.images } : {}),
+    };
+    return { entry: "cascade", config: cascadeConfig(cascadeLadder, body.maxCostUsd), parkedLeg: leg, objectiveInputs };
+}
+//# sourceMappingURL=resume-composition.js.map

package/dist/http/resume-ctx-read.d.ts

@@ -6,21 +6,22 @@
  * 机制上「坏体不再与缺席同答」成立,**用户面上不成立**(用户拿到的还是同一个 409)。判据要钉用户实际
  * 拿到的码,这只铸点就是让那句判据有地方落(test [ref] 的判据订正,当拍采纳)。
  *
- * 三态与各自的理由:
+ * 各态与各自的理由(店边界的读失败**怎么分类只在一处答**:整仓唯一的店故障判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,
+ * 本口按它的五词逐词落地 —— 一张穷举 `switch`,判官加词而这里不表态 = 编译错;本口自己不认任何错误类):
  *  · `ok` —— 读出来了。
- *  · `absent` —— 行不在(`reapCtx` 按设计在 run 终态后删掉它),**或**读腿抛了一个**不是坏体**的错
- *    (连接 / 超时 / 权限 / 店抖动):证不出它在就当它不在,**这是刻意保守**([ref] 方向锚:
- *    拒绝可重试,搁浅不可)。
- *  · `corrupt` —— 店给了它的**拒绝契约**(`StoreCorruptError`,`kind:"corrupt"` + 坐标)。
+ *  · `absent` —— 店答了「这一行不在」(`null`;`reapCtx` 按设计在 run 终态后删掉它)。**只有**店的这一句答才是缺席:
+ *    读失败证不出它在,也证不出它不在,所以不进这一态(修前把连接 / 超时 / 权限 / 店抖动一并读成缺席 —— 断连下续跑被答成
+ *    「续跑上下文没了,作为新任务重提」,出路说错,且与判官对同一只错的读法是两份)。
+ *  · `corrupt` —— 判官的 `corrupt`(店的**拒绝契约** `StoreCorruptError`,`kind:"corrupt"` + 坐标)。
  *    **不折成缺席**:两者的运维动作完全不同(前者去查那一行,后者什么都不用做)。
- *    ⚠️ `not-text`(投影漂 = 我方的码病)**刻意不进这一态**,原样上抛、响亮成 500 —— 不许伪装成
- *    「数据坏了」,更不许折成缺席(那会让一次代码漂看起来像「这条会话没有上下文」)。
+ *  · `unreadable` —— 判官的 `connection` / `deployment` / `unclassified`:这一次读失败了(库断连 / 拒连 / 超时、缺表 / 权限拒、
+ *    认不出的库错)。各续跑入口答 {@link resumeCtxUnreadableAnswer}(503 `state.resume_context_unreadable`):这一请求没有执行,稍后重发 ——
+ *    与审批队列读口对「此刻读不出」的读法同一条(判官的这三词并成一个答;[ref] 方向锚「拒绝可重试,搁浅不可」照旧成立:拒在任何状态改动之前)。
+ *  · 判官的 `defect`(本服务自己的程序错:运行时的六只原生错误类、读腿漂移 `SqlJsonColumnError` 的 `not-text`)⇒ **原样上抛**,响亮成 500 ——
+ *    不许伪装成「数据坏了」,也不许折成「此刻读不出」或缺席(那会让一次代码漂看起来像「这条会话没有上下文」,或劝人重试一件注定失败的事)。
  *
- * 🔴 **按「店的拒绝形」分类,不按「列错误类」**([ref],7.95.1:这一句此前反了,整整一版)。修前本口
- * 认的是属主谓词 `isJsonColumnBodyProblem`(= 一只 `SqlJsonColumnError`),而 SQL 两孪生的 `refusing()`
- * 早把列错误**折**成了一只普通 `Error` ⇒ 折后的错落进下面那条「店抖动 ⇒ 当缺席」臂,坏体与缺席在
- * 用户面上仍然同答 409 —— 正是 [ref] 第二半要修的那个病,只是它当时只在 local 车道上修成了(那一侧
- * 恰好没折码,把列错误漏了出来 = 巧合式正确)。两条车道现在同一份拒绝契约,本口只认它。
+ * 🔴 **按「店的拒绝形」分类,不按「列错误类」**([ref],7.95.1)。SQL 两孪生的 `refusing()` 把列错误**折**成店的拒绝契约,
+ * 两条车道同一份拒绝契约;判官认的就是它(`corrupt`),本口不再持有自己的那一份。
  *
  * 🔴 **第四态 `unsealable`([ref],7.134.0):读出来了,但凭据位上的封签开不开**。店交出的是**落盘形**(凭据位上是封签,`StoredCheckpointCtx`);
  * 本口在任何消费者看到之前经**唯一**开口 `openCheckpointCtx` 开封(规则属主 = `checkpoint-ctx.ts` 末段「凭据位密封」)—— 所以 `ok` 交出的恒是开封形,
@@ -43,6 +44,8 @@ export type ResumeCtxRead = {
 } | {
     readonly kind: "corrupt";
     readonly where: string;
+} | {
+    readonly kind: "unreadable";
 } | {
     readonly kind: "unsealable";
     readonly field: string;
@@ -54,6 +57,37 @@ export interface CheckpointCtxOpening {
     readonly opener: CheckpointCtxOpener | undefined;
 }
 export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: CheckpointCtxOpening): Promise<ResumeCtxRead>;
+/**
+ * 续跑家族一次店往返失败的落点 —— 判官的五词逐词表态,**只在这一处**。三个读者同读它:本口读续跑上下文那一读、续跑腿读「这张卡归哪条 run」那一读,
+ * 与续跑腿的认领(`resume-legs.ts` 的 `resumeClaimFaultAnswerOf`:认领那一笔,或认领之后执行席那一次读 / 写失败 —— 后者的认领已由写口撤回)。
+ * `corrupt` ⇒ 坏体(带坐标);`connection` / `deployment` / `unclassified` ⇒ 读不出 / 写不进;`defect` ⇒ 原样上抛。
+ */
+export declare function resumeStoreFailureOf(e: unknown): {
+    readonly kind: "corrupt";
+    readonly where: string;
+} | {
+    readonly kind: "unreadable";
+};
+/**
+ * 读失败的对外答复 —— 503 `state.resume_context_unreadable`:这一次读这条会话的续跑上下文失败了(判官的 `connection` / `deployment` / `unclassified`),
+ * 这一请求**没有执行**(拒在任何状态改动之前:卡仍待决、行字节不动、一次性 nonce 未烧),稍后原样重发;一直如此 ⇒ 请运维查库。句子不带店层 detail(内部机件不上 wire,[ref] 同律)。
+ * 全部续跑入口与终态 steer 的铸卡证明腿同一只答(码 / 句同源)。
+ * 🔴 形是给冻结门看的(与 {@link resumeCtxCorruptAnswer} 同一条):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function resumeCtxUnreadableAnswer(): {
+    status: number;
+    body: RefusalBody;
+};
+/**
+ * 续跑腿**认领**撞店故障的对外答复 —— 认领那一笔(`markResuming` / wake 现建行的 `createRun`)或认领之后那一次提交(执行席的再读 / 落格)。
+ * 与 {@link resumeCtxUnreadableAnswer} **同码同状态**(503 `state.resume_context_unreadable`:店这一拍没答出来,这一请求没有执行,稍后原样重发;一直如此 ⇒ 请运维查库),
+ * 句子说的是这一形自己的事:读或写这条任务的存储状态失败了,卡仍待决(认领之后那一形的认领已由写口撤回到取来时的样子)。句子不带店层 detail。
+ * 🔴 形是给冻结门看的(与 {@link resumeCtxCorruptAnswer} 同一条):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function resumeClaimFaultAnswer(): {
+    status: number;
+    body: RefusalBody;
+};
 /**
  * 开不开的对外答复([ref])—— 409 `conflict.checkpoint_ctx_unsealable`,机读 `field`(哪一个凭据位,提交体路径;键名不是秘密,值从不进来)+ `reason`
  * (闭集 `CHECKPOINT_CTX_UNSEALABLE_REASONS`)。句子说「这条任务的续跑上下文里带的凭据本服务开不开」、五种成因与出路(按 `reason` 修好保管目录后原样重发,