@sema-agent/server 7.148.0 → 7.150.0

package/dist/http/durable-run-leg.js

@@ -5,24 +5,38 @@ import { recheckClaimBeforeLaunch, refusalAfterLostClaim, startClaimHeartbeat }
 import { heldFor } from "../peer-seat.js";
 import { fleetRunPublisher, fleetRunLabels, nameFleetRowOnDelivery } from "../fleet/fleet-bus.js";
 import { cascadeConfig, fillRunPreviewOnDelivery, runMeta } from "./run-meta.js";
+import { approvalLegOriginOf } from "../approval-leg-origin.js";
 import { declaredApprovalFrameFamilies, resolveStreamApprovalGate } from "../tool-approval.js";
 import { buildActiveRunConflict } from "./active-run-conflict.js";
-import { commitExecutionContext } from "./execution-context.js";
+import { commitExecutionContext, faultedAnswerOf } from "./execution-context.js";
 import { rootSessionAbsentAnswer } from "./execution-context.js";
 import { timeClaim } from "./claim-latency.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { clearTurnActivity, readTurnActivityMs } from "../turn-activity.js";
 import { recordResourceWindow } from "../resource-window.js";
 import { persistSubmissionCtx, SUBMIT_CTX_CLAIM_LOST } from "./submit-ctx.js";
-import { releaseClaimedRun } from "./claimed-run.js";
-import { headReadOf } from "../session-incarnation.js";
+import { withdrawClaimedRun } from "./claimed-run.js";
+import { sessionFactsReadOf } from "./owner-access.js";
 import { createSessionWorkspaceRecorder, sessionWorkspaceStoreOf } from "../session-workspace.js";
 export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const { deps } = ctx;
-    const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
     const sessionId = args.prepared.spec.sessionId;
     const taskId = args.clientTaskId ?? uuidv7();
     const trustedInternals = await heldWorkflowParkDecisions(deps, sessionId, args.workflowDecision?.carried);
+    let legId;
+    try {
+        const claimed = await claimAndCommit(ctx, runStore, args, sessionId, taskId);
+        if (!("holdingLeg" in claimed))
+            return claimed;
+        legId = claimed.holdingLeg;
+    }
+    catch (e) {
+        return faultedAnswerOf(e, args.face.faulted);
+    }
+    return launchDurableRun(ctx, runStore, args, sessionId, taskId, trustedInternals, legId);
+}
+async function claimAndCommit(ctx, runStore, args, sessionId, taskId) {
+    const { deps } = ctx;
     const created = await timeClaim(deps.metrics, "run_claim", runStore.createRun(taskId, sessionId, args.prepared.auth?.subject ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), identity: args.identity, idem: args.idem ?? null }));
     if (created.ok)
         clearTurnActivity(taskId);
@@ -40,11 +54,11 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const owner = args.prepared.auth?.subject ?? null;
     const stopPreLaunchHeartbeat = startClaimHeartbeat(runStore, taskId, owner, deps.metrics);
     try {
-        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore, taskId }, args.prepared.execution);
+        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore, taskId, legId: created.legId }, args.prepared.execution);
         if (placementReject)
-            return placementReject;
+            return args.face.refused(placementReject);
         if (deps.checkpointStore) {
-            const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, { runStore, taskId }, args.prepared);
+            const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, { runStore, taskId, legId: created.legId }, args.prepared);
             if (ctxRefusal === SUBMIT_CTX_CLAIM_LOST)
                 return await refusalAfterLostClaim(deps, runStore, sessionId, taskId);
             if (ctxRefusal)
@@ -55,13 +69,13 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
                 await args.workflowDecision.commitBeforeLaunch(taskId);
             }
             catch (err) {
-                await releaseClaimedRun(runStore, taskId, `the workflow decision this run delivers could not be recorded: ${err instanceof Error ? err.message : String(err)}`, (releaseErr, step) => {
+                await withdrawClaimedRun(runStore, taskId, created.legId, (releaseErr, step) => {
                     deps.logger?.warn?.("workflow_decision_run_release_failed", { taskId, sessionId, step, err: releaseErr instanceof Error ? releaseErr.message : String(releaseErr) });
                 });
                 throw err;
             }
         }
-        const lostClaim = await recheckClaimBeforeLaunch(deps, runStore, sessionId, taskId);
+        const lostClaim = await recheckClaimBeforeLaunch(deps, runStore, sessionId, taskId, created.legId);
         if (lostClaim !== undefined)
             return lostClaim;
     }
@@ -69,11 +83,16 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
         stopPreLaunchHeartbeat();
     }
     commitSessionInheritEnv(deps, args.prepared.spec.sessionId, args.prepared.body);
+    return { holdingLeg: created.legId };
+}
+function launchDurableRun(ctx, runStore, args, sessionId, taskId, trustedInternals, legId) {
+    const { deps } = ctx;
+    const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
     const anchorOwner = args.prepared.auth?.subject ?? null;
-    const headOf = headReadOf(deps.sessionStorage);
-    const captureTurnAnchor = deps.resumeAnchorStore && headOf
+    const sessionFactsOf = sessionFactsReadOf(deps.sessionStorage);
+    const captureTurnAnchor = deps.resumeAnchorStore && sessionFactsOf
         ? async (eventId) => {
-            const leaf = (await headOf(sessionId))?.leafId;
+            const leaf = (await sessionFactsOf(sessionId))?.leafId;
             if (leaf)
                 await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner);
         }
@@ -89,7 +108,7 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
         ...fleetRunLabels(args.prepared.acceptance.objectiveAtSubmit),
     });
     nameFleetRowOnDelivery(args.prepared.acceptance, fleetPub);
-    void heldFor(args.prepared.peerLease, () => runInBackground(args.prepared.runner, args.prepared.spec, runStore, taskId, deps.metrics, args.prepared.auth?.subject, args.prepared.verify, args.prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, args.prepared.spec.limits?.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, args.elicitOwner, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests, deps.toolApproval
+    void heldFor(args.prepared.peerLease, () => runInBackground(args.prepared.runner, args.prepared.spec, runStore, taskId, { legId, runStaleSec: deps.config.runStaleSec }, deps.metrics, args.prepared.auth?.subject, args.prepared.verify, args.prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, args.prepared.spec.limits?.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, args.elicitOwner, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests, deps.toolApproval
         ? {
             coordinator: deps.toolApproval,
             streamApprovalOn: resolveStreamApprovalGate({
@@ -101,9 +120,9 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
             windowMs: deps.config.streamApproval?.windowMs,
             windowMarginMs: deps.config.streamAskWindowMarginMs,
             declaredFamilies: declaredApprovalFrameFamilies(args.prepared.body.settings),
-            executionLane: args.prepared.execution.lane,
+            origin: approvalLegOriginOf(args.prepared.execution),
         }
-        : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance, createSessionWorkspaceRecorder(sessionWorkspaceStoreOf(deps.sessionStorage), args.prepared.legFacts?.sessionWitness), args.prepared.legFacts?.skills));
+        : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance, createSessionWorkspaceRecorder(sessionWorkspaceStoreOf(deps.sessionStorage), args.prepared.legFacts?.sessionWitness), args.prepared.legFacts?.skills, args.prepared.legFacts?.registeredCwd));
     args.runSlot?.release();
     args.prepared.seat.markRecord();
     return { status: 202, body: { taskId, sessionId, status: "running", ...(args.prepared.warnings !== undefined ? { warnings: args.prepared.warnings } : {}) } };

package/dist/http/execution-context.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage } from "node:http";
 import type { SessionHead, TaskSpec } from "@sema-agent/core";
+import { HttpError } from "../security.js";
 import { type DeviceOwner, type DeviceStore } from "../device-store.js";
 import { type DeviceEnrollment, type DeviceRejection } from "../device-enrollment.js";
 import type { ServiceConfig } from "../config.js";
@@ -123,19 +124,30 @@ export type RootedTaskSpec = TaskSpec & {
  * 走到这里只能是擦型或 JS 形;拒在建任何行之前)。续跑家族照它自己的折叠律把这只拒答成 409 `resume_blocked_by_policy`(`blockedBy` = 这只码,
  * `http/resume-legs.ts` 的 `resolveResumeSpecOrBlocked`:装配期的每一只 `HttpError` 在续跑腿上都这么折),同样什么都没续。
  *
- * **根「必须已在」的唯一写者也是这里**(`requireExistingSession`;装配器不写它):根是宿主的 ⇒ 引擎取会话时不许「缺行即建」——
- * 解析器步 ① 读到过这一行(`occupant` 在场),或调用方自己要求了它(`requireExistingSession: true`;店不带执行席时这是唯一的来源)⇒ 盖 `true`:
- * 门与引擎取会话之间这一行被删(属主删除 / 受理前拒的撤回),引擎答 `resume.session_not_found`,不在原 id 上重建一只无主的空根。
- * **例外只有一条,来自引擎的派生形**:`cascade: true` 的提交不盖 —— 引擎派生每一级时只删 `sessionId`、其余字段照展开,带着这一位的级就成了
- * 「没有会话 id 却要求会话已在」,被引擎拒掉(每一级都跑不起来)。引擎把这一位随 `sessionId` 一并剥掉之后,cascade 也盖,这一条例外删去。
- * 没读到行、调用方也没要求 ⇒ 不盖(与引擎缺省同:没有宿主见过的根可护)。
+ * **根「必须已在」(`requireExistingSession`)的唯一写者也是这里**(装配器不写它),按调用方交来的 {@link RootUse} 穷举 —— 用法由**选引擎入口的那条腿**交
+ * (受理漏斗:与它交给提交腿的 `cascade` 同一个值;续跑重建:`session`;续跑的梯子臂:`ladder_host`),不从提交体再读一遍:
+ *  · `session` —— 它是引擎在根上取会话时的「只接、不建」:解析器步 ① 读到过这一行(`occupant` 在场),或调用方自己要求了它(`requireExistingSession: true`;
+ *    店不带执行席时这是唯一的来源)⇒ 盖 `true`:门与引擎取会话之间这一行被删(属主删除 / 受理前拒的撤回),引擎答 `resume.session_not_found`,不在原 id 上重建一只
+ *    无主的空根;没读到行、调用方也没要求 ⇒ 不盖(只加不减:装配器交来的那一位原样留着);
+ *  · `ladder_host` —— 引擎在梯子上不取根,没有可盖的取会话 ⇒ 盖出的 spec 上**没有**这一位(交来的 spec 带着也剥掉:续跑的梯子臂从重建的那一份再盖);
+ *    根在不在、门后被删由宿主判 —— 受理口的属主门(调用方要求了它而行不在 ⇒ 404)与执行起点的认领(带 run 店的部署:根行锁之后判在不在 / 放置提交判行在 ⇒ 404)。
  */
 export declare function stampSpecRoot(spec: ResolvedTaskSpec, ctx: ExecutionRoot, submission: SpecRootSubmission): RootedTaskSpec;
-/** {@link stampSpecRoot} 读的那两位提交事实(受理漏斗交这次的体;续跑家族交 checkpoint 上存的那一份体)。 */
-export interface SpecRootSubmission {
-    readonly cascade?: unknown;
+/**
+ * 引擎拿这次提交的根做什么(闭集;{@link stampSpecRoot} 按它穷举 —— 加一种用法 ⇒ 那只 `switch` 编译红):
+ *  · `session` —— 引擎在根上取会话跑(单腿;验证门的实现腿与修复腿;续跑家族 —— 续跑、wake、宿主会话上新铸的一跑);
+ *  · `ladder_host` —— 根是梯子的宿主(`cascade: true` 的组合入口):每一级在引擎为它现铸的会话里冷跑,引擎不取根;根只是这条梯子停驻卡的归属(组合腿的 `hostSessionId`)。
+ */
+export type RootUse = "session" | "ladder_host";
+/**
+ * {@link stampSpecRoot} 的第三参:选引擎入口的那条腿交来的用法;调用方「根必须已在」的要求只属于 `session` 用法(梯子上它由宿主的门与认领判,型上没有这一键)。
+ */
+export type SpecRootSubmission = {
+    readonly use: "session";
     readonly requireExistingSession?: unknown;
-}
+} | {
+    readonly use: "ladder_host";
+};
 /**
  * run 店建行时根会话行已经不在(`CreateRunOutcome.sessionAbsent`:受理之后、认领之前会话被删)的**唯一**答复 ——
  * 四个建行点(同步 / 流式 / durable / wake)、解析期的「行不在 / 住客换了」与提交期的 `gone` 同答 404 `resume.session_not_found`,什么都没建、什么都没跑。
@@ -150,19 +162,100 @@ export interface ExecutionRefusal {
     readonly body: RefusalBody;
 }
 /**
- * 本次认领 —— 提交拒时要释放的东西。`run` = 四个建行点与续跑家族认领的 run 行(释放 = 终结 + 放认领 + 放幂等键,唯一写法 `releaseClaimedRun`);
- * `parked` = 停驻赎回的认领(释放 = 回滚认领;「会话不在」答那条腿既有的 `decide.not_parked`,不是提交腿的 404)。
+ * 本次认领 —— 提交没放行时要撤回的东西。撤回只有一张表({@link withdrawClaim}),按认领种类把认领撤回到**它取来时的样子**:
+ *  · `run` = 本请求铸的行(四个建行点 / wake 的现建行 / workflow 决定在宿主会话上的新一跑;`legId` = 建行交回的持有腿):取来之前没有这一行 ⇒ 每一种收场都删掉它
+ *    (唯一写法 `withdrawClaimedRun`:只认本腿持有的那一行,行仍在跑才删,认领与幂等键随行去;已被收割 / 终局 ⇒ 零删)—— 同一个 `taskId` / 同一把幂等键的重发是一次新提交;
+ *  · `resumed` = 续跑家族 `markResuming` 认领的停驻行:取来之前它停在等一张待决的卡 ⇒ 放回停驻(`restore`:认领方的写法 = 停驻的唯一提交点 `park-row-commit.ts` 的 `commitParkRow`;
+ *    认领与幂等键留着,卡仍待决,同一个决定可以再发;认领窗里落下的取消由认领方按取消收场 —— 停驻态会让下一次认领重置取消旗)。
+ *    唯一的例外是 `gone`:店答出这条 run 的会话已经不在,它再也续不了 ⇒ 终结(同 `run` 那一只写法);
+ *  · `parked` = 停驻赎回的认领:每一种收场都回滚认领。
+ * 答复不在认领上:写口交回店的拒答,各面经自己的 {@link ClaimFace} 答它。
  */
 export type ExecutionClaim = {
     readonly kind: "run";
     readonly runStore: RunStore;
     readonly taskId: string;
+    readonly legId: string;
+} | {
+    readonly kind: "resumed";
+    readonly runStore: RunStore;
+    readonly taskId: string;
+    readonly restore: () => Promise<void>;
 } | {
     readonly kind: "parked";
     readonly taskId: string;
     readonly rollback: (why: string) => Promise<unknown>;
-    readonly goneAnswer: ExecutionRefusal;
 };
+/**
+ * 认领之后、交给引擎之前那一段没放行的收场 —— **唯一**的类别判定。规则一句:**店答出的拒是答案,店的故障不是**。判在 {@link commitExecutionContext} 的两只出口上
+ * (结构判:交回拒答 vs 抛,不读错误文案);续跑腿「提交放行之后、交给引擎之前」那一段的抛同属 `faulted`(`resume-legs.ts`,经同一张撤回表):
+ *  · `gone` —— 店答出这条会话已经不在(行没了 / 住客换了,{@link isRootSessionGoneRefusal}):确定的答案,这条会话上什么都再也续不了;
+ *  · `refused` —— 店答出这条会话此刻不能在本处执行(已放在别的车道、写者在别处、设备拒):确定的答案,但会话还在 —— 与认领之前解析器读出同一个事实是同一个命运;
+ *  · `faulted` —— 店没答出来(故障 / 超时 / 程序错):证不出这条会话不能执行,不当答案用。答复只看(这一面 × 店有没有答出来):各面的瞬时答复({@link faultedAnswerOf}),
+ *    本服务自己的程序错照旧响亮 500。
+ */
+export type CommitEnding = "gone" | "refused" | "faulted";
+/**
+ * 提交点的拒答是不是「会话不在」那一只({@link rootSessionAbsentAnswer};唯一读者 —— 撤回表据它分 `gone` / `refused`,续跑家族与停驻赎回的 {@link ClaimFace} 据它决定那一只拒怎么答)。
+ * 只认这一只答复的码(与 {@link isRootSessionGoneError} 同一个判据,一个读拒答、一个读解析器的抛)。
+ */
+export declare function isRootSessionGoneRefusal(refusal: ExecutionRefusal): boolean;
+/**
+ * `faulted` 那一形的答复 —— 认领这一段(认领那一笔、认领之后的提交、续跑腿交给引擎之前的店往返、新提交起跑之前的店写)的一抛**只在这里**分两种:
+ * 店没答出来(判官的 `corrupt` / `connection` / `deployment` / `unclassified`)⇒ 这一面的瞬时答复(`answer`:新提交 {@link runStoreUnavailableAnswer} · 续跑家族
+ * `resume-ctx-read.ts` 的 `resumeClaimFaultAnswer` · 停驻赎回 `decide.store_unreachable`;每一面与它认领那一笔撞店故障同答);本服务自己的程序错(`defect`)⇒ 原样上抛,响亮成 500。
+ * 两种都不改撤回:认领已按 `faulted` 撤回(调用方在调本函数之前撤,或写口在抛之前撤)。判官加词而这里不表态 = 编译错。
+ * 设备注册簿那一次往返(设备店 / 准入链)也只经这里读:店没答出来 ⇒ 设备闭集的 {@link registryUnavailable},认领之前的准入与认领之后的首绑 / 再断言同答。
+ */
+export declare function faultedAnswerOf<A>(e: unknown, answer: () => A): A;
+/**
+ * 新提交(`POST /v1/tasks` 两腿、`POST /v1/runs` 与 A2A)撞店故障的**唯一**答复({@link SUBMISSION_CLAIM_FACE} 的 `faulted`)—— 503 `state.run_store_unavailable`:
+ * 认领之前那一次执行席读、认领那一笔(`createRun`)、认领之后的执行放置、续跑输入的写或起跑之前的认领复核,有一次店往返没答出来;本请求铸的行已撤回(删掉,认领与幂等键随行去),
+ * 什么都没起跑。稍后原样再发(同一个自带 `taskId` 也行);一直如此 ⇒ 请运维查库。句子不带店层 detail。🔴 形是给冻结门看的:`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function runStoreUnavailableAnswer(): {
+    status: 503;
+    body: RefusalBody;
+};
+/**
+ * **一面的两只答法**(规则一句见文件头「一面一只答法」):这一面在认领之前那一读(解析器)、认领那一笔、认领之后每一笔、交给引擎之前的店往返上,
+ * 店答出的拒与店的故障各怎么答 —— 每一面只声明一次,各调用点只经它答,不各自选码:
+ *  · `refused` —— 写口交回的店的拒答(会话不在 / 本处此刻不能执行)在这一面的答复:与这一面认领之前解析器读出同一个事实同一只答;
+ *  · `faulted` —— 店没答出来在这一面的瞬时答复(经 {@link faultedAnswerOf} 读;本服务的程序错照旧上抛)。
+ * 三面:{@link SUBMISSION_CLAIM_FACE}(新提交)· {@link CONTINUATION_CLAIM_FACE}(续跑家族:决断 / `/resume` / `plan_review` / `/wake` / `/decide` 在宿主会话上起的新一跑)·
+ * 停驻赎回(`parked-decide.ts` 的 `parkedRedeemFace`,按子代句柄铸)。
+ */
+export interface ClaimFace {
+    readonly refused: (refusal: ExecutionRefusal) => ExecutionRefusal;
+    readonly faulted: () => ExecutionRefusal;
+}
+/** 新提交这一面:店答出的拒原样答(认领之前解析器那一只 typed 拒同码同体);店没答出来 ⇒ {@link runStoreUnavailableAnswer}。 */
+export declare const SUBMISSION_CLAIM_FACE: ClaimFace;
+/**
+ * 续跑家族这一面:会话不在({@link isRootSessionGoneRefusal})⇒ 原答 404 `resume.session_not_found`;其余店答出的拒 ⇒ {@link cardWaitingRefusalAnswer}(与认领之前同一只折法);
+ * 店没答出来 ⇒ `resume-ctx-read.ts` 的 `resumeClaimFaultAnswer`(503 `state.resume_context_unreadable`,卡仍待决)。
+ */
+export declare const CONTINUATION_CLAIM_FACE: ClaimFace;
+/**
+ * 一只拒在「有一张卡仍在等」的那几面上的答复(续跑家族与停驻赎回;认领之前的解析器拒与认领之后写口交回的拒同经这里)—— 认领之前那一只折法
+ * (`checkpoint-ctx.ts` 的 `resumeAssemblyRefusalAnswer`:409 `resume_blocked_by_policy`,`blockedBy` = 原码,原事实随体;自报瞬时的拒原码原状态)+ `retriable`(卡仍待决)。
+ */
+export declare function cardWaitingRefusalAnswer(refusal: ExecutionRefusal): ExecutionRefusal;
+/** 一只拒答 → typed 拒(`HttpError`;体经 `httpErrorRefusal` 读回同一份:码、句、机读事实)。解析器的拒与提交门认领之前的拒只认这一种载体。 */
+export declare function refusalHttpError(refusal: ExecutionRefusal): HttpError;
+/**
+ * **认领之前那一读**在一面上的唯一读法(提交门 / 续跑家族的重建 / 停驻赎回同调唯一的解析器 {@link resolveExecutionContext}):解析器的拒(typed `HttpError`)是答案,
+ * 原样上抛给这一面自己的折法;店没答出来 ⇒ 抛这一面的瞬时答复(`face.faulted`,载体 {@link refusalHttpError} 外套 {@link ClaimFaultAnswer} —— 与这一面认领那一笔撞店故障同答,
+ * 续跑家族的折叠口认它、不折);本服务的程序错原样上抛(响亮 500)。认领之前没有认领可撤,状态零改动。
+ */
+export declare function resolveBeforeClaim(deps: ExecutionContextDeps, entry: Extract<ExecutionEntry, {
+    readonly root: string;
+}>, face: ClaimFace): Promise<RootedExecutionContext>;
+/** {@link resolveBeforeClaim} 抛出的「店没答出来」答复(typed 拒;`answer` = 这一面的瞬时答复原体)。只有折叠口要认它(续跑家族不把它折成 409);提交门按 typed 拒原样答。 */
+export declare class ClaimFaultAnswer extends HttpError {
+    readonly answer: ExecutionRefusal;
+    constructor(answer: ExecutionRefusal);
+}
 /** {@link commitExecutionContext} 的依赖 —— 逐字取自 `ServiceDeps` 的同名键(同一只 deps 对象喂进来)。 */
 export interface ExecutionCommitDeps {
     readonly sessionStorage?: {
@@ -189,10 +282,18 @@ export declare function placementWriteDeadlineMs(runStaleSec: number | undefined
 export declare function devicePlacementErrorBody(rej: DeviceRejection): RefusalBody;
 /**
  * **认领之后的唯一写口**(四个 `createRun` 点、续跑家族 `markResuming` 之后、停驻赎回 `claimParkedAgent` 之后)。返回 `null` = 放行;
- * 否则本次认领已释放,调用方交回拒答。店故障 / 超时 ⇒ 释放后原样上抛(响亮,不当答案);设备意图那一支的注册簿故障答 {@link registryUnavailable}(设备闭集,同准入阶段)。
+ * 否则本次认领已按 {@link withdrawClaim} 撤回(店答出的拒 = `gone` / `refused`),调用方交回拒答。店故障 / 超时 ⇒ 认领按 `faulted` 撤回后原样上抛
+ * (响亮,不当答案:各调用方经 {@link faultedAnswerOf} 落自己这一面的瞬时码);设备意图那一支的注册簿往返(首绑 / 再断言)撞故障 ⇒ 交回设备闭集的 {@link registryUnavailable}
+ * (经 {@link faultedAnswerOf},与认领之前的准入同一只读法;程序错照旧上抛),执行席那一读撞故障与认领之前那一读同答(上抛)。
  *
  * 不变量(一句):**离开本函数的那一刻,这条会话(解析器那一位住客)的格就是这条执行的车道(device 车道:准入批准的那台设备);否则本次认领已释放、调用方拿到拒答。**
  * 它不说「此后不变」:认领持有期间根行住客与放置不被换绑 / 导入改动,那是各写者写事务内锁根行后读认领的保证(规则句),不在本函数重复判。
  */
 export declare function commitExecutionContext(deps: ExecutionCommitDeps, claim: ExecutionClaim, ctx: RootedExecutionContext): Promise<ExecutionRefusal | null>;
+/**
+ * **撤回本次认领的唯一一张表**(规则与各种类的落点见 {@link ExecutionClaim};类别见 {@link CommitEnding})。两个调用处:{@link commitExecutionContext} 的两只出口,
+ * 与续跑腿「提交放行之后、交给引擎之前」那一段的抛(`resume-legs.ts`,`faulted`)。`ending` 只在 `resumed` 上分叉(会话不在 ⇒ 终结;其余 ⇒ 放回停驻),另两种认领取来时就只有一个去处。
+ * 认领之后的其余几笔(续跑输入、决定落行、起跑之前的复核)撤本请求铸的行用 `run` 那一臂的同一只写法(`withdrawClaimedRun`)。
+ */
+export declare function withdrawClaim(deps: ExecutionCommitDeps, claim: ExecutionClaim, why: string, ending: CommitEnding): Promise<void>;
 //# sourceMappingURL=execution-context.d.ts.map

package/dist/http/execution-context.js

@@ -3,13 +3,16 @@ import { HttpError, createCodedHttpError, ssoVerifiedScope } from "../security.j
 import { gatedPerson } from "./principal-gate.js";
 import { DEVICE_ERROR_CODES, assertDeviceIdShape } from "../device-store.js";
 import { buildDeviceRejection } from "../device-enrollment.js";
-import { sameOccupant } from "../execution-placement.js";
+import { SessionForkInProgressError, sameOccupant } from "../execution-placement.js";
 import { deployedExecutionLanes } from "../execution-lane-caps.js";
 import { gateExecutionLane } from "../runtime-caps-resolver.js";
-import { releaseClaimedRun } from "./claimed-run.js";
+import { releaseClaimedRun, withdrawClaimedRun } from "./claimed-run.js";
 import { sessionIdRetiredFor } from "../deleted-session-ids.js";
 import { refusalBody } from "./refusal-body.js";
 import { timeClaim } from "./claim-latency.js";
+import { storeFaultClassOf } from "../plugins/store-fault.js";
+import { resumeClaimFaultAnswer } from "./resume-ctx-read.js";
+import { resumeAssemblyRefusalAnswer, resumeRefusalWithCard } from "./checkpoint-ctx.js";
 export async function resolveExecutionContext(deps, entry) {
     const lanes = deployedExecutionLanes(deps.config);
     switch (entry.kind) {
@@ -70,8 +73,7 @@ function laneOf(root, cell, lanes) {
     }
 }
 function sessionMirrorError(root) {
-    const answer = sessionMirrorAnswer(root);
-    return createCodedHttpError(answer.status, answer.body.errorCode, answer.body.error, { forkPath: forkPathOf(root) });
+    return refusalHttpError(sessionMirrorAnswer(root));
 }
 export function forkPathOf(root) {
     return `/v1/sessions/${encodeURIComponent(root)}/fork`;
@@ -87,8 +89,7 @@ function sessionMirrorAnswer(root) {
     };
 }
 function rootSessionGoneError() {
-    const absent = rootSessionAbsentAnswer();
-    return createCodedHttpError(absent.status, absent.body.errorCode, absent.body.error);
+    return refusalHttpError(rootSessionAbsentAnswer());
 }
 export function isRootSessionGoneError(err) {
     return err instanceof HttpError && err.code === rootSessionAbsentAnswer().body.errorCode;
@@ -142,8 +143,8 @@ async function admitDevicePlacement(deps, entry, lane, seat, reading) {
     try {
         admitted = await deps.deviceEnrollment.admitSession({ rootSessionId: entry.root, placement: reading, requester: owner, ...(requestedDeviceId === undefined ? {} : { requestedDeviceId }) });
     }
-    catch {
-        throw asHttpError(registryUnavailable());
+    catch (e) {
+        throw asHttpError(faultedAnswerOf(e, registryUnavailable));
     }
     if (admitted.ok)
         return { rootSessionId: entry.root, occupant: reading.occupant, owner, admittedDeviceId: admitted.value.deviceId, firstBind: false };
@@ -153,8 +154,8 @@ async function admitDevicePlacement(deps, entry, lane, seat, reading) {
     try {
         view = await deps.deviceStore.readDeviceForAdmission(requestedDeviceId, owner);
     }
-    catch {
-        throw asHttpError(registryUnavailable());
+    catch (e) {
+        throw asHttpError(faultedAnswerOf(e, registryUnavailable));
     }
     if (!view)
         throw asHttpError(buildDeviceRejection(DEVICE_ERROR_CODES.NOT_FOUND, "device not found"));
@@ -169,8 +170,20 @@ export function stampSpecRoot(spec, ctx, submission) {
     if (named !== undefined && named !== ctx.root) {
         throw createCodedHttpError(400, "request.precondition_unmet", "the deployment's spec resolver named a session other than the one this submission was authorized for — a submission's root session comes only from the authorizer, so resolveSpec must not set sessionId (read opts.execution.root instead)");
     }
-    const requireExisting = submission.cascade !== true && (ctx.occupant !== undefined || submission.requireExistingSession === true);
-    return requireExisting ? { ...spec, sessionId: ctx.root, requireExistingSession: true } : { ...spec, sessionId: ctx.root };
+    switch (submission.use) {
+        case "session": {
+            const mustExist = ctx.occupant !== undefined || submission.requireExistingSession === true;
+            return mustExist ? { ...spec, sessionId: ctx.root, requireExistingSession: true } : { ...spec, sessionId: ctx.root };
+        }
+        case "ladder_host": {
+            const { requireExistingSession: _noAcquireOnALadder, ...ladderSpec } = spec;
+            return { ...ladderSpec, sessionId: ctx.root };
+        }
+        default: {
+            const unhandled = submission;
+            throw new Error(`stampSpecRoot: unhandled root use ${JSON.stringify(unhandled)}`);
+        }
+    }
 }
 export function rootSessionAbsentAnswer() {
     return {
@@ -181,6 +194,62 @@ export function rootSessionAbsentAnswer() {
         }),
     };
 }
+export function isRootSessionGoneRefusal(refusal) {
+    return refusal.body.errorCode === rootSessionAbsentAnswer().body.errorCode;
+}
+export function faultedAnswerOf(e, answer) {
+    const fault = storeFaultClassOf(e);
+    switch (fault) {
+        case "corrupt":
+        case "connection":
+        case "deployment":
+        case "unclassified":
+            return answer();
+        case "defect":
+            throw e;
+        default: {
+            const unhandled = fault;
+            throw new Error(`faultedAnswerOf: the store-fault judge answered a class this reader does not place: ${String(unhandled)}`);
+        }
+    }
+}
+export function runStoreUnavailableAnswer() {
+    return {
+        status: 503,
+        body: refusalBody({ errorCode: "state.run_store_unavailable", message: "this task could not be recorded just now (the store did not answer), so nothing was started. Send it again later; if this keeps happening, ask whoever operates this deployment to check its database." }),
+    };
+}
+export const SUBMISSION_CLAIM_FACE = { refused: (refusal) => refusal, faulted: runStoreUnavailableAnswer };
+export const CONTINUATION_CLAIM_FACE = {
+    refused: (refusal) => (isRootSessionGoneRefusal(refusal) ? refusal : cardWaitingRefusalAnswer(refusal)),
+    faulted: resumeClaimFaultAnswer,
+};
+export function cardWaitingRefusalAnswer(refusal) {
+    const { error, errorCode, ...facts } = refusal.body;
+    return resumeRefusalWithCard(resumeAssemblyRefusalAnswer(refusal.status, { errorCode, message: error, facts }), true);
+}
+export function refusalHttpError(refusal) {
+    const { error, errorCode, ...facts } = refusal.body;
+    return createCodedHttpError(refusal.status, errorCode, error, Object.keys(facts).length > 0 ? facts : undefined);
+}
+export async function resolveBeforeClaim(deps, entry, face) {
+    try {
+        return await resolveExecutionContext(deps, entry);
+    }
+    catch (e) {
+        if (e instanceof HttpError)
+            throw e;
+        throw new ClaimFaultAnswer(faultedAnswerOf(e, face.faulted));
+    }
+}
+export class ClaimFaultAnswer extends HttpError {
+    answer;
+    constructor(answer) {
+        const { error, errorCode: code, ...facts } = answer.body;
+        super(answer.status, error, Object.keys(facts).length > 0 ? { code, extra: facts } : { code });
+        this.answer = answer;
+    }
+}
 export function placementWriteDeadlineMs(runStaleSec) {
     const stale = typeof runStaleSec === "number" && Number.isFinite(runStaleSec) && runStaleSec > 0 ? runStaleSec : RUN_STALE_SEC_DEFAULT;
     return Math.min(15_000, Math.max(1_000, Math.floor((stale * 1000) / 4)));
@@ -209,7 +278,7 @@ export async function commitExecutionContext(deps, claim, ctx) {
     return timeClaim(deps.metrics, "placement_commit", commitPlacement(deps, claim, ctx, seat, occupant));
 }
 async function commitPlacement(deps, claim, ctx, seat, occupant) {
-    const release = (why) => releaseClaim(deps, claim, why);
+    const release = (why, ending) => withdrawClaim(deps, claim, why, ending);
     const deadlineMs = placementWriteDeadlineMs(deps.config?.runStaleSec);
     const withDeadline = async (work) => {
         let timer;
@@ -227,56 +296,64 @@ async function commitPlacement(deps, claim, ctx, seat, occupant) {
                 clearTimeout(timer);
         }
     };
-    const goneAnswer = () => (claim.kind === "parked" ? claim.goneAnswer : rootSessionAbsentAnswer());
     let refusal;
     try {
         refusal =
             ctx.device !== undefined
-                ? await commitDevice(deps, seat, ctx.device, withDeadline, goneAnswer)
+                ? await commitDevice(deps, seat, ctx.device, withDeadline)
                 : ctx.placement === "absent"
-                    ? await commitPlace(seat, ctx, occupant, withDeadline, goneAnswer)
-                    : await reassertWriter(seat, ctx, occupant, withDeadline, goneAnswer);
+                    ? await commitPlace(seat, ctx, occupant, withDeadline)
+                    : await reassertWriter(seat, ctx, occupant, withDeadline);
     }
     catch (err) {
-        deps.logger?.warn("execution_placement_commit_failed", { root: ctx.root, lane: ctx.lane, placement: ctx.placement, deadlineMs, err: err instanceof Error ? err.message : String(err) });
-        await release(`execution placement could not be committed: ${err instanceof Error ? err.message : String(err)}`);
-        if (ctx.device !== undefined) {
-            refusal = deviceRefusal(registryUnavailable());
+        if (err instanceof SessionForkInProgressError) {
+            refusal = { status: 409, body: refusalBody({ errorCode: err.code, message: err.message }) };
             deps.metrics?.inc("execution_placement_rejects_total", { errorCode: refusal.body.errorCode });
+            await release(`execution placement rejected: [${refusal.body.errorCode}] ${refusal.body.error}`, "refused");
             return refusal;
         }
+        deps.logger?.warn("execution_placement_commit_failed", { root: ctx.root, lane: ctx.lane, placement: ctx.placement, deadlineMs, err: err instanceof Error ? err.message : String(err) });
+        await release(`execution placement could not be committed: ${err instanceof Error ? err.message : String(err)}`, "faulted");
         throw err;
     }
     if (refusal === null)
         return null;
     deps.metrics?.inc("execution_placement_rejects_total", { errorCode: refusal.body.errorCode });
-    await release(`execution placement rejected: [${refusal.body.errorCode}] ${refusal.body.error}`);
+    await release(`execution placement rejected: [${refusal.body.errorCode}] ${refusal.body.error}`, isRootSessionGoneRefusal(refusal) ? "gone" : "refused");
     return refusal;
 }
-async function releaseClaim(deps, claim, why) {
+export async function withdrawClaim(deps, claim, why, ending) {
+    const loud = (taskId, step, err) => {
+        deps.logger?.warn("execution_placement_run_release_failed", { taskId, step, err: err instanceof Error ? err.message : String(err) });
+        deps.metrics?.inc("execution_placement_run_release_failed_total");
+    };
     switch (claim.kind) {
         case "run":
-            await releaseClaimedRun(claim.runStore, claim.taskId, why, (err, step) => {
-                deps.logger?.warn("execution_placement_run_release_failed", { taskId: claim.taskId, step, err: err instanceof Error ? err.message : String(err) });
-                deps.metrics?.inc("execution_placement_run_release_failed_total");
-            });
+            await withdrawClaimedRun(claim.runStore, claim.taskId, claim.legId, (err, step) => loud(claim.taskId, step, err));
+            return;
+        case "resumed":
+            if (ending !== "gone") {
+                await claim.restore();
+                return;
+            }
+            await releaseClaimedRun(claim.runStore, claim.taskId, why, (err, step) => loud(claim.taskId, step, err));
             return;
         case "parked":
             await claim.rollback(why);
             return;
         default: {
             const unhandled = claim;
-            throw new Error(`commitExecutionContext: unknown claim ${JSON.stringify(unhandled)}`);
+            throw new Error(`withdrawClaim: unknown claim ${JSON.stringify(unhandled)}`);
         }
     }
 }
-async function commitPlace(seat, ctx, occupant, withDeadline, goneAnswer) {
+async function commitPlace(seat, ctx, occupant, withDeadline) {
     if (ctx.lane === "device") {
         return deviceRefusal(buildDeviceRejection(DEVICE_ERROR_CODES.NOT_BOUND, "this session has no device binding — nothing was started"));
     }
-    return placeOutcomeAnswer(ctx.root, await withDeadline(seat.place(ctx.root, occupant, { role: "writer", lane: ctx.lane })), goneAnswer);
+    return placeOutcomeAnswer(ctx.root, await withDeadline(seat.place(ctx.root, occupant, { role: "writer", lane: ctx.lane })));
 }
-function placeOutcomeAnswer(root, outcome, goneAnswer) {
+function placeOutcomeAnswer(root, outcome) {
     switch (outcome.outcome) {
         case "placed":
         case "same":
@@ -286,17 +363,17 @@ function placeOutcomeAnswer(root, outcome, goneAnswer) {
         case "mirror":
             return sessionMirrorAnswer(root);
         case "gone":
-            return goneAnswer();
+            return rootSessionAbsentAnswer();
         default: {
             const unhandled = outcome;
             throw new Error(`commitExecutionContext: no answer for ${JSON.stringify(unhandled)}`);
         }
     }
 }
-async function reassertWriter(seat, ctx, occupant, withDeadline, goneAnswer) {
+async function reassertWriter(seat, ctx, occupant, withDeadline) {
     const now = await withDeadline(seat.read(ctx.root));
     if (now === undefined || !sameOccupant(now.occupant, occupant))
-        return goneAnswer();
+        return rootSessionAbsentAnswer();
     const cell = now.cell;
     switch (cell.role) {
         case "writer":
@@ -312,20 +389,31 @@ async function reassertWriter(seat, ctx, occupant, withDeadline, goneAnswer) {
         }
     }
 }
-async function commitDevice(deps, seat, intent, withDeadline, goneAnswer) {
+async function commitDevice(deps, seat, intent, withDeadline) {
     const enrollment = deps.deviceEnrollment;
     if (!enrollment) {
         throw new Error("commitExecutionContext: a device placement intent was minted without a DeviceEnrollment — assembly bug (both are read from the same ServiceDeps)");
     }
+    const registry = async (work) => {
+        try {
+            return { ok: true, value: await withDeadline(work) };
+        }
+        catch (e) {
+            return { ok: false, refusal: deviceRefusal(faultedAnswerOf(e, registryUnavailable)) };
+        }
+    };
     if (intent.firstBind) {
-        const bound = await withDeadline(enrollment.bindPlacement({ rootSessionId: intent.rootSessionId, occupant: intent.occupant, deviceId: intent.admittedDeviceId, requester: intent.owner }));
+        const binding = await registry(enrollment.bindPlacement({ rootSessionId: intent.rootSessionId, occupant: intent.occupant, deviceId: intent.admittedDeviceId, requester: intent.owner }));
+        if (!binding.ok)
+            return binding.refusal;
+        const bound = binding.value;
         if (bound.ok)
             return null;
         if ("reject" in bound)
             return deviceRefusal(bound.reject);
         switch (bound.placement) {
             case "gone":
-                return goneAnswer();
+                return rootSessionAbsentAnswer();
             case "mirror":
                 return sessionMirrorAnswer(intent.rootSessionId);
             case "tree_bound":
@@ -338,8 +426,10 @@ async function commitDevice(deps, seat, intent, withDeadline, goneAnswer) {
     }
     const placement = await withDeadline(seat.read(intent.rootSessionId));
     if (placement === undefined || !sameOccupant(placement.occupant, intent.occupant))
-        return goneAnswer();
-    const readmitted = await withDeadline(enrollment.admitSession({ rootSessionId: intent.rootSessionId, placement, requester: intent.owner, requestedDeviceId: intent.admittedDeviceId }));
-    return readmitted.ok ? null : deviceRefusal(readmitted.reject);
+        return rootSessionAbsentAnswer();
+    const readmission = await registry(enrollment.admitSession({ rootSessionId: intent.rootSessionId, placement, requester: intent.owner, requestedDeviceId: intent.admittedDeviceId }));
+    if (!readmission.ok)
+        return readmission.refusal;
+    return readmission.value.ok ? null : deviceRefusal(readmission.value.reject);
 }
 //# sourceMappingURL=execution-context.js.map