@sema-agent/server 7.138.0 → 7.139.0

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

@@ -0,0 +1,218 @@
+/**
+ * **执行上下文** —— 每条执行起点从这一只解析器取同一型上下文:根会话是谁、这一位住客在根会话行上的执行放置是什么、这条执行走哪条车道、
+ * 主体能不能用这条车道;认领之后的初始放置只有一只写口 {@link commitExecutionContext}。
+ *
+ * ## 规则(一句)
+ * 根只有一个来源 = authorizer(`ServiceCoreDeps.authorize` 必填席,唯一铸点即登记点),根进 spec 只有一个写者 = {@link stampSpecRoot};
+ * 执行放置**读只有一只** —— 会话店执行席 `seat.read(root)` 一次行读(住客 + 格),解析器读它、提交腿的门交来的 `judged` 比它、设备准入链判的也是这一读;
+ * **写只有一只** —— 认领之后的 {@link commitExecutionContext}(按解析器那一读的住客定址,0 行按住客复读分类,永不对现住客重试)。
+ *
+ * ## 解析步序(设计 §3.2 表 ①–④;⑤ 取 rig 不在本版)
+ *  ① 读:会话店不带执行席 ⇒ absent、`occupant` 缺(只一元车道表的部署可能);否则一次行读 —— 行不在 ⇒ 404 `resume.session_not_found`;`judged`(门判过的那一读)
+ *     在场而与行头不是同一位住客(化身 ∧ 属主,写口同一只判官 `sameOccupant`)⇒ 同 404(他人在门与解析之间删掉并同 id 重登记,或同一化身的属主变了 ——
+ *     local M10 认领 / identical 重戳 / SQL 导入提交点改属主 —— 判到新住客的车道就是错的);local 格是 `forking`
+ *     ⇒ 409 `conflict.fork_in_progress`;读故障抛(不吞成 absent)。解析器不建行、不铸根。
+ *  ② 定车道:`mirror` ⇒ 409 `conflict.session_mirror`(体带 `forkPath`);`writer(L)` 而 L 不在本部署的车道表 ⇒ 409 `execution_lane.not_served{boundLane}`;absent ⇒ 表首。
+ *  ③ 授权:主体的执行车道裁定(`gateExecutionLane`,判据与码同 `runtime-caps-resolver.ts`);服务形不判。
+ *  ④ 只 fresh:设备准入链(体 `deviceId` 只在 device 车道收;准入链三步 + 首绑目标三读,全读;判的是步 ① 那一读)。
+ *
+ * 入口三形(判别联合,{@link ExecutionEntry}):`fresh`(提交腿:根 = authorizer 交出的 `auth.sessionId`,`judged` = authorizer 判过的头)·
+ * `continuation`(续跑家族与停驻赎回:根 = checkpoint / 停驻行的根;不带 `judged` —— 步 ① 那一读就是这条执行对根的唯一一读,认领之后由写口按它判)·
+ * `service`(服务 run:没有会话根)。
+ * `fresh` / `continuation` 两形型上恒带 `root: string`,`service` 形没有 `root` 键 —— 「按一只缺席的根去读行」在型上不可表达。
+ *
+ * ## 提交({@link commitExecutionContext};设计 §3.2「提交」)
+ * 只在认领之后(四个 `createRun` 点、续跑家族 `markResuming` 之后、停驻赎回 `claimParkedAgent` 之后)调,是认领之后改执行放置的唯一写口:
+ *  · 有设备意图(fresh ∧ device 车道)⇒ 首绑(设备店一只事务,按住客定址)或已绑臂的再断言(按住客再读 + 准入链再断言设备);
+ *  · absent ⇒ place(非 device 车道);命中 = 成立;0 行按住客复读分类:同值 = 成立 · 异车道 ⇒ `execution_lane.tree_bound` · mirror ⇒ `conflict.session_mirror` ·
+ *    gone(行不在或住客不是解析器那一位)⇒ 「会话不在」(提交腿 404 `resume.session_not_found`;停驻赎回答它自己的 `decide.not_parked`)—— **不对现住客重试**;
+ *  · writer ⇒ 按住客再读断言仍是 writer(L);
+ *  · 拒 ⇒ 先释放本次认领(run:终结 + 放认领 + 放幂等键;停驻:回滚认领)再交回拒答;店故障 ⇒ 释放后原样上抛(响亮,不当答案)。
+ * claim 之后每一次店往返都带 {@link placementWriteDeadlineMs} 硬时限。
+ *
+ * ## 便利度不变(clay [ref] 硬约束)
+ * 本文件**不产生任何审批**:只做「这条会话放在哪条车道 / 哪台设备上」的读、判与认领之后的一次写。device 车道上 `permissionMode: "bypassPermissions"` 的 run
+ * 与 host 车道同构造同读数(判据钉在 device-first-bind 测试的「零额外审批」格)。
+ */
+import type { IncomingMessage } from "node:http";
+import type { SessionHead, TaskSpec } from "@sema-agent/core";
+import { type DeviceOwner, type DeviceStore } from "../device-store.js";
+import { type DeviceEnrollment, type DeviceRejection } from "../device-enrollment.js";
+import type { ServiceConfig } from "../config.js";
+import type { RunStore } from "../plugins/store-backend.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type ExecutionLane } from "../execution-lane-caps.js";
+import type { ExecutionRuling } from "../web-admin-client/facade.js";
+import type { Logger } from "../observability/logger.js";
+import type { SessionFace } from "../session-incarnation.js";
+import { type RefusalBody } from "./refusal-body.js";
+/** 门判过的那一读(authorizer 的头;只 `fresh` 入口带):解析器拿它的住客(化身 ∧ 属主)与行头比 —— 判官 = 写口同一只 `sameOccupant`。 */
+export type JudgedOccupant = Pick<SessionHead, "owner" | "incarnation">;
+/** 执行起点交给解析器的入口。 */
+export type ExecutionEntry = {
+    readonly kind: "fresh";
+    readonly root: string;
+    /** 主体(授权步 ③ 按它问执行车道裁定)。 */
+    readonly principal: string | undefined;
+    /** authorizer 判过的头(属主门那一读;现铸臂是登记后那一读)。缺 = 店没有 `headOf`(只一元表无席形可达)。 */
+    readonly judged: JudgedOccupant | undefined;
+    /** 设备准入(步 ④)的两样输入:调用方的请求(判调用方域)与体里的 `deviceId`(原值,形在步 ④ 判)。 */
+    readonly req: IncomingMessage | undefined;
+    readonly deviceId: unknown;
+} | {
+    readonly kind: "continuation";
+    readonly root: string;
+    readonly principal: string | undefined;
+} | {
+    readonly kind: "service";
+};
+/** 解析器的产出:有会话根的两形与没有根的服务形。 */
+export type ExecutionContext = {
+    readonly kind: "fresh" | "continuation";
+    readonly root: string;
+    /** 步 ① 那一读的住客;会话店不带执行席 ⇒ 缺(提交无事可做)。 */
+    readonly occupant: SessionFace | undefined;
+    readonly placement: "absent" | "writer";
+    readonly lane: ExecutionLane;
+    /** 只 fresh ∧ device 车道:准入链判完的设备意图(认领之后由 {@link commitExecutionContext} 写或再断言)。 */
+    readonly device?: DevicePlacementIntent;
+} | {
+    readonly kind: "service";
+    readonly lane: ExecutionLane;
+    readonly placement: "absent";
+};
+/** 带根的上下文 —— 认领之后的提交、审批席的出处车道读这一形(服务 run 不认领)。 */
+export type RootedExecutionContext = Extract<ExecutionContext, {
+    readonly root: string;
+}>;
+/** 装配器(`resolveSpec`)收的那一半:根与入口形(它不判放置、不选车道)。 */
+export type ExecutionRoot = Pick<RootedExecutionContext, "kind" | "root">;
+/** 解析器读的部署件(全部取自同一只 `ServiceDeps`)。 */
+export interface ExecutionContextDeps {
+    readonly config: ServiceConfig;
+    /** 会话店:执行席 `executionPlacement` 是放置的唯一载体与唯一读。 */
+    readonly sessionStorage?: {
+        readonly executionPlacement?: ExecutionPlacementSeat;
+    } | undefined;
+    /** 主体的执行车道裁定(caps client;缺 = 无中心 ⇒ 不判,与已发同)。 */
+    readonly executionRuling?: ((principal: string | undefined) => Promise<ExecutionRuling | undefined>) | undefined;
+    readonly logger?: Logger | undefined;
+    readonly deviceStore?: DeviceStore | undefined;
+    readonly deviceEnrollment?: DeviceEnrollment | undefined;
+}
+/**
+ * **唯一的解析器**(设计 §3.2 步 ①–④)。同一入口、同一行、同一裁定恒得同一上下文;判别是穷举的(新入口形 = 编译错)。
+ * 拒一律抛 typed `HttpError`(提交腿原样答;续跑家族照它自己的折叠律答,`http/resume-legs.ts`)。
+ */
+export declare function resolveExecutionContext(deps: ExecutionContextDeps, entry: Extract<ExecutionEntry, {
+    readonly root: string;
+}>): Promise<RootedExecutionContext>;
+export declare function resolveExecutionContext(deps: ExecutionContextDeps, entry: ExecutionEntry): Promise<ExecutionContext>;
+/** 拒体里「继续在本处执行」的下一步路径(fork 口)—— 镜像拒体的 `forkPath` 唯一铸法(执行面与会话行写口 `PATCH /v1/sessions/:id` 同读)。 */
+export declare function forkPathOf(root: string): string;
+/** 解析器的拒是不是「会话不在」(停驻赎回腿把它答成自己既有的 `decide.not_parked`;判据只在这里认那只答复的码)。 */
+export declare function isRootSessionGoneError(err: unknown): boolean;
+/**
+ * 调用方 device 域的**唯一铸造点**。`undefined` = 判不出域(无 principal,或凭据不带 tenant claim)—— 消费点必须响亮拒,禁静默空视图。
+ *
+ * 🔴 位置即契约:`{owner_tenant, owner_subject}` 是 O11 的 device-lane-local 复合身份(全局 principal 一个字节不动)。subject = `gatedPrincipal`(verified 链),
+ * tenant = `ssoVerifiedScope`(registry auth-bridge JWT 的 `scope` claim)—— **两者都是签名真源,不是自报头**。管理面三读三写与首绑写协议全部从这一只函数取域;
+ * 派生第二份就是把 O11 的判据本体复制成一份会漂的孪生。
+ */
+export declare function deviceOwnerDomainOf(req: IncomingMessage, config: ServiceConfig): DeviceOwner | undefined;
+/**
+ * **已校验、未写库**的设备放置意图(device 车道的 fresh 上下文才带)。解析那一刻还不知道哪个并发请求会赢下会话的认领,所以它不写 ——
+ * 只把「如果我赢了,该写什么 / 该断言什么」算好交给 {@link commitExecutionContext}。
+ */
+export interface DevicePlacementIntent {
+    /** 绑定键 = **根**会话(后代无条件继承)。 */
+    readonly rootSessionId: string;
+    /** 步 ① 那一读的住客:首绑写按住客谓词;已绑臂的再断言先比住客。 */
+    readonly occupant: SessionFace;
+    /** 验证过的复合身份(恒取 verified 链,不取自可伪造头)。 */
+    readonly owner: DeviceOwner;
+    /**
+     * **准入链批准的那台设备** —— 提交的断言对象。身份留在意图里,已绑臂才有东西可断言(一条写了 `deviceId: A` 的提交在「准入过后、认领之前」被换绑到 B
+     * 时不许静默在 B 上跑完 —— 执行环境工厂读的是**当下**的绑定)。
+     */
+    readonly admittedDeviceId: string;
+    /** `true` = 解析那一读里还没有设备绑定 ⇒ 提交做那一次首绑(写);`false` = 已绑 ⇒ 提交不写,只再断言。 */
+    readonly firstBind: boolean;
+}
+/**
+ * 装配器的产物型:根不归装配器写。`{ sessionId?: never }` 让任何型上带 `string` 的 `sessionId`(字面量、变量、展开、`TaskSpec` 型值)都不可赋;
+ * 擦型(`any` / `as unknown as`)与 JS 嵌入方不归型管,由 {@link stampSpecRoot} 的运行时判兜。
+ */
+export type ResolvedTaskSpec = Omit<TaskSpec, "sessionId"> & {
+    sessionId?: never;
+};
+/** 盖过根的 spec:执行点、认领、续跑输入读的都是这一形(`sessionId` 恒在)。 */
+export type RootedTaskSpec = TaskSpec & {
+    readonly sessionId: string;
+};
+/**
+ * **根进 spec 的唯一写者。** 装配器交回的 spec 上 `sessionId` 缺席(或为 `undefined`)⇒ 盖上这条上下文的根;
+ * 在场且等于根 ⇒ 同值,照盖;在场而**不等** ⇒ 400 `request.precondition_unmet`(嵌入方的装配器另点了一只会话 —— 它在型上不能这么写,
+ * 走到这里只能是擦型或 JS 形;拒在建任何行之前)。续跑家族照它自己的折叠律把这只拒答成 409 `resume_blocked_by_policy`(`blockedBy` = 这只码,
+ * `http/resume-legs.ts` 的 `resolveResumeSpecOrBlocked`:装配期的每一只 `HttpError` 在续跑腿上都这么折),同样什么都没续。
+ */
+export declare function stampSpecRoot(spec: ResolvedTaskSpec, ctx: ExecutionRoot): RootedTaskSpec;
+/**
+ * run 店建行时根会话行已经不在(`CreateRunOutcome.sessionAbsent`:受理之后、认领之前会话被删)的**唯一**答复 ——
+ * 四个建行点(同步 / 流式 / durable / wake)、解析期的「行不在 / 住客换了」与提交期的 `gone` 同答 404 `resume.session_not_found`,什么都没建、什么都没跑。
+ */
+export declare function rootSessionAbsentAnswer(): {
+    status: 404;
+    body: RefusalBody;
+};
+/** 提交点的拒答(各建行点用自己协议的发送姿势,状态与体只有这一份)。 */
+export interface ExecutionRefusal {
+    readonly status: number;
+    readonly body: RefusalBody;
+}
+/**
+ * 本次认领 —— 提交拒时要释放的东西。`run` = 四个建行点与续跑家族认领的 run 行(释放 = 终结 + 放认领 + 放幂等键,唯一写法 `releaseClaimedRun`);
+ * `parked` = 停驻赎回的认领(释放 = 回滚认领;「会话不在」答那条腿既有的 `decide.not_parked`,不是提交腿的 404)。
+ */
+export type ExecutionClaim = {
+    readonly kind: "run";
+    readonly runStore: RunStore;
+    readonly taskId: string;
+} | {
+    readonly kind: "parked";
+    readonly taskId: string;
+    readonly rollback: (why: string) => Promise<unknown>;
+    readonly goneAnswer: ExecutionRefusal;
+};
+/** {@link commitExecutionContext} 的依赖 —— 逐字取自 `ServiceDeps` 的同名键(同一只 deps 对象喂进来)。 */
+export interface ExecutionCommitDeps {
+    readonly sessionStorage?: {
+        readonly executionPlacement?: ExecutionPlacementSeat;
+    } | undefined;
+    readonly deviceEnrollment?: DeviceEnrollment | undefined;
+    readonly config?: {
+        readonly runStaleSec?: number;
+    } | undefined;
+    readonly logger?: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    } | undefined;
+    readonly metrics?: {
+        inc(name: string, labels?: Record<string, string>): void;
+    } | undefined;
+}
+/**
+ * claim 之后那一次写 / 再读的**硬时限**:从 `runStaleSec` 派生(不新铸旋钮)—— 它只回答「这次店往返会不会挂到 stale 回收把认领收走」。
+ * 取四分之一并夹在 `[1s, 15s]`。
+ */
+export declare function placementWriteDeadlineMs(runStaleSec: number | undefined): number;
+/** 拒绝的**唯一** wire 体铸点(各消费点各自用自己协议的发送姿势,但体的键集只有这一份)。 */
+export declare function devicePlacementErrorBody(rej: DeviceRejection): RefusalBody;
+/**
+ * **认领之后的唯一写口**(四个 `createRun` 点、续跑家族 `markResuming` 之后、停驻赎回 `claimParkedAgent` 之后)。返回 `null` = 放行;
+ * 否则本次认领已释放,调用方交回拒答。店故障 / 超时 ⇒ 释放后原样上抛(响亮,不当答案);设备意图那一支的注册簿故障答 {@link registryUnavailable}(设备闭集,同准入阶段)。
+ *
+ * 不变量(一句):**离开本函数的那一刻,这条会话(解析器那一位住客)的格就是这条执行的车道(device 车道:准入批准的那台设备);否则本次认领已释放、调用方拿到拒答。**
+ * 它不说「此后不变」:认领持有期间根行住客与放置不被换绑 / 导入改动,那是各写者写事务内锁根行后读认领的保证(规则句),不在本函数重复判。
+ */
+export declare function commitExecutionContext(deps: ExecutionCommitDeps, claim: ExecutionClaim, ctx: RootedExecutionContext): Promise<ExecutionRefusal | null>;
+//# sourceMappingURL=execution-context.d.ts.map

package/dist/http/execution-context.js

@@ -0,0 +1,330 @@
+import { HttpError, createCodedHttpError, ssoVerifiedScope } from "../security.js";
+import { gatedPrincipal } 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 { deployedExecutionLanes } from "../execution-lane-caps.js";
+import { gateExecutionLane } from "../runtime-caps-resolver.js";
+import { releaseClaimedRun } from "./claimed-run.js";
+import { refusalBody } from "./refusal-body.js";
+export async function resolveExecutionContext(deps, entry) {
+    const lanes = deployedExecutionLanes(deps.config);
+    switch (entry.kind) {
+        case "service":
+            return { kind: "service", lane: lanes[0], placement: "absent" };
+        case "fresh":
+        case "continuation": {
+            const seat = deps.sessionStorage?.executionPlacement;
+            const reading = seat === undefined ? undefined : await readRow(seat, entry.root, entry.kind === "fresh" ? entry.judged : undefined);
+            const { lane, placement } = laneOf(entry.root, reading?.cell ?? { role: "absent" }, lanes);
+            gateExecutionLane(await deps.executionRuling?.(entry.principal), lane, deps.logger);
+            const ctx = { kind: entry.kind, root: entry.root, occupant: reading?.occupant, placement, lane };
+            if (entry.kind === "continuation")
+                return ctx;
+            const device = await admitDevicePlacement(deps, entry, lane, seat, reading);
+            return device === undefined ? ctx : { ...ctx, device };
+        }
+        default: {
+            const unhandled = entry;
+            throw new Error(`resolveExecutionContext: unhandled entry ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+async function readRow(seat, root, judged) {
+    const reading = await seat.read(root);
+    if (reading === undefined || (judged !== undefined && !sameOccupant(judged, reading.occupant)))
+        throw rootSessionGoneError();
+    if (reading.cell.role === "forking") {
+        throw createCodedHttpError(409, "conflict.fork_in_progress", "this session is the target of a fork that has not finished copying — retry that fork with the same forkId and forkNonce, or delete the session; nothing was started");
+    }
+    return reading;
+}
+function laneOf(root, cell, lanes) {
+    switch (cell.role) {
+        case "absent":
+            return { lane: lanes[0], placement: "absent" };
+        case "writer":
+            if (!lanes.includes(cell.lane)) {
+                throw createCodedHttpError(409, "execution_lane.not_served", "this session is placed where this deployment no longer runs work (see boundLane) — nothing was started", { boundLane: cell.lane });
+            }
+            return { lane: cell.lane, placement: "writer" };
+        case "mirror":
+            throw sessionMirrorError(root);
+        case "forking":
+            throw new Error(`resolveExecutionContext: session ${root} reads as forking after the read step refused it`);
+        default: {
+            const unknownRole = cell;
+            throw new Error(`resolveExecutionContext: no lane for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+function sessionMirrorError(root) {
+    const answer = sessionMirrorAnswer(root);
+    return createCodedHttpError(answer.status, answer.body.errorCode, answer.body.error, { forkPath: forkPathOf(root) });
+}
+export function forkPathOf(root) {
+    return `/v1/sessions/${encodeURIComponent(root)}/fork`;
+}
+function sessionMirrorAnswer(root) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "conflict.session_mirror",
+            message: "this session is a read-only mirror of a session whose writer is elsewhere — it cannot run here; fork it (forkPath) to continue here; nothing was started",
+            facts: { forkPath: forkPathOf(root) },
+        }),
+    };
+}
+function rootSessionGoneError() {
+    const absent = rootSessionAbsentAnswer();
+    return createCodedHttpError(absent.status, absent.body.errorCode, absent.body.error);
+}
+export function isRootSessionGoneError(err) {
+    return err instanceof HttpError && err.code === rootSessionAbsentAnswer().body.errorCode;
+}
+export function deviceOwnerDomainOf(req, config) {
+    const subject = gatedPrincipal(req, config);
+    if (subject === undefined)
+        return undefined;
+    const tenant = ssoVerifiedScope(req);
+    if (tenant === undefined)
+        return undefined;
+    return { tenant, subject };
+}
+function asHttpError(rej) {
+    return createCodedHttpError(rej.status, rej.code, rej.message);
+}
+function registryUnavailable() {
+    return buildDeviceRejection(DEVICE_ERROR_CODES.NOT_BOUND, "the device binding for this session could not be resolved (the device registry is unavailable) — refusing rather than running on an unverified device");
+}
+async function admitDevicePlacement(deps, entry, lane, seat, reading) {
+    const requested = entry.deviceId;
+    if (lane !== "device") {
+        if (requested !== undefined) {
+            throw createCodedHttpError(400, "request.precondition_unmet", "deviceId is only accepted on a deployment that executes on the user's own device (REMOTE_EXEC=device) — this deployment does not, so binding this session to a device id would be a declaration that never took effect");
+        }
+        return undefined;
+    }
+    if (!deps.deviceStore || !deps.deviceEnrollment || seat === undefined || reading === undefined) {
+        throw createCodedHttpError(501, "capability.device_lane_required", "device execution is selected for this deployment but its stores are not wired on this replica — refusing to admit a submit that would execute nowhere");
+    }
+    if (entry.req === undefined) {
+        throw createCodedHttpError(403, "auth.forbidden", "device placement needs a verified caller domain and this leg carries no request context");
+    }
+    const owner = deviceOwnerDomainOf(entry.req, deps.config);
+    if (owner === undefined) {
+        throw createCodedHttpError(403, "auth.forbidden", "device placement needs a caller domain: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`) — connect through the registry auth bridge");
+    }
+    if (requested !== undefined) {
+        if (typeof requested !== "string") {
+            throw createCodedHttpError(400, "request.field_invalid", "deviceId must be a string (the device id returned by POST /v1/devices/enroll)");
+        }
+        try {
+            assertDeviceIdShape(requested);
+        }
+        catch {
+            throw createCodedHttpError(400, "request.field_invalid", "deviceId is not a valid device id (byte-exact key: non-empty, no control characters or surrounding whitespace, at most 64 bytes)");
+        }
+    }
+    const requestedDeviceId = requested;
+    let admitted;
+    try {
+        admitted = await deps.deviceEnrollment.admitSession({ rootSessionId: entry.root, placement: reading, requester: owner, ...(requestedDeviceId === undefined ? {} : { requestedDeviceId }) });
+    }
+    catch {
+        throw asHttpError(registryUnavailable());
+    }
+    if (admitted.ok)
+        return { rootSessionId: entry.root, occupant: reading.occupant, owner, admittedDeviceId: admitted.value.deviceId, firstBind: false };
+    if (admitted.reject.code !== DEVICE_ERROR_CODES.NOT_BOUND || requestedDeviceId === undefined)
+        throw asHttpError(admitted.reject);
+    let view;
+    try {
+        view = await deps.deviceStore.readDeviceForAdmission(requestedDeviceId, owner);
+    }
+    catch {
+        throw asHttpError(registryUnavailable());
+    }
+    if (!view)
+        throw asHttpError(buildDeviceRejection(DEVICE_ERROR_CODES.NOT_FOUND, "device not found"));
+    if (view.row.status === "revoked")
+        throw asHttpError(buildDeviceRejection(DEVICE_ERROR_CODES.REVOKED, "device has been revoked"));
+    if (!view.online)
+        throw asHttpError(buildDeviceRejection(DEVICE_ERROR_CODES.OFFLINE, "device is not connected"));
+    return { rootSessionId: entry.root, occupant: reading.occupant, owner, admittedDeviceId: requestedDeviceId, firstBind: true };
+}
+export function stampSpecRoot(spec, ctx) {
+    const named = spec.sessionId;
+    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)");
+    }
+    return { ...spec, sessionId: ctx.root };
+}
+export function rootSessionAbsentAnswer() {
+    return {
+        status: 404,
+        body: refusalBody({
+            errorCode: "resume.session_not_found",
+            message: "the session this run was to start on no longer exists (it was deleted after the request was admitted) — nothing was started",
+        }),
+    };
+}
+export function placementWriteDeadlineMs(runStaleSec) {
+    const stale = typeof runStaleSec === "number" && Number.isFinite(runStaleSec) && runStaleSec > 0 ? runStaleSec : 120;
+    return Math.min(15_000, Math.max(1_000, Math.floor((stale * 1000) / 4)));
+}
+function deviceRefusal(rej) {
+    return { status: rej.status, body: devicePlacementErrorBody(rej) };
+}
+export function devicePlacementErrorBody(rej) {
+    return refusalBody({ errorCode: rej.code, message: rej.message });
+}
+function treeBoundAnswer(boundLane) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "execution_lane.tree_bound",
+            message: "this session is already placed elsewhere on this deployment (see boundLane) — this run cannot be placed somewhere else; nothing was started",
+            facts: { boundLane },
+        }),
+    };
+}
+export async function commitExecutionContext(deps, claim, ctx) {
+    const seat = deps.sessionStorage?.executionPlacement;
+    if (ctx.occupant === undefined || seat === undefined)
+        return null;
+    const occupant = ctx.occupant;
+    const release = (why) => releaseClaim(deps, claim, why);
+    const deadlineMs = placementWriteDeadlineMs(deps.config?.runStaleSec);
+    const withDeadline = async (work) => {
+        let timer;
+        try {
+            return await Promise.race([
+                work,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error(`execution placement store call exceeded ${deadlineMs}ms`)), deadlineMs);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                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)
+                : ctx.placement === "absent"
+                    ? await commitPlace(seat, ctx, occupant, withDeadline, goneAnswer)
+                    : await reassertWriter(seat, ctx, occupant, withDeadline, goneAnswer);
+    }
+    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());
+            deps.metrics?.inc("execution_placement_rejects_total", { errorCode: refusal.body.errorCode });
+            return refusal;
+        }
+        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}`);
+    return refusal;
+}
+async function releaseClaim(deps, claim, why) {
+    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");
+            });
+            return;
+        case "parked":
+            await claim.rollback(why);
+            return;
+        default: {
+            const unhandled = claim;
+            throw new Error(`commitExecutionContext: unknown claim ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+async function commitPlace(seat, ctx, occupant, withDeadline, goneAnswer) {
+    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);
+}
+function placeOutcomeAnswer(root, outcome, goneAnswer) {
+    switch (outcome.outcome) {
+        case "placed":
+        case "same":
+            return null;
+        case "tree_bound":
+            return treeBoundAnswer(outcome.boundLane);
+        case "mirror":
+            return sessionMirrorAnswer(root);
+        case "gone":
+            return goneAnswer();
+        default: {
+            const unhandled = outcome;
+            throw new Error(`commitExecutionContext: no answer for ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+async function reassertWriter(seat, ctx, occupant, withDeadline, goneAnswer) {
+    const now = await withDeadline(seat.read(ctx.root));
+    if (now === undefined || !sameOccupant(now.occupant, occupant))
+        return goneAnswer();
+    const cell = now.cell;
+    switch (cell.role) {
+        case "writer":
+            return cell.lane === ctx.lane ? null : treeBoundAnswer(cell.lane);
+        case "mirror":
+            return sessionMirrorAnswer(ctx.root);
+        case "absent":
+        case "forking":
+            throw new Error(`commitExecutionContext: session ${ctx.root} was resolved as a writer and now reads as ${cell.role} for the same occupant`);
+        default: {
+            const unknownRole = cell;
+            throw new Error(`commitExecutionContext: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
+async function commitDevice(deps, seat, intent, withDeadline, goneAnswer) {
+    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)");
+    }
+    if (intent.firstBind) {
+        const bound = await withDeadline(enrollment.bindPlacement({ rootSessionId: intent.rootSessionId, occupant: intent.occupant, deviceId: intent.admittedDeviceId, requester: intent.owner }));
+        if (bound.ok)
+            return null;
+        if ("reject" in bound)
+            return deviceRefusal(bound.reject);
+        switch (bound.placement) {
+            case "gone":
+                return goneAnswer();
+            case "mirror":
+                return sessionMirrorAnswer(intent.rootSessionId);
+            case "tree_bound":
+                return treeBoundAnswer(bound.boundLane);
+            default: {
+                const unhandled = bound;
+                throw new Error(`commitExecutionContext: no answer for ${JSON.stringify(unhandled)}`);
+            }
+        }
+    }
+    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);
+}
+//# sourceMappingURL=execution-context.js.map