@sema-agent/server 7.147.0 → 7.148.0

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

@@ -1,6 +1,8 @@
 import type { RunStore } from "../plugins/store-backend.js";
 import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
+import { type CtxWriteClaim } from "../plugins/store-contracts.js";
+import type { CtxClaimPut } from "../plugins/checkpoint-store-face.js";
 import { buildCheckpointCtx, type CheckpointCtxSealer, type SealedCheckpointCtx } from "./checkpoint-ctx.js";
 import { type RefusalBody } from "./refusal-body.js";
 import type { CheckpointCtx, PreparedTaskSubmission } from "./route-ctx.js";
@@ -11,28 +13,34 @@ export interface SubmitCtxRefusal {
     readonly status: 413 | 409;
     readonly body: RefusalBody;
 }
+/**
+ * 栅栏答「认领已失」([ref]):零写;本请求刚认领的那条 run 已被收割判决终局、认领已放 ⇒ 不撤。调用方**当拍**按起跑前复核的同一只三臂答复
+ * (`claim-heartbeat.ts` `refusalAfterLostClaim` / `recheckClaimBeforeLaunch`),在任何后续写(workflow 决定落行)与起跑之前。
+ */
+export declare const SUBMIT_CTX_CLAIM_LOST: "claim_lost";
+/** 提交腿的续跑输入写口(检查点店唯一写口的那一面):有认领 ⇒ 交认领、栅栏写;没有 ⇒ 无条件写。 */
+export interface SubmitCtxStore {
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx, claim?: CtxWriteClaim): Promise<CtxClaimPut | void>;
+}
 /**
  * 写这一笔(行体经续跑输入的唯一构造口 `buildCheckpointCtx` 铸 —— 新的持久化写都经它,读法记号随之盖上);写不进 ⇒ 撤掉
  * `claim` 指的那条刚认领的 run(无 run 店的部署没有认领 ⇒ `undefined`),再按成因答复(见文件头)。
  * 返回 `undefined` = 写进了,腿照常起跑。
  */
-export declare function persistSubmitCtx(store: {
-    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
-}, deps: {
+export declare function persistSubmitCtx(store: SubmitCtxStore, deps: {
     readonly logger?: Logger | undefined;
     readonly metrics?: Metrics | undefined;
     readonly checkpointCtxSealing?: CheckpointCtxSealer | undefined;
+    readonly instanceId?: string | undefined;
 }, claim: {
     readonly runStore: RunStore;
     readonly taskId: string;
-} | undefined, sessionId: string, fields: Parameters<typeof buildCheckpointCtx>[0]): Promise<SubmitCtxRefusal | undefined>;
+} | undefined, sessionId: string, fields: Parameters<typeof buildCheckpointCtx>[0]): Promise<SubmitCtxRefusal | typeof SUBMIT_CTX_CLAIM_LOST | undefined>;
 /**
  * 提交腿写续跑输入的入口(三个调用点同调这一只):体与标记按受理座提交时交出的那一份定(见文件头「体里的目标按哪一份写」),只写这一笔。
  * 写不进的处置与答复 = {@link persistSubmitCtx}(本函数只定体、不另判)。
  */
-export declare function persistSubmissionCtx(store: {
-    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
-}, deps: Parameters<typeof persistSubmitCtx>[1], claim: Parameters<typeof persistSubmitCtx>[2], prepared: Pick<PreparedTaskSubmission, "body" | "auth" | "verify" | "acceptance" | "bodyFromScreenedCtx"> & {
+export declare function persistSubmissionCtx(store: SubmitCtxStore, deps: Parameters<typeof persistSubmitCtx>[1], claim: Parameters<typeof persistSubmitCtx>[2], prepared: Pick<PreparedTaskSubmission, "body" | "auth" | "verify" | "acceptance" | "bodyFromScreenedCtx"> & {
     readonly spec: Pick<PreparedTaskSubmission["spec"], "sessionId" | "model">;
-}): Promise<SubmitCtxRefusal | undefined>;
+}): Promise<SubmitCtxRefusal | typeof SUBMIT_CTX_CLAIM_LOST | undefined>;
 //# sourceMappingURL=submit-ctx.d.ts.map

package/dist/http/submit-ctx.js

@@ -1,5 +1,6 @@
 import { StoreRowTooLargeError } from "../plugins/sql-errors.js";
 import { releaseClaimedRun } from "./claimed-run.js";
+import { runProvenElsewhere } from "../plugins/store-contracts.js";
 import { buildCheckpointCtx, CheckpointCtxUnsealableError } from "./checkpoint-ctx.js";
 import { refusalBody } from "./refusal-body.js";
 import { limitFactsUnmeasured } from "../limit-refusal.js";
@@ -14,6 +15,7 @@ function withheldBody(body, picked) {
     const pin = typeof body.model !== "string" && typeof picked === "string" && picked !== DEFAULT_MODEL_REF ? { model: picked } : {};
     return { ...body, objective: WITHHELD_OBJECTIVE, ...pin };
 }
+export const SUBMIT_CTX_CLAIM_LOST = "claim_lost";
 function unsealableRefusal(e) {
     return {
         status: 409,
@@ -39,9 +41,10 @@ function rowTooLargeRefusal(tooLarge) {
     }
 }
 export async function persistSubmitCtx(store, deps, claim, sessionId, fields) {
+    let landed;
     try {
-        await store.putCtx(sessionId, buildCheckpointCtx(fields, deps.checkpointCtxSealing, sessionId));
-        return undefined;
+        const ctx = buildCheckpointCtx(fields, deps.checkpointCtxSealing, sessionId);
+        landed = await store.putCtx(sessionId, ctx, claim === undefined ? undefined : { fence: claim.runStore, taskId: claim.taskId, legHolds: (run) => !runProvenElsewhere(run, deps.instanceId) });
     }
     catch (err) {
         const tooLarge = err instanceof StoreRowTooLargeError ? err : undefined;
@@ -63,6 +66,7 @@ export async function persistSubmitCtx(store, deps, claim, sessionId, fields) {
         deps.logger?.warn("submit_ctx_row_too_large", { sessionId, taskId: claim?.taskId, wall: tooLarge.wall, db: tooLarge.dbMessage });
         return rowTooLargeRefusal(tooLarge);
     }
+    return landed === "claim_released" ? SUBMIT_CTX_CLAIM_LOST : undefined;
 }
 export async function persistSubmissionCtx(store, deps, claim, prepared) {
     const sessionId = prepared.spec.sessionId;

package/dist/http/submit-replay.d.ts

@@ -9,7 +9,7 @@
  *
  * ## 判定(三条,按序;别的一律不放)
  *  · 这次提交自带 taskId 而命中的行**不是**那一条(`Idempotency-Key` 指向别的行)⇒ 冲突;
- *  · 调用方读不到这一行(属主门 = `runOwnerReadable`,「这个调用方读得到这一行 run 吗」的唯一谓词,经属主存取器 `owner-access.ts` 读)⇒ 冲突;
+ *  · 调用方读不到这一行(属主门 = `qualsOf`,「这个调用方读得到这一行 run 吗」的唯一谓词,经属主存取器 `owner-access.ts` 读)⇒ 冲突;
  *    冲突 ⇒ `409 conflict.run_exists`,体里**不回显**那条行的任何标识(不给跨租户预言机)。先于下一条判:读不到的行不比体。
  *  · 这次提交带 `Idempotency-Key`(`caller.idem` 在场)、那一行绑的**就是这把键**,而它记着的请求体指纹与这次不同 ⇒
  *    `409 conflict.idempotency_payload_mismatch`(同形 `{ error, errorCode }`,不回显键与那一行);**不**回放首发、不新建、那一行不动。
@@ -21,29 +21,42 @@
  *  · `sync`(`POST /v1/tasks`;`/v1/tasks/stream` 把同一份体放进 `done.result`)—— `200 { …首答的信封, replay: true }`:
  *    首答的信封由 `http/sync-submit-body.ts` 铸(`buildSyncSubmitBody`),重放经同文件的 `syncSubmitBodyOfRow` 读行 ——
  *    终局 / 停驻行上有结果 ⇒ 与首答同形(结果的键在顶层,`result` 是串);行上没有结果可交(首投还在跑)⇒ 轮询回执 `{ taskId, sessionId, status }`。
- *    `replay: true` 是重放的判别位(本函数叠上,不在信封里)。
+ *    `replay: true` 是判别位,经 {@link replayedOutcome} 叠上(不在信封里)。
+ *
+ * ## `replay` 位(一条律,唯一铸点 {@link replayedOutcome})
+ * `replay: true` ⇔ 这是一份 **200** 结局,而它**不是本次请求产出的** —— 两处来路,一个判别位:本函数读行作答(`sync` 形),与在飞合流的跟随方
+ * (同一进程里并发的同键同体请求,结局是首发那一次的;`POST /v1/tasks` 与 `/v1/tasks/stream` 两腿同读)。拒绝(非 200)永不带位:拒绝说的是
+ * 「这次没受理」,不是另一次提交的结局 —— 本函数的两只 409、流式腿开流之后才判出的拒绝、合流到的首发拒绝都一样。流式腿终帧的 `done.replay`
+ * 是结局自己这一只位的投影({@link isReplayedOutcome}),写点不另盖。`durable` 形的 202 回执不是结局,不带位。
  */
 import type { RunIdemBinding, RunRecord } from "../plugins/store-contracts.js";
 import type { RunStore } from "../plugins/store-backend.js";
 import type { ServiceConfig } from "../config-types.js";
 import type { SubmitOutcome } from "./idempotency.js";
-import type { Principal } from "../security.js";
+import type { Subject } from "../owner-brands.js";
 /** 提交腿的回执形(闭集;穷举 `switch`,加一形不写这里 = 编译红)。 */
 export type SubmitReplayFace = "durable" | "sync";
 /** 发起这次提交的一方。 */
 export interface ReplayCaller {
-    /** 已验身份(`gatedPrincipal` 的回值,`Principal` 品牌)。 */
-    principal: Principal | undefined;
+    /** 已验主体(分区键;`gatedSubject` 的回值,`Subject` 品牌)。 */
+    subject: Subject | undefined;
     /** 这次提交自带的 taskId(`body.taskId`;A2A 派生值)。缺席 = 只凭 `Idempotency-Key` 命中。 */
     clientTaskId?: string;
     /** 这次提交的账本绑定(键 + 请求体指纹;`RunIdemBinding`)。`undefined` = 这次提交没带 `Idempotency-Key`(只凭 `body.taskId`)⇒ 不比体。
      *  必填位(值可为 `undefined`):每个调用点都得当面说出它有没有绑定,漏传是编译错误,不是静默不比。 */
     idem: RunIdemBinding | undefined;
 }
+/**
+ * `replay: true` 的**唯一**铸点(律见文件头「`replay` 位」):200 ⇒ 体上叠位(结局对象的其余键与 `wiringManifest` 回执原样带过);非 200 ⇒ 原样交回。
+ * 提交面的 200 体恒是对象(三只铸点:同步腿 `buildSyncSubmitBody`、流式腿的结果、本文件读行);不是对象 ⇒ 原样交回(缺席 = 「没有重放证据」,不是「真跑过」)。
+ */
+export declare function replayedOutcome(outcome: SubmitOutcome): SubmitOutcome;
+/** 这份结局带不带 `replay` 位(读 {@link replayedOutcome} 叠上的那一只;流式腿终帧的 `done.replay` 只读它)。 */
+export declare function isReplayedOutcome(outcome: SubmitOutcome): boolean;
 /** 一份提交回执是不是 {@link replayOfExistingRun} 铸的**冲突**体(判别位 = 机器码;铸点就在下面,码与它同文件)—— 把回执渲成别的协议形的
  *  调用方(A2A)按它分句,不另抄码。 */
 export declare function isRunExistsConflictBody(body: unknown): boolean;
-export declare function replayOfExistingRun(row: RunRecord, caller: ReplayCaller, face: SubmitReplayFace, deps: {
+export declare function replayOfExistingRun(seen: RunRecord, caller: ReplayCaller, face: SubmitReplayFace, deps: {
     config: ServiceConfig;
 }, runStore: RunStore): Promise<SubmitOutcome>;
 //# sourceMappingURL=submit-replay.d.ts.map

package/dist/http/submit-replay.js

@@ -1,25 +1,37 @@
-import { runRowReadable } from "./owner-access.js";
+import { runRowAt, seesRunAs } from "./owner-access.js";
+import { claimCallerOf } from "../security.js";
 import { syncSubmitBodyOfRow } from "./sync-submit-body.js";
 import { refusalBody } from "./refusal-body.js";
+export function replayedOutcome(outcome) {
+    const body = outcome.body;
+    if (outcome.status !== 200 || typeof body !== "object" || body === null || Array.isArray(body))
+        return outcome;
+    return { ...outcome, body: { ...body, replay: true } };
+}
+export function isReplayedOutcome(outcome) {
+    const body = outcome.body;
+    return outcome.status === 200 && typeof body === "object" && body !== null && body.replay === true;
+}
 export function isRunExistsConflictBody(body) {
     return typeof body === "object" && body !== null && body.errorCode === "conflict.run_exists";
 }
-export async function replayOfExistingRun(row, caller, face, deps, runStore) {
-    const sameRun = caller.clientTaskId === undefined || caller.clientTaskId === row.taskId;
-    if (!sameRun || !runRowReadable(deps.config, caller.principal, row.owner, "owner")) {
+export async function replayOfExistingRun(seen, caller, face, deps, runStore) {
+    const sameRun = caller.clientTaskId === undefined || caller.clientTaskId === seen.taskId;
+    if (!sameRun || !seesRunAs("run.replay", claimCallerOf(caller.subject, deps.config), seen.owner)) {
         return { status: 409, body: refusalBody({ errorCode: "conflict.run_exists", message: "a run already exists for this submission's taskId or Idempotency-Key" }) };
     }
     if (caller.idem !== undefined) {
-        const held = await runStore.bindIdemBodyFingerprint(row.taskId, caller.idem);
+        const held = await runStore.bindIdemBodyFingerprint(seen.taskId, caller.idem);
         if (held !== null && held !== caller.idem.bodyFingerprint) {
             return { status: 409, body: refusalBody({ errorCode: "conflict.idempotency_payload_mismatch", message: "this Idempotency-Key was already used for a different request body — a retry must resend the same body; send a different request with a new Idempotency-Key" }) };
         }
     }
+    const row = await runRowAt("run.replay", runStore, seen);
     switch (face) {
         case "durable":
             return { status: 202, body: { taskId: row.taskId, sessionId: row.sessionId, status: row.status } };
         case "sync":
-            return { status: 200, body: { ...syncSubmitBodyOfRow(deps, row), replay: true } };
+            return replayedOutcome({ status: 200, body: syncSubmitBodyOfRow(row) });
         default: {
             const unknown = face;
             throw new Error(`replayOfExistingRun: unknown submit face ${String(unknown)}`);

package/dist/http/sync-submit-body.d.ts

@@ -26,7 +26,6 @@
  * `failed.nestedPause.token`)因此在进本函数之前就已摘掉,幂等缓存存的正是本函数的产物,重放体同体同脱。
  */
 import { type ParkedRunStatus, type PersistedTaskResult, type RunRecord } from "../plugins/store-contracts.js";
-import { type RunFaceDeps } from "./run-read-face.js";
 /** 同步 200 体上的 poll 回执三键:一条 run 的 poll 键、会话、对外词。park 体叠在结果之上带它({@link SyncParkReceipt});重放命中一条还没有结果可交的行时,它**就是**整个体({@link syncSubmitBodyOfRow})。 */
 export interface SyncRunReceipt {
     /** 同步腿提交时铸的 durable run id —— `GET /v1/runs/:taskId` 的 poll 键。 */
@@ -50,11 +49,11 @@ export declare function buildSyncSubmitBody<R extends PersistedTaskResult>(exitR
  * (终局 = 结果本身;停驻 = 结果 + 回执三键),与首答的三个 200 出口逐字同形 —— 首答恒 = 「出口封口 + 脱敏后的引擎结果」,那份对象就是落在行上的那一份
  * (调用方铸一次、既落行又进体),重放读到的是它被读入口(同一只 {@link runRowExitResult},`GET /v1/runs/:id` 的 `result` 读的也是它)再封再脱的样子。
  * 行上没有结果可交(首投还在跑、在别的副本上没落定;或终局行的结果已被收割清空)⇒ 首答在这一刻**不存在**,体只剩 {@link SyncRunReceipt} 三键 —— 去 `GET /v1/runs/:taskId` 轮询,
- * 不把「读面」塞进同步体里充首答(失联折叠与读面同一只判据 {@link runRowStale}:折成 `failed`)。
+ * 不把「读面」塞进同步体里充首答。交进来的行已过观察口(重放口 `run.replay`):心跳过期的行在那里已落成 `failed`。
  *
  * 首答体上另有两类**本次请求**的附注(`notice` / `warnings`,见 `routes/tasks.ts` 的 `withSyncSubmitKeys`):重放在 `prepareSpec` 之前就答了,
- * 结构上不知道本次请求带没带 verify / cascade、放行侧选择器里有没有空条目 ⇒ 重放体没有它们。判别位 `replay: true` 由重放出口(`submit-replay.ts`)叠上,不在信封里。
+ * 结构上不知道本次请求带没带 verify / cascade、放行侧选择器里有没有空条目 ⇒ 重放体没有它们。判别位 `replay: true` 由它的唯一铸点(`submit-replay.ts` 的 `replayedOutcome`)叠上,不在信封里。
  * 纯数据 ⇒ `build*` 的近亲;名字取 `…OfRow`(行 → 体的读法),与 `buildSyncSubmitBody` 同文件同铸点。
  */
-export declare function syncSubmitBodyOfRow(deps: RunFaceDeps, row: RunRecord): ReturnType<typeof buildSyncSubmitBody> | SyncRunReceipt;
+export declare function syncSubmitBodyOfRow(row: RunRecord): ReturnType<typeof buildSyncSubmitBody> | SyncRunReceipt;
 //# sourceMappingURL=sync-submit-body.d.ts.map

package/dist/http/sync-submit-body.js

@@ -1,17 +1,16 @@
 import { isParkedRunStatus, isTerminalRunStatus } from "../plugins/store-contracts.js";
-import { runRowExitResult, runRowStale } from "./run-read-face.js";
+import { runRowExitResult } from "./run-read-face.js";
 export function buildSyncSubmitBody(exitResult, parkReceipt) {
     return parkReceipt === undefined ? exitResult : { ...exitResult, ...parkReceipt };
 }
-export function syncSubmitBodyOfRow(deps, row) {
-    const stale = runRowStale(deps, row);
-    const exit = stale ? undefined : runRowExitResult(row);
+export function syncSubmitBodyOfRow(row) {
+    const exit = runRowExitResult(row);
     if (exit !== undefined) {
         if (isTerminalRunStatus(row.status))
             return buildSyncSubmitBody(exit);
         if (isParkedRunStatus(row.status))
             return buildSyncSubmitBody(exit, { taskId: row.taskId, sessionId: row.sessionId, status: row.status });
     }
-    return { taskId: row.taskId, sessionId: row.sessionId, status: stale ? "failed" : row.status };
+    return { taskId: row.taskId, sessionId: row.sessionId, status: row.status };
 }
 //# sourceMappingURL=sync-submit-body.js.map

package/dist/http/wire-types.d.ts

@@ -14,7 +14,8 @@ import type { buildSyncSubmitBody } from "./sync-submit-body.js";
 import type { EntryProblem } from "../entry-problems.js";
 /**
  * 请求面上的一条技能 = core 的 `SkillSpec` 去掉 `mods`(core 7.56.0 [ref] 的技能座扩展注册:带 `register` 函数的代码对象,不是 wire 数据)。
- * 带 `mods` 的请求技能受理门 400(`http/admission.ts` 的 `validateUserSkills`);本服务不编技能 hooks(能力位 `mods.skill_seat` 恒假)。
+ * 本型的键集就是两道技能门(顶层 `skills[i]` 与子代 `agents[a].skills[j]`)的**闭合键表**(`spec-fields.ts` 的 `SKILL_FIELD_SHAPES` 按 `keyof RequestSkill` 铸型):
+ * 表外的键 400 点名坐标(`mods` / 退役的 `manifest` 各一句,其余一句「不是技能的键」);本服务不编技能 hooks(能力位 `mods.skill_seat` 恒假)。
  * 键集仍由 core 本体派生([ref]:core 加键,本型同批跟上;删 `mods` 是唯一的一处减法)。
  */
 export type RequestSkill = Omit<SkillSpec, "mods">;
@@ -147,10 +148,10 @@ export interface TaskRequestBody {
      *
      *  🔴 **类型 = core 的 `SkillSpec` 本体,不是它的手抄子集**([ref]):这里曾写死
      *  `{ name; description; content }` —— core 闭集六位里的三位,而 `manifest` / `files` / `baseDir`
-     *  三位在运行期一直是**收的**(受理门 `validateUserSkills` 不判未知键,`buildRunSkills` 原样透传到
+     *  三位在运行期一直是**收的**(当年的受理门不判未知键 —— 7.148.0 起顶层也是闭合键表,`buildRunSkills` 原样透传到
      *  `TaskSpec.skills`)。一份会漂的手抄 = 声明面比真受理面**窄**,SDK 消费方按声明写代码就以为发不了,
      *  而 core 加键(7.20.0 [ref] 的 `baseDir`)时这里连红都不会红。改成 core 本体后,闭集由 tsc 看守。
-     *  ⚠️ 受理**判据**(形/尺寸)仍在 `validateUserSkills` + `spec-fields.ts` 的 `SKILL_FIELD_SHAPES`——
+     *  ⚠️ 受理**判据**(键集 / 形 / 尺寸)在 `spec-fields.ts` 的 `skillItemIssue`(两道技能门同一只,读 `SKILL_FIELD_SHAPES`)——
      *  类型说「哪些键存在」,门说「值合不合法」,两者不是一件事。
      *  (旧注里的「Caps: ≤10 skills, content ≤32KB each」两条帽早已随 [ref] / core 1.293 退役,一并纠正:
      *   今天只剩 `content ≤ 1 MiB` 这一条 core 加载门孪生。) */

package/dist/identity-source.d.ts

@@ -1,12 +1,12 @@
 /**
  * **身份来源闭集 + run 行身份元组** —— 叶子模块(零依赖):凭据门(`http/principal-gate.ts`)、run 店契约(`plugins/store-contracts.ts`)、
- * 三只 run 店、中央建表语句(`plugins/tidb-pool.ts` / `plugins/pg-pool.ts`)与 `/health` 自报位读同一份。
+ * 三只 run 店与 leader run 店(`plugins/leader-run-store-sql.ts`)、中央建表语句(`plugins/tidb-pool.ts` / `plugins/pg-pool.ts`)与 `/health` 自报位读同一份。
  *
  * ## 律(三句;全仓只在这里写一次)
  * 1. **一张表、一个次序**:{@link IDENTITY_SOURCES} 的序 = 凭据门的判定次序(`verifiedIdentitySource` 答表里第一个验得过的词)= `/health.auth.kinds` 的出现序。
  *    出示了部署的 service 凭据就是 `service_token` —— 哪怕同一枚 Bearer 也被鉴权桥验成登录令牌、哪怕运维给这枚凭据起的系统名叫 `sso`;
  *    验不过 service 凭据而鉴权桥挂了身份 ⇒ `sso`;都没有而直连门 principal 令牌验过 ⇒ `direct_door_jwt`。
- * 2. **一只元组、受理时铸一次**:run 行的身份元组 {@link RunIdentity}(三列 `identity_source` / `identity_scope` / `identity_principal_inc`)在凭据门上随来源
+ * 2. **一只元组、受理时铸一次**:run 行(`task_run` 与 `leader_run`)的身份元组 {@link RunIdentity}(三列 `identity_source` / `identity_scope` / `identity_principal_inc`)在凭据门上随来源
  *    一起定下(`principal-gate.ts` 的 `admitRunIdentity`,唯一调用点是凭据门),建行处原样写入,之后只读 —— 续跑认领、挂起、终局、重启都不改它,
  *    没有任何读者按当前状态重推它。`RunRecord.source`(系统名 / `"sso"` / null)只作归因,不是认证来源。
  * 3. **缺席一种读法**:`null` = 这一行**没有「属主在受理时验过的凭据」的记录** —— 三列存在之前写下的行、没有任何验过凭据的受理(无鉴权写面
@@ -23,6 +23,37 @@
 /** 验过的身份来源的**闭集**(序 = 判定次序 = `/health.auth.kinds` 的出现序;加一个来源 = 加一个词,读它的各只穷举 `switch` 不接就编译红)。 */
 export declare const IDENTITY_SOURCES: readonly ["service_token", "sso", "direct_door_jwt"];
 export type IdentitySource = (typeof IDENTITY_SOURCES)[number];
+/**
+ * 身份来源在**配置**上接没接线的读入形(`ServiceConfig` 结构上满足)。「这台部署能回哪几个身份来源」只读配置、不读装配:鉴权桥的验签器由
+ * `boot/stage-09-leader.ts` 按 {@link authBridgeIssuerOf} 的同一个读数建(读得出 issuer ⇔ 建)⇒「验签器在场」≡「配置里有桥」,
+ * 起服任一阶段(含先于验签器的一次性迁移段)读到的是同一个答案;验签器与配置里的桥两者不一致的装配(任一方向)在 `createHttpServer` 拒(`http/server.ts`)。
+ */
+export interface IdentitySourceConfig {
+    readonly authToken?: string | undefined;
+    readonly authTokens?: Readonly<Record<string, string>> | undefined;
+    readonly authBridgeIssuer?: string | undefined;
+    readonly webAdmin?: {
+        readonly baseUrl: string;
+    } | undefined;
+    readonly directDoorActive: boolean;
+}
+/**
+ * 鉴权桥 issuer 的**唯一**取值(装配 `boot/stage-09-leader.ts`、caps `centerWiring.issuer`、`/health.center.issuer` 与 {@link configuredIdentitySources} 同读,不各写一份回退):
+ * 显式 `AUTH_BRIDGE_ISSUER`(`config.authBridgeIssuer`)恒赢 ⇒ `source:"explicit"`;缺席则回退中心基址 `webAdmin.baseUrl`
+ * (配了中心即默认开桥)⇒ `source:"fallback"`;两者都没有 ⇒ `undefined`(桥不装)。
+ */
+export declare function authBridgeIssuerOf(config: Pick<IdentitySourceConfig, "authBridgeIssuer" | "webAdmin">): {
+    readonly issuer: string;
+    readonly source: "explicit" | "fallback";
+} | undefined;
+/** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源,也是身份来源 `service_token` 接没接线的那一句。**单一属主**:全局凭据门(`http/dispatch.ts`)、
+ *  停驻行的赎回席(`http/approval-sweeps.ts`)、记忆整理阀门的启动期告警(`boot/stage-06-runners.ts`)、以及 {@link configuredIdentitySources} 读同一句(手抄迟早只改一处,而这条判据决定的是「无凭证部署上写口开不开」)。 */
+export declare function hasServiceAuth(config: Pick<IdentitySourceConfig, "authToken" | "authTokens">): boolean;
+/**
+ * 🔴 **「这台部署能回哪几个身份来源」的唯一读法**({@link IDENTITY_SOURCES} 里配置接了线的那几个词,序同表)。读者:部署形表的 `identity` 轴
+ * (`deployment-shape.ts`,「有没有身份边界」那一行由它答)、`/health.auth`(自报位,`http/health-self-report.ts`)、server-as-peer 受众门(`http/server.ts`)。
+ */
+export declare function configuredIdentitySources(config: IdentitySourceConfig): readonly IdentitySource[];
 /**
  * run 行身份元组(受理时铸、持久、之后只读;律见文件头)。三键恒在、与三列一一对应:`scope` / `principalInc` 只随 `sso` 有值 ——
  * service 凭据与直连门令牌不带登录令牌的 scope / 化身号,判别联合让「`service_token` 带 scope」这种形写不出来。
@@ -56,8 +87,8 @@ export declare function runIdentityClaimOverflow(claim: RunIdentityClaim, value:
     readonly max: number;
 } | undefined;
 /**
- * `task_run` 三列的列定义 —— 两方言各一段,**唯一属主**:中央建表语句(`tidb-pool.ts` / `pg-pool.ts` 的 `CREATE TABLE task_run`)内插这同一段;
- * 存量库缺列时起服列册对账(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE task_run ADD COLUMN …` 由同一份建表语句解析生成 ⇒
+ * 身份元组三列的列定义 —— 两方言各一段,**唯一属主**:`task_run`(中央建表语句 `tidb-pool.ts` / `pg-pool.ts`)与 `leader_run`(`leader-run-store-sql.ts`)的
+ * `CREATE TABLE` 内插这同一段;存量库缺列时起服列册对账(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE <表> ADD COLUMN …` 由同一份建表语句解析生成 ⇒
  * 「新库建出来的列」与「运维按拒句 / MIGRATION 补上的列」逐字同形。三列都可空(存量行与律 3 的三种成因都是 NULL);PG 钉 `COLLATE "C"`
  * (身份键按字节判等,与 MySQL 协议表级 `utf8mb4_bin` 同形)。
  */
@@ -71,7 +102,7 @@ export interface RunIdentityCells {
     readonly identityScope: string | null;
     readonly identityPrincipalInc: string | null;
 }
-/** 元组 → 三格(写口;三只 run 店同一只)。 */
+/** 元组 → 三格(写口;三只 run 店与 leader run 店同一只)。 */
 export declare function runIdentityCells(identity: RunIdentity | null): RunIdentityCells;
 /**
  * 三格 → 元组(读口;SQL 两方言的行映射与 File 车道的 run.json 读回同一只)。读不出一只**合形**元组的三格一律读成 `null`(律 3:不合格,fail-closed),

package/dist/identity-source.js

@@ -1,4 +1,31 @@
 export const IDENTITY_SOURCES = ["service_token", "sso", "direct_door_jwt"];
+export function authBridgeIssuerOf(config) {
+    if (config.authBridgeIssuer !== undefined)
+        return { issuer: config.authBridgeIssuer, source: "explicit" };
+    if (config.webAdmin !== undefined)
+        return { issuer: config.webAdmin.baseUrl, source: "fallback" };
+    return undefined;
+}
+export function hasServiceAuth(config) {
+    return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
+}
+function identitySourceConfigured(kind, config) {
+    switch (kind) {
+        case "service_token":
+            return hasServiceAuth(config);
+        case "sso":
+            return Boolean(authBridgeIssuerOf(config)?.issuer);
+        case "direct_door_jwt":
+            return config.directDoorActive;
+        default: {
+            const unknownKind = kind;
+            throw new Error(`identity sources: unknown identity source ${String(unknownKind)}`);
+        }
+    }
+}
+export function configuredIdentitySources(config) {
+    return IDENTITY_SOURCES.filter((k) => identitySourceConfigured(k, config));
+}
 export const RUN_IDENTITY_SCOPE_MAX_CHARS = 190;
 export const RUN_IDENTITY_PRINCIPAL_INC_MAX_CHARS = 64;
 export const RUN_IDENTITY_CLAIM_COLUMNS = { scope: RUN_IDENTITY_SCOPE_MAX_CHARS, principalInc: RUN_IDENTITY_PRINCIPAL_INC_MAX_CHARS };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { loadConfig, type ServiceConfig } from "./config.js";
+export { declareServerWithheldEnv } from "./server-secret-env.js";
 export { composeExecutionLane, assertExecutionLaneInvariants, HTTP_SERVICE_LANE_ENTRY, type ExecutionLaneComposeCtx, type ExecutionLaneEntry } from "./boot/execution-lane.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { loadConfig } from "./config.js";
+export { declareServerWithheldEnv } from "./server-secret-env.js";
 export { composeExecutionLane, assertExecutionLaneInvariants, HTTP_SERVICE_LANE_ENTRY } from "./boot/execution-lane.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";

package/dist/key-resolver.d.ts

@@ -84,6 +84,38 @@ export type ModelKeyRef = Pick<Model, "name">;
 export declare function createKeyResolver(modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedCustodyPoison>): ((model: ModelKeyRef) => Promise<{
     apiKey: string;
 } | undefined>) | undefined;
+/** 两张 per-model 钥匙表(`config.modelApiKeyEnv` / `config.modelApiKeys` 的形;缺席读作空表)。 */
+export interface ModelKeyTables {
+    readonly modelApiKeyEnv?: Readonly<Record<string, string>>;
+    readonly modelApiKeys?: Readonly<Record<string, string | SealedCustodyPoison>>;
+}
+/**
+ * 一只模型的**凭据身份**(不是值):它声明的钥匙来源是谁。
+ *  · `sealed` —— 托管密钥的解封产物(明文,或解不开时的毒丸;与 `config.modelApiKeys` 的值同型)。本进程的托管店 boot 只读一次,同一密文恒解出同一产物 ⇒
+ *    持有产物就是持有那一代的身份;重贴 = 新身份。
+ *  · `apiKeyEnv` —— 目录给它配的 env 变量**名**;值在取值那一刻按名读(同名轮换是同一身份)。
+ * 没有自有凭据 ⇒ `{}`。两张表至多一个条目有效(托管压过 env 引用,registry-core 互斥)。
+ */
+export interface CredentialIdentity {
+    readonly apiKeyEnv?: string;
+    readonly sealed?: string | SealedCustodyPoison;
+}
+/**
+ * 凭据身份的**唯一读法** —— key 链({@link resolveModelApiKey} / {@link modelKeyPoisonOf} / {@link createKeyResolver})取值前先问它,
+ * boot 焊死模型的两只座(降级壳焊住的目标、记忆整理席解到的条目)冻结的也是它的读数:**焊死的 Model 与它的凭据身份同一代**,
+ * 目录把两者一起换掉之后、重启之前,座仍打焊死的端点、带焊死那一代的身份(值按身份现取:env 引用同名轮换仍热)。身份变了 ⇒ 那只座的重启片签
+ * (指纹读 {@link credentialIdentityFingerprint})。
+ */
+export declare function credentialIdentityOf(tables: ModelKeyTables, modelName: string): CredentialIdentity;
+/**
+ * 凭据身份的**非明文**读数 —— 重启片两侧读数里凭据那一位的唯一铸法(明文是活秘密:只取摘要,绝不进日志 / 序列化面)。
+ * `apiKeyEnv` = 变量名(值热、同名轮换不签);`sealedKey`:缺席 ⇒ `null`;毒丸 ⇒ `{ poisoned, reason }`(不含检测时刻 —— 每次 apply 都会重铸);
+ * 明文 ⇒ `{ digest }`(sha256 前 16 位十六进制;同一明文重封一次 = 同一把 key ⇒ 不签)。
+ */
+export declare function credentialIdentityFingerprint(identity: CredentialIdentity): {
+    readonly apiKeyEnv: string | null;
+    readonly sealedKey: unknown;
+};
 /** 「这只模型声明的钥匙来源今天拿不到」⇒ 那一只毒丸;拿得到 / 没声明 ⇒ `undefined`。能力面的配对标注据它答 `"unknown"`(判别,不是 catch)。 */
 export declare function modelKeyPoisonOf(modelName: string, modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedCustodyPoison>): ModelKeyPoison | undefined;
 /**

package/dist/key-resolver.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 export function modelKeyPoison(p) {
     const at = new Date().toISOString();
     if (p.source === "sealed")
@@ -50,16 +51,29 @@ export function createKeyResolver(modelApiKeyEnv, env = process.env, modelApiKey
     };
 }
 function chainLookup(modelName, modelApiKeyEnv, env, modelApiKeys) {
-    const sealed = modelApiKeys[modelName];
-    if (isModelKeyPoison(sealed))
-        return { kind: "poison", poison: sealed };
-    if (sealed)
-        return { kind: "key", key: sealed };
-    const envName = modelApiKeyEnv[modelName];
-    if (!envName)
+    const identity = credentialIdentityOf({ modelApiKeyEnv, modelApiKeys }, modelName);
+    if (identity.sealed !== undefined)
+        return isModelKeyPoison(identity.sealed) ? { kind: "poison", poison: identity.sealed } : { kind: "key", key: identity.sealed };
+    if (identity.apiKeyEnv === undefined)
         return { kind: "undeclared" };
-    const value = env[envName];
-    return value ? { kind: "key", key: value } : { kind: "poison", poison: modelKeyPoison({ source: "env", reason: "env_missing", apiKeyEnv: envName }) };
+    const value = env[identity.apiKeyEnv];
+    return value ? { kind: "key", key: value } : { kind: "poison", poison: modelKeyPoison({ source: "env", reason: "env_missing", apiKeyEnv: identity.apiKeyEnv }) };
+}
+export function credentialIdentityOf(tables, modelName) {
+    const sealed = tables.modelApiKeys !== undefined && Object.hasOwn(tables.modelApiKeys, modelName) ? tables.modelApiKeys[modelName] : undefined;
+    if (isModelKeyPoison(sealed) || typeof sealed === "string" && sealed !== "")
+        return { sealed };
+    const apiKeyEnv = tables.modelApiKeyEnv !== undefined && Object.hasOwn(tables.modelApiKeyEnv, modelName) ? tables.modelApiKeyEnv[modelName] : undefined;
+    return typeof apiKeyEnv === "string" && apiKeyEnv !== "" ? { apiKeyEnv } : {};
+}
+export function credentialIdentityFingerprint(identity) {
+    const sealed = identity.sealed;
+    const sealedKey = sealed === undefined
+        ? null
+        : isModelKeyPoison(sealed)
+            ? { poisoned: modelKeyPoisonIdentity(sealed), reason: sealed.reason }
+            : { digest: createHash("sha256").update(sealed, "utf8").digest("hex").slice(0, 16) };
+    return { apiKeyEnv: identity.apiKeyEnv ?? null, sealedKey };
 }
 export function modelKeyPoisonOf(modelName, modelApiKeyEnv, env = process.env, modelApiKeys = {}) {
     const r = chainLookup(modelName, modelApiKeyEnv, env, modelApiKeys);

package/dist/leader/diffup.js

@@ -1,5 +1,6 @@
 import { safeRev, DEFAULT_MAX_DIFF_BYTES } from "./diffout.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "../plugins/blob-backend.js";
+import { createEgressFetch } from "../egress-redirect.js";
 export function buildUploadScript(p) {
     if (!safeRev(p.baseSha))
         throw new Error(`buildUploadScript: unsafe baseSha ${JSON.stringify(p.baseSha)}`);
@@ -114,7 +115,7 @@ export function buildUploadLoopScript(p) {
 }
 export async function fetchUploadedDiff(getUrl, opts = {}) {
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_DIFF_BYTES;
-    const f = opts.fetchImpl ?? fetch;
+    const f = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", opts.fetchImpl);
     let res;
     try {
         res = await f(getUrl, { signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });

package/dist/leader/endpoint.d.ts

@@ -1,6 +1,9 @@
 import type { LeaderResult } from "./leader.js";
 import { type LeaderRunRecord, type LeaderRunStatus, type NewLeaderRun, type LeaderRunTerminal } from "../plugins/leader-run-store-sql.js";
 import { type IdemCaller } from "../http/idempotency.js";
+import type { Subject } from "../owner-brands.js";
+import type { RunIdentity } from "../identity-source.js";
+import type { LeaderParkExpiry } from "./wire.js";
 /**
  * endpoint 消费的 store 面(结构型,不是 nominal union):真实现是 `SqlLeaderRunStore` 的两个方言孪生,
  * 测试用进程内假件。窄到只有 endpoint 真调的三个方法 —— 端点不该看见店的其余口。
@@ -14,6 +17,8 @@ export interface LeaderRunStore {
     /** 按提交幂等键(已 scope 的定宽 hash)读行 —— `GET /v1/leader?idempotencyKey=` 的读口。 */
     getByIdem(idemKey: string): Promise<LeaderRunRecord | undefined>;
     finishRun(id: string, patch: LeaderRunTerminal): Promise<boolean>;
+    /** 翻耐久取消旗(只翻 `running` 行;回执 = 翻没翻)。驱动副本经 `getRun` 读它(一次读拿到状态 + 旗)。 */
+    requestCancel(id: string): Promise<boolean>;
 }
 export interface LeaderRequestBody {
     /** The task to decompose + execute (the Planner turns it into N disjoint sub-tasks). */
@@ -36,6 +41,10 @@ export interface LeaderRun {
     /** BL-4: the principal that submitted this run (null = anonymous/single-tenant). The GET is owner-checked so
      *  an owned run is visible ONLY to its owner (404 to others — no existence oracle), like GET /v1/runs/:id. */
     owner?: string | null;
+    /** 降级臂的取消旗(店在场时以库上的旗为准,本地这一格只服务降级臂的读面)。 */
+    cancelRequested: boolean;
+    /** 取消口停下的终局带 `cancelled`。 */
+    errorCode?: LeaderRunTerminal["errorCode"];
 }
 export interface LeaderEndpoint {
     /** Returns a {status,body} to send, or null if the (method,url) is not a leader route. Kicks the background
@@ -45,7 +54,9 @@ export interface LeaderEndpoint {
      *  header; `GET /v1/leader`: the `idempotencyKey` query — the read port "which leader run did this key create"; scoped by the
      *  caller's identity bit `principal ?? source` before it reaches the store — the one key minter `idemKeyOf(raw, caller, "leader")`).
      *  ASYNC because the durable arm reads/writes SQL. */
-    handle(method: string, url: string, body: unknown, caller?: IdemCaller, idempotencyKey?: string | null): Promise<{
+    handle(method: string, url: string, body: unknown, caller?: IdemCaller, idempotencyKey?: string | null, 
+    /** POST 受理时的身份元组(路由经 `runIdentityOf` 铸;缺席 = `null` = 不合格)。只写进行,不上 wire。 */
+    identity?: RunIdentity | null): Promise<{
         status: number;
         body: object;
     } | null>;
@@ -59,7 +70,9 @@ export interface LeaderEndpoint {
      *  With a store in place this Map holds only the runs THIS replica is driving. Exposed for tests. */
     runs: Map<string, LeaderRun>;
 }
-export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody) => Promise<LeaderResult>, opts: {
+/** 取消终局的 `error` 句(机读位是 `errorCode: "cancelled"`)。 */
+export declare const LEADER_RUN_CANCELLED_ERROR = "leader run cancelled (POST /v1/leader/:id/cancel): it stopped at an abort checkpoint before any push";
+export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody, signal: AbortSignal) => Promise<LeaderResult>, opts: {
     logger?: {
         info?: (m: string, x?: Record<string, unknown>) => void;
         error?: (m: string, x?: Record<string, unknown>) => void;
@@ -73,8 +86,16 @@ export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody
     requiredFields?: readonly string[];
     /** [ref] 车4 件1:durable 登记表。缺席 ⇒ 显式的单副本内存降级臂(见文件头注)。 */
     store?: LeaderRunStore;
-    /** [ref] RH-3:「这个调用方读得到这一行 leader run 吗」—— 属主存取器的判官形(`http/owner-access.ts` 的 `createLeaderRunVisibility`,boot 装一次)。
-     *  必填:本模块不自判属主(修前手抄 `owner == null || owner === requester`,缺 [ref] C8 窄互认臂而注称 mirrors runOwnerOk),读面与幂等重放同读它。 */
-    ownerVisible: (principal: string | null | undefined, owner: string | null | undefined) => boolean;
+    /** [ref] RH-3:「这个调用方读得到这一行 leader run 吗」—— 属主存取器的判官形(`http/owner-access.ts` 的 `seesRunAs("run.leader")`,boot 装一次)。
+     *  必填:本模块不自判属主(修前手抄 `owner == null || owner === requester`,缺 [ref] C8 窄互认臂而注称 mirrors admitRunRow),读面与幂等重放同读它。 */
+    ownerVisible: (subject: Subject | null | undefined, owner: string | null | undefined) => boolean;
+    /** 过期一组 worker 会话的待决停驻(`wire.ts` 的 `createLeaderParkExpirer`,boot 在有 checkpoint 店时递)。缺席 = 本部署没有 checkpoint 店 ⇒
+     *  worker 由构造即不可能停驻(durable spec 要那只店),没有可过期的东西。 */
+    expireWorkerParks?: (workers: ReadonlyArray<{
+        readonly workerId: string;
+        readonly sessionId: string;
+    }>) => Promise<LeaderParkExpiry>;
+    /** 旗读拍距(ms)。缺席 = `LIVENESS_HEARTBEAT_MS`(与 run 心跳同一个数);测试注入短拍。 */
+    cancelPollMs?: number;
 }): LeaderEndpoint;
 //# sourceMappingURL=endpoint.d.ts.map