@sema-agent/server 7.148.0 → 7.150.0

package/dist/http/owner-access.d.ts

@@ -11,16 +11,30 @@
  *    `policyFace` = 策略面〔面表键〕,与 `session_owner_unreadable` 那一行的 `face` = 口名分开命名:一个字段名一义)。
  *
  * 嵌套可选读(会话面板的上一腿、审批预览)与协议口(A2A、leader、提交重放)用 {@link seesRun} / {@link seesSession}:不下发,看不见 = 没有,由调用点走它自己的缺席路径。
+ *
+ * ## 读只经这里([ref] 第二阶段)
+ * 请求路径上带属主的 run / 会话行**只有本模块读**,交出去的只有两种:**承认**(判过的行 —— 门 `admit*`、非下发读 `readVisible*`、承认之后的重读也是这两只,
+ * 同一只入口再判一次)与**不带属主格的一格事实**(`*FactsOf` / `*LeafReadOf` / `latestRunIdOf` / `sessionAgentOf`:持有认领的腿与承认派生的读要的那一格 ——
+ * 状态 / 位置 / 所属会话 / 叶子 / 委派元组,行本身不出本模块)。列表的属主过滤落成店的过滤参数也只在这里({@link listVisibleRuns} / {@link listRunsOfScope})。
+ * 路由层看到的店在型上没有按 id 读口({@link RouteRunStore} / {@link RouteSessionStore}:那几口的型是 `never`,调不了;视图仍是那只店的子型,交给本模块的口与持认领腿的
+ * 写口照常),视图只在一处铸({@link sealRouteDeps})。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { SessionHead } from "@sema-agent/core";
+import type { SessionHead, WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import type { RunStore, StoreBackend } from "../plugins/store-backend.js";
 import { type Logger } from "../observability/logger.js";
-import type { RunRecord } from "../plugins/store-contracts.js";
+import type { LatestRunRef, RunListQuery, RunRecord } from "../plugins/store-contracts.js";
 import type { ServiceConfig } from "../config-types.js";
-import { type Admitted, type Caller, type FaceId, type ListFaceId, type ListFilter, type OwnedReading, type Qual, type RunFaceId, type SessionFaceId } from "../owner-faces.js";
+import type { SessionAuditReadOpts } from "../audit.js";
+import { type DeploymentShapeInput } from "../deployment-shape.js";
+import { type SessionAgent } from "../session-agent.js";
+import { type SessionFace } from "../session-incarnation.js";
+import { type Admitted, type Caller, type FaceId, type ListFaceId, type ListFilter, type OwnedReading, type Qual, type RunFaceId, type SessionFaceId, type WorkflowFaceId } from "../owner-faces.js";
 import { type Person, type Subject } from "../owner-brands.js";
 import { type OwnerAwareSessionStore } from "../security.js";
 import { type OperatorRoster } from "./principal-gate.js";
+import { type RouteDeps } from "./route-ctx.js";
+import type { FlatServiceDeps } from "./server.js";
 import type { AgentRosterRouteId } from "./routes/agents-roster.js";
 import type { ApprovalsAssistantRouteId } from "./routes/approvals-assistant.js";
 import type { BackgroundRouteId } from "./routes/background.js";
@@ -36,6 +50,7 @@ import type { SessionSyncRouteId } from "./routes/session-sync.js";
 import type { SessionsListRouteId } from "./routes/sessions-list.js";
 import type { SessionsRouteId } from "./routes/sessions.js";
 import type { TraceUsageRouteId } from "./routes/trace-usage.js";
+import type { WorkflowAgentSteerRouteId, WorkflowsRouteId } from "./routes/workflows.js";
 /** 存取器读的装配:部署配置(身份来源只从配置读,见 `identity-source.ts` 的 `configuredIdentitySources`)+ 运维日志。`FlatServiceDeps` 结构上满足。 */
 export interface OwnerAccessWiring {
     readonly config: ServiceConfig;
@@ -43,8 +58,9 @@ export interface OwnerAccessWiring {
 }
 /**
  * 🔴 **一次请求的调用方**(唯一铸点之一;另一只是决定口的 {@link callerOfDecision}、提交挂接的 `security.ts` `claimCallerOf`)。
- * 主体 = `gatedSubject`(验身份的那一只;带场景头 ⇒ 这个人的那一格分区);运维 = `explicitOperatorOk(personOf(主体))`(唯一读法,读人);fleet = 部署没有身份边界(`devOpenDeployment`)或出示 service 凭据、
- * 不报主体、部署没声明关掉(`actsForDeployment`),两者互斥(前者要求没配凭据);只读 trace 凭据单列(它只在读档算 fleet,见面表 `fleet` 列)。
+ * 主体 = `gatedSubject`(验身份的那一只;带场景头 ⇒ 这个人的那一格分区);运维 = `explicitOperatorOk(personOf(主体))`(唯一读法,读人);fleet = `actsForDeployment`
+ * (唯一读法:报了主体 ⇒ 不是 fleet;不报主体 ⇒ 部署没有身份边界时 `dev_open`、出示部署让它代自己说话的 service 凭据时 `deployment_token`,两者互斥 —— 前者要求没配凭据);
+ * 只读 trace 凭据单列(它只在读档算 fleet,见面表 `fleet` 列)。报了主体的调用方因此在每一口都是那位主体,与提交挂接的 `claimCallerOf`(fleet 恒缺)同读。
  */
 export declare function callerOf(req: IncomingMessage, w: Pick<OwnerAccessWiring, "config">): Caller;
 /**
@@ -55,10 +71,10 @@ export declare function callerOf(req: IncomingMessage, w: Pick<OwnerAccessWiring
 export declare function callerOfDecision(base: Caller, decider: Person | undefined, roster: OperatorRoster): Caller;
 /** 决定者的主体(唯一读法;{@link callerOfDecision} 与只要主体 + 运维位的决断腿同读):证明推出的人 × 请求的场景(请求没带场景 ⇒ 与人逐字节同)。 */
 export declare function deciderSubjectOf(requestSubject: Subject | undefined, decider: Person | undefined): Subject | undefined;
-/** 属主面与列表面所在十六个域的路由 id(全部;无属主门的那几条登 `null`)。 */
-export type OwnedRouteId = RunsRouteId | RunVerbsRouteId | RunPermissionModeRouteId | RunMemoryCaptureRouteId | SessionsRouteId | SessionSyncRouteId | SessionMemorySyncRouteId | BackgroundRouteId | McpReconnectRouteId | NotifyWakeRouteId | TraceUsageRouteId | ApprovalsAssistantRouteId | SessionsListRouteId | FleetRouteId | ProjectsRouteId | AgentRosterRouteId;
+/** 属主面与列表面所在十八个域的路由 id(全部;无属主门的那几条登 `null`)。 */
+export type OwnedRouteId = WorkflowsRouteId | WorkflowAgentSteerRouteId | RunsRouteId | RunVerbsRouteId | RunPermissionModeRouteId | RunMemoryCaptureRouteId | SessionsRouteId | SessionSyncRouteId | SessionMemorySyncRouteId | BackgroundRouteId | McpReconnectRouteId | NotifyWakeRouteId | TraceUsageRouteId | ApprovalsAssistantRouteId | SessionsListRouteId | FleetRouteId | ProjectsRouteId | AgentRosterRouteId;
 /**
- * 🔴 **路由 → 面**(闭集穷举;`satisfies Record<…>`:十六个路由域里加一条路由不登 = 编译红,登错资源的面由 {@link admitRunRow} / {@link admitSessionRow} 的签名挡)。
+ * 🔴 **路由 → 面**(闭集穷举;`satisfies Record<…>`:十八个路由域里加一条路由不登 = 编译红,登错资源的面由 {@link admitRunRow} / {@link admitSessionRow} / {@link admitWorkflowRun} 的签名挡)。
  * 列表 / 舰队读面登列表面(`list.read` / `session.list`:属主视域经 `owner-faces.ts` 的 `listFilterOf` 从这一行派生)。
  * `null` = 这条路由不在本表判属主:提交面、ask / 检查点面(属主门在腿里经 `owner-faces.ts` 的 `keyAdmits` 判:决定 / 应答的属主是停驻行与问账行,不是路径上的这一行)。
  */
@@ -133,6 +149,11 @@ export declare const ROUTE_FACES: {
     readonly "assistant-task-preempt": "run.preempt";
     readonly "assistant-task-resume": "run.resume";
     readonly "assistant-task-plan-review": "run.decision";
+    readonly "workflows-list": "workflow.read";
+    readonly "workflow-detail": "workflow.read";
+    readonly "workflow-journal": "workflow.read";
+    readonly "workflow-stream": "workflow.read";
+    readonly "workflow-agent-steer": "workflow.steer";
     readonly "sessions-list": "session.list";
     readonly "sendfile-links": "list.read";
     readonly "fleet-stream": "list.read";
@@ -152,7 +173,11 @@ export type SessionRouteId = {
 export type ListRouteId = {
     [R in keyof RouteFaces]: RouteFaces[R] extends ListFaceId ? R : never;
 }[keyof RouteFaces];
-type RoutedId = RunRouteId | SessionRouteId | ListRouteId;
+/** 登到工作流面的路由(由表派生)。 */
+export type WorkflowRouteId = {
+    [R in keyof RouteFaces]: RouteFaces[R] extends WorkflowFaceId ? R : never;
+}[keyof RouteFaces];
+type RoutedId = RunRouteId | SessionRouteId | ListRouteId | WorkflowRouteId;
 /** 协议口 / 嵌套读的面(不经路由表的那几只;路由面一律经 {@link ROUTE_FACES})。 */
 export type ProtocolFaceId = "run.a2a" | "run.leader" | "run.replay" | "run.preview" | "run.panel" | "run.anchor";
 /** 读 run 行的口:登到 run 面的路由 + 协议口 / 嵌套读(由两张既有闭集派生)。 */
@@ -342,14 +367,18 @@ export declare function deliverVerdict<R extends OwnedReading>(entry: Entry, res
  * 交回承认(行 + 全部资格)或 `undefined`(已应答)。`id` = 路径上的 run id(句子的句柄指路;按幂等键读的口不传)。
  */
 export declare function admitRunRow(entry: Entry, res: ServerResponse, runStore: RunObserver, row: RunRecord | null | undefined, id?: string): Promise<Admitted<RunRecord> | undefined>;
+/** 本模块门读的 run 店:按 id 读口 + 观察口(路由层的视图上这一读口封着 —— 视图交得进来,路由自己调不了)。 */
+export type RunGateStore = Pick<RunStore, "getRun"> & RunObserver;
 /** run 面的门,行由本模块读(店唯一的按 id 读 `getRun`):路由不再自己读行(裸读普查门 ④ 的路由基线据此归零)。 */
-export declare function admitRunById(entry: Entry, res: ServerResponse, runStore: {
-    getRun(taskId: string): Promise<RunRecord | null | undefined>;
-} & RunObserver, taskId: string): Promise<Admitted<RunRecord> | undefined>;
-/** 嵌套可选读 / 协议口的 run 行读(不下发):本模块按 id 读一行并判,看不见 ≡ 没有(`undefined`),调用点走它自己的缺席路径。 */
-export declare function readVisibleRun(entry: Entry, runStore: {
-    getRun(taskId: string): Promise<RunRecord | null | undefined>;
-} & RunObserver, taskId: string): Promise<RunRecord | undefined>;
+export declare function admitRunById(entry: Entry, res: ServerResponse, runStore: RunGateStore, taskId: string): Promise<Admitted<RunRecord> | undefined>;
+/** run 面的门,按提交幂等键读行(`GET /v1/runs?idempotencyKey=`;键由调用方的身份铸,别人的键算出的是另一把):没有 / 看不见同一只投影,没有路径 id ⇒ 常量句。 */
+export declare function admitRunByIdem(entry: Entry, res: ServerResponse, runStore: Pick<RunStore, "getRunByIdem"> & RunObserver, idemKey: string): Promise<Admitted<RunRecord> | undefined>;
+/**
+ * run 行的非下发读:本模块按 id 读一行并判(属主门 + 本口的 `RUN_STATE_FACES`),看不见 ≡ 没有(`undefined`),调用点走它自己的缺席路径。
+ * 两种读者同用:嵌套可选读 / 协议口,与**承认之后的重读**(取消 / 抢占 / steer / 中断的竞态重读、流的逐拍复读、A2A 的等待循环)—— 重读用承认它的同一只入口,
+ * 对新读数再判一次同一只(run 行的属主不变,这一判对同一位调用方恒同答;行没了 ⇒ 没有)。交回承认(行 + 资格)。
+ */
+export declare function readVisibleRun(entry: Entry, runStore: RunGateStore, taskId: string): Promise<Admitted<RunRecord> | undefined>;
 /** run 行可见吗(不下发;嵌套可选读与协议口):看不见 ≡ 没有。 */
 export declare function seesRun(entry: Entry, owner: string | null | undefined): boolean;
 /**
@@ -375,16 +404,35 @@ export declare function readOwnerCell<T>(entry: Entry, sessionId: string, read:
  * 会话面的门:调用点读到的那一读(`undefined` / `null` = 没有;读不出按面折过的也是 `undefined`)交进来 —— 没有 ⇒ 投影;行格(无主、且 placement 改得了判时问一次);
  * 运维旁路 → 前门 → 看不见 ⇒ 同一投影。交回承认(读数 + 全部资格)或 `undefined`(已应答)。
  */
-export declare function admitSessionRow<T extends OwnedReading>(entry: Entry, res: ServerResponse, store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, reading: T | null | undefined): Promise<Admitted<T> | undefined>;
+export declare function admitSessionRow<T extends OwnedReading>(entry: Entry, res: ServerResponse, store: PlacementReadingStore | undefined, sessionId: string, reading: T | null | undefined): Promise<Admitted<T> | undefined>;
 /**
  * 会话行的判(不下发):行格只经 `security.ts` 的 {@link sessionCellFor}(无主行的 placed 位只在两种假设不都放行时问店;存档读不出按面表 `placementUnreadable` 列;
  * 别的读故障照常上抛)。事件流把这一判整个框进它的读期上限,判完再 {@link deliverVerdict}。
  */
-export declare function judgeSessionRow<T extends OwnedReading>(entry: Entry, store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, reading: T): Promise<OwnerVerdict<T>>;
-/** 会话面的门,头由本模块读(会话店唯一的按 id 读 `headOf`;读不出按面的 `unreadable` 列折):路由不再自己读头。 */
-export declare function admitSessionById(entry: Entry, res: ServerResponse, store: Pick<OwnerAwareSessionStore, "placementOf"> & Required<Pick<OwnerAwareSessionStore, "headOf">>, sessionId: string): Promise<Admitted<SessionHead> | undefined>;
+export declare function judgeSessionRow<T extends OwnedReading>(entry: Entry, store: PlacementReadingStore | undefined, sessionId: string, reading: T): Promise<OwnerVerdict<T>>;
+/** 本模块门读的会话店:按 id 头读(路由层的视图上封着)+ 无主行 placed 位的问询(可缺)。 */
+export type SessionGateStore = Required<Pick<OwnerAwareSessionStore, "headOf">> & PlacementReadingStore;
+/** 交 placed 位问询的店(可缺:店不交 ⇒ 无主行读作普通无主行,`security.ts` 的 `sessionOwnerCellOf`)。 */
+export type PlacementReadingStore = Pick<OwnerAwareSessionStore, "placementOf">;
+/**
+ * 会话面按 id 的判(不下发):头由本模块读(会话店唯一的按 id 读 `headOf`;读不出按面的 `unreadable` 列折)并判;`undefined` = 没有这一行。
+ * 门 {@link admitSessionById} 与非下发读 {@link readVisibleSession} 都是它;事件流把它整个框进自己的读期上限,判完再 {@link deliverVerdict}。
+ */
+export declare function judgeSessionById(entry: Entry, store: SessionGateStore, sessionId: string): Promise<OwnerVerdict<SessionHead> | undefined>;
+/** 会话面的门,头由本模块读:路由不再自己读头。没有 ⇒ 投影;前门 / 看不见经各自的下发口。 */
+export declare function admitSessionById(entry: Entry, res: ServerResponse, store: SessionGateStore, sessionId: string): Promise<Admitted<SessionHead> | undefined>;
+/**
+ * 会话行的非下发读:看不见 ≡ 没有。**承认之后的重读**用它(同一只入口对新读数再判一次同一只:两读之间易主 ⇒ 按新主判;行没了 ⇒ 没有)——
+ * 记忆同步栅栏的叶子复读等。住客(化身)绑定不在这里(见 `owner-faces.ts` 的 `Admitted`)。
+ */
+export declare function readVisibleSession(entry: Entry, store: SessionGateStore, sessionId: string): Promise<Admitted<SessionHead> | undefined>;
+/**
+ * 承认之后的**世代围栏**(会话事件流的心跳拍):这只会话此刻的属主还是承认时读到的那一格吗 —— 删了(没有这一行 / 读不出按面折)或换主 ⇒ 否。
+ * 与 {@link readVisibleSession} 的「再判可见」不同:比的是同一行前后两次读到的属主(删建 / 易主 ⇒ 作废),两侧都是行上的属主,不是调用方身份。
+ */
+export declare function sessionOwnerUnchanged(entry: Entry, store: SessionGateStore, sessionId: string, admittedOwner: string | null): Promise<boolean>;
 /** 会话行的完整判(不下发,交回承认 / `undefined`):两读之间要再判一次的口(同步导入的提交前复判)与「看不见按自己的形答」的口用。 */
-export declare function judgeSession<T extends OwnedReading>(entry: Entry, store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, reading: T): Promise<Admitted<T> | undefined>;
+export declare function judgeSession<T extends OwnedReading>(entry: Entry, store: PlacementReadingStore | undefined, sessionId: string, reading: T): Promise<Admitted<T> | undefined>;
 /** 这一份承认里的调用方是 fleet 吗(本口 `fleet` 列里的一格成立):fork 新属主「继承源属主」那一支读它。 */
 export declare function admittedAsFleet(entry: Entry, admitted: {
     readonly quals: ReadonlySet<Qual>;
@@ -396,5 +444,182 @@ export declare function entryIsFleet(entry: Entry): boolean;
  * 路由 id 查表得列表面,`owner-faces.ts` 的 `listFilterOf` 从那一行派生(一只读法;trace 列表经 {@link enter} 拿入口后同读它)。
  */
 export declare function routeListFilter<R extends ListRouteId>(req: IncomingMessage, w: Pick<OwnerAccessWiring, "config">, route: R): ListFilter;
+/** run 店上读出带属主行的口(闭集):按 id、按提交幂等键、按会话(最近一条腿)、列表。 */
+export type RunRowReadName = "getRun" | "getRunByIdem" | "latestRunForSession" | "listRuns";
+/** 会话店上按 id 读出带属主行的口(闭集):头读、删除门的头读、委派子代的 placed 位 / 元组。 */
+export type SessionRowReadName = "headOf" | "deletionHeadOf" | "placementOf";
+/**
+ * 封口:这几口在型上调不了 —— 值上原样在。每一口的可缺与否照抄店形(`keyof Pick<T, K>` 同态保留修饰):店必交的读口 ⇒ 必有的 `never`;可缺的读口 ⇒ 可缺的 `never`(读作 `undefined`,
+ * 「在场」仍要能力事实证明:判过在场的见证上那一格是必有的 `never`,交得进要它在场的口)。修饰不能统一写成可缺:必有的方法与可缺的 `never` 相交,TS 把整只交叉型约成 `never`。
+ * 视图是那只店的**子型**:本模块的口与持认领腿的写口收完整的店形,视图交得进去。
+ */
+type ReadsSealed<T, K extends keyof T> = {
+    readonly [P in keyof Pick<T, K>]: never;
+};
+/** 路由层看到的 run 店({@link RunRowReadName} 封着)。 */
+export type RouteRunStore = RunStore & ReadsSealed<RunStore, RunRowReadName>;
+/** 路由层看到的会话店({@link SessionRowReadName} 封着)。 */
+export type RouteSessionStore = OwnerAwareSessionStore & ReadsSealed<OwnerAwareSessionStore, SessionRowReadName>;
+/** 路由层看到的存储后端:铸 run 店 / 会话店的两只工厂封着(路由从后端拿不到一只没封的店;后端的其余面照常)。 */
+export type RouteBackend = StoreBackend & ReadsSealed<StoreBackend, "run" | "session">;
+/**
+ * 🔴 **铸路由层的 deps 视图 —— 全仓唯一的一处**(`route-ctx.ts` 的 `RouteDeps`;值就是服务的那一只 deps,只在型上封住带属主的读口)。
+ * 子型收窄只能在铸点上说一次:之后路由拿到的 run / 会话店读不出带属主的行(编译红),交给本模块的口照读。
+ */
+export declare function sealRouteDeps(deps: FlatServiceDeps): RouteDeps;
+/**
+ * 一条 run **不带属主格**的事实:状态、位置(哪一副本在跑)、所属会话。读者两种 —— 持有会话认领的腿读它持有 / 输给的那一条(认领冲突的 409 材料、
+ * 决定投递的回执幂等、提交流的兜底收场、取消动词会不会结算那张卡),与承认派生的读(承认过的会话上那条在飞 run 的状态;决定口的证明要绑的会话)。
+ * 行不出本模块:要属主或整行就走门 / {@link readVisibleRun}。`undefined` = 没有这一行。
+ */
+export interface RunFacts {
+    readonly status: RunRecord["status"];
+    readonly instanceId: RunRecord["instanceId"];
+    readonly sessionId: string;
+}
+export declare function runFactsOf(store: Pick<RunStore, "getRun">, taskId: string): Promise<RunFacts | undefined>;
+/** 会话最近一条腿的 run id(不交属主;没有腿 ⇒ `undefined`):审批预览与记忆同步的栅栏只要 id —— 要行再经 {@link readVisibleRun} 判。 */
+export declare function latestRunIdOf(store: Pick<RunStore, "latestRunForSession">, sessionId: string): Promise<string | undefined>;
+/** 一只会话**不带属主 / 住客**的事实:叶子(`null` = 空会话)。叶子是惰性读(展开即读会话内容 —— 坏档在这里抛),只要「在不在」的读者不碰它。 */
+export interface SessionFacts {
+    readonly leafId: string | null;
+}
+/**
+ * 会话事实的读口:`undefined` = 没有这只会话。店没有按 id 头读 ⇒ 交回 `undefined`(这台部署读不出,调用方按自己的缺席臂)。
+ * 读者:回退锚的逐轮捕获(两条起跑腿读叶子)、失认领答复的「会话在不在」(不碰叶子)、同步拉取清单的当前叶子。
+ */
+export declare function sessionFactsReadOf(store: Pick<OwnerAwareSessionStore, "headOf"> | undefined): ((sessionId: string) => Promise<SessionFacts | undefined>) | undefined;
+/**
+ * 会话在委派树里的位置(wire 键 `agent` 的值;唯一读口):店的 placed 位一读 → `session-agent.ts` 的 `sessionAgentOf`(元组不带属主)。店不交这一面 ⇒ `undefined`
+ * (这台部署不存元组,不探)。探针抛 ⇒ 原样上抛 —— 读不出怎么说归读者(视图读响亮失败;队列只缺那一行的键并计数),本函数不替任何一面把故障说成「不是子代」。
+ */
+export declare function readSessionAgent(store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string): Promise<SessionAgent | undefined>;
+/**
+ * 会话通知投递之前的住客复核(律在 `session-notify-door.ts` 头注「复核住客」):此刻的住客还是门承认过的那一位吗 —— `same` / `gone`(会话没了)/ `replaced`(换了住客)。
+ * 店没有按 id 头读 ⇒ 交回 `undefined`(调用方先判;门响亮拒)。
+ */
+export declare function occupantRecheckOf(store: Pick<OwnerAwareSessionStore, "headOf"> | undefined): ((sessionId: string, occupant: Pick<SessionHead, "owner" | "incarnation">) => Promise<"same" | "gone" | "replaced">) | undefined;
+/**
+ * 引擎会话规则席的键(律在 `session-rules-seat.ts` 头注):引擎交来的人恰是这只会话属主背后的人 ⇒ 键 = 会话属主;否则原样(没带场景的会话属主与人字节相同)。
+ * 属主只经会话店的头读一处;读不到头(会话不在 / 店不交头读)⇒ 原样。
+ */
+export declare function engineRulesKeyOf(store: Pick<OwnerAwareSessionStore, "headOf"> | undefined, sessionId: string, principal: string | undefined): Promise<string | undefined>;
+/**
+ * 会话最近一条腿的 run 指针(`LatestRunRef`:id + 属主 + 排序键;刻意不是整行 —— 不把结果 blob 拖进按会话的读)经本口的属主门判:看不见 ≡ 没有。
+ * 读者:会话面板的上一腿(面 `run.panel`,看不见 = 不投那个键)。
+ */
+export declare function readVisibleLatestRun(entry: Entry, store: Pick<RunStore, "latestRunForSession">, sessionId: string): Promise<LatestRunRef | undefined>;
+/** run 列表的属主过滤参数(一只派生,读与游标指纹同读):视域钉住一位主体 ⇒ 强制那一位(调用方点名的 `owner` 不算);不钉人(fleet)⇒ 点名的照用(运维视图)。 */
+export declare function runListOwnerOf(filter: ListFilter, named: string | undefined): string | undefined;
+/** run 列表的读口(列表面 `list.read`):过滤参数由 {@link runListOwnerOf} 从视域派生,只在这里落成店的过滤参数。 */
+export declare function listVisibleRuns(store: Pick<RunStore, "listRuns">, filter: ListFilter, named: string | undefined, query: Omit<RunListQuery, "owner">): Promise<RunRecord[]>;
+/** 审批 / 助手面按停驻 scope 列 run:属主过滤 = scope 的属主键(公共 scope `_` ⇒ 属主为 null 的 run,主体 ⇒ 恰它的;`security.ts` 的唯一编解码),只在这里落成店的过滤参数。 */
+export declare function listRunsOfScope(store: Pick<RunStore, "listRuns">, scope: string, limit: number): Promise<RunRecord[]>;
+/** 一把提交钥匙命中的行对这位调用方算什么:`visible` = 读得到的那一行;`occupied` = 有行但不是这次提交拿得到的(看不见 / 自带 taskId 而键指着别的行)—— 回执 409,不回显那一行。 */
+export type ReplayHit = {
+    readonly kind: "visible";
+    readonly row: RunRecord;
+} | {
+    readonly kind: "occupied";
+};
+/** 提交重放的判(纯):命中的行(进门按钥匙读到的 / 建行撞唯一键时观察到的)对这位提交者(认领面的调用方 `claimCallerOf`:不放 fleet、不放运维)算什么。 */
+export declare function replayHitOf(subject: Subject | undefined, config: DeploymentShapeInput<"principal">, row: RunRecord, clientTaskId: string | undefined): ReplayHit;
+/** 提交重放读:按一把钥匙读行(`Idempotency-Key` 铸的键,或调用方自铸的 `body.taskId`)并判;没有命中 ⇒ `undefined`(这是一次新提交)。 */
+export declare function readReplayHit(subject: Subject | undefined, config: DeploymentShapeInput<"principal">, store: Pick<RunStore, "getRun" | "getRunByIdem">, key: {
+    readonly idemKey: string;
+} | {
+    readonly taskId: string;
+}, clientTaskId: string | undefined): Promise<ReplayHit | undefined>;
+/** 会话视图读(`sessionAudit`:存档读出的视图 + 头读的属主)。 */
+type SessionViewRead = NonNullable<FlatServiceDeps["sessionAudit"]>;
+/**
+ * 读**会话视图**的三口(`GET /v1/sessions/:id` / `…/memory-status` / `…/memory/erase`)的「归属 + 读存档」**唯一**一段([ref];律在 `routes/sessions.ts` 的调用点注):
+ * 会话店有头读 ⇒ 先判归属(门同 head / fork / sync 各口),非属主拿到的应答与「属主的会话完好」时逐字相同;只接了视图面 ⇒ 视图只能先读,读失败时归属还没判出来 ⇒
+ * 换成一只不带码的错上抛。视图读完之后再判一次同一只(两读之间换主 ⇒ 按新主拒;读后会话消失 ⇒ 没有这一行)。交回视图,`undefined` = 已应答。
+ */
+export declare function admitSessionView(entry: Entry, res: ServerResponse, store: Pick<OwnerAwareSessionStore, "headOf" | "placementOf"> | undefined, sessionAudit: SessionViewRead, sessionId: string, readOpts?: SessionAuditReadOpts): Promise<({
+    owner: string | null;
+} & Record<string, unknown>) | undefined>;
+/** 同步族的门读结果:活行的住客(拉取只认它)、占着这个 id 的那一位(活行 ∪ 在删行)、这位调用方碰不碰得了占着的那一行(面 `session.own`)。 */
+export interface SyncGateReading {
+    readonly face: SessionFace | undefined;
+    readonly occupant: SessionFace | undefined;
+    readonly mayTouch: boolean;
+}
+/**
+ * 同步族(拉取 / 推送 / 干跑 / 导入第二阶段)的门读 —— 一只判据、两个时刻(律在 `routes/session-sync.ts` 的门注):会话店的头读投成活住客;「这个 id 被占着吗」只有
+ * 一种读法,与认领面同一只 `deletionHeadReadOf`(活行 ∪ 在删行:在删的行对活行读法是「不在」,但它仍占着这个 id);占着的那一行准不准这位调用方碰 = 面表 `session.own`。
+ */
+export declare function readSyncGate(entry: Entry, store: DeletionGateStore, sessionId: string): Promise<SyncGateReading>;
+/** 工具结果店的出处读口(core `ToolResultStore.ownerOf`:这枚 ref 写下时声明的会话 / task)。 */
+export interface ToolResultProvenanceReader {
+    ownerOf?(ref: string): Promise<{
+        readonly sessionId: string;
+        readonly taskId?: string;
+    } | undefined> | {
+        readonly sessionId: string;
+        readonly taskId?: string;
+    } | undefined;
+}
+/**
+ * 一枚工具结果 ref 属于这条**已承认**的 run 吗(律在 `routes/trace-usage.ts` 的 ②-a 段):店记着的出处是这条 run 的会话,且出处若点名了 task 则必须是这条。
+ * 店不交出处 / 出处缺席 ⇒ 判不过(fail-closed:读面对没有出处的 ref 一律 404)。
+ */
+export declare function toolResultRefOwned(store: ToolResultProvenanceReader | undefined, ref: string, run: Pick<RunRecord, "sessionId" | "taskId">): Promise<boolean>;
+/**
+ * leader 登记表的请求口读(协议面 `run.leader`;`GET /v1/leader/:id` 与取消口,含取消口 CAS 输之后的重读):按 id 读一行,按交来的可见判
+ * (boot 装的 `seesRunAs("run.leader")`)判,看不见 ≡ 没有。驱动腿与旗读拍读本副本自己在驱动的行,不经这里。
+ */
+export declare function readVisibleLeaderRow<R extends {
+    readonly owner: string | null;
+}>(store: {
+    getRun(id: string): Promise<R | undefined>;
+}, id: string, visible: (owner: string | null) => boolean): Promise<R | undefined>;
+/** 工作流按 id 四口的会话断言(受理相;`label` = 发过的日志字段 `face`;判法与 run 面同一只 {@link sessionAsserted})。列表口不判(摘要没有那一格)。 */
+export declare const WORKFLOW_SESSION_ASSERTION: {
+    readonly "workflow-detail": {
+        readonly phase: "accept";
+        readonly label: "workflow.detail";
+    };
+    readonly "workflow-journal": {
+        readonly phase: "accept";
+        readonly label: "workflow.journal";
+    };
+    readonly "workflow-stream": {
+        readonly phase: "accept";
+        readonly label: "workflow.stream";
+    };
+    readonly "workflow-agent-steer": {
+        readonly phase: "accept";
+        readonly label: "workflow.agent-steer";
+    };
+};
+/** 工作流行的承认:门放过的那一行 + 调用方(换成引擎身份之后)对它持有的全部资格。 */
+export interface WorkflowAdmission {
+    readonly row: WorkflowRun;
+    readonly quals: ReadonlySet<Qual>;
+}
+/** 工作流门的一次判(不下发):承认,或拒因(没有 / 前门 / 看不见 / 会话断言不符)。 */
+export type WorkflowVerdict = WorkflowAdmission | "missing" | "door" | "not_visible" | "session_mismatch";
+/**
+ * 工作流列表(`GET /v1/workflows`)—— 属主过滤只在这里落成店参数:调用方换成它的引擎身份(与 {@link judgeWorkflowRun} 同一只换算),店按 `scope` 列筛。
+ * 面表 `workflow.read` 只给属主(不放 fleet / 运维)⇒ 列表 = 调用方自己那一格的行。
+ */
+export declare function listVisibleWorkflows(entry: Entry, store: Pick<WorkflowRunStore, "listByScope">, opts: Parameters<WorkflowRunStore["listByScope"]>[1]): ReturnType<WorkflowRunStore["listByScope"]>;
+/**
+ * 🔴 **工作流行的判(唯一一处;[ref] 第二阶段)**:按 id 读一行(店的 `get`,不带 scope —— 修前是 core 按 scope 读 + 路由再比一次 scope,两读答同一问),
+ * 行格 = `scope` 列的属主键(引擎写下的引擎身份,恒有主);调用方一侧换成它的引擎身份(`engine-identity.ts` 的 `engineScopeOf`:引擎按它写 scope ——
+ * 带场景的请求是那个人,匿名是 `"default"`)再过事实函数 {@link qualsOf} + 面表;前门按这次请求的调用方判。承认之后按 {@link WORKFLOW_SESSION_ASSERTION} 判会话断言。
+ */
+export declare function judgeWorkflowRun(entry: Entry, store: Pick<WorkflowRunStore, "get">, runId: string): Promise<WorkflowVerdict>;
+/** 工作流按 id 读面的门:没有 / 看不见 / 会话断言不符同一只投影(`workflow_missing`),前门经它的下发口。交回承认或 `undefined`(已应答)。 */
+export declare function admitWorkflowRun(entry: Entry, res: ServerResponse, store: Pick<WorkflowRunStore, "get">, runId: string): Promise<WorkflowAdmission | undefined>;
+/** 删除门读的会话店:头读在场(能力事实 `sessionDelete` 的见证)+ 店可交的删除门头读与 placed 位问询。 */
+export type DeletionGateStore = SessionGateStore & Pick<OwnerAwareSessionStore, "deletionHeadOf">;
+/**
+ * 会话删除门(`DELETE /v1/sessions/:id`):读的头是删除门那一只(`session-incarnation.ts` 的 `deletionHeadReadOf`:local 店删到一半的行 —— 读者早已读作不在 —— 也答得出
+ * 开始删它的那位属主:那位重发收得完,别人得到与「不在」同一句;别的店 = `headOf`,与协调器围栏读同一只),行格的 placed 位问询 = 店自己的那一只(绑好宿主)。其余同 {@link admitSessionById}。
+ */
+export declare function admitSessionForDeletion(entry: Entry, res: ServerResponse, store: DeletionGateStore, sessionId: string): Promise<Admitted<SessionHead> | undefined>;
 export {};
 //# sourceMappingURL=owner-access.d.ts.map

package/dist/http/owner-access.js

@@ -1,20 +1,23 @@
 import { createLogger } from "../observability/logger.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
-import { FACES, fleetOn, listFilterOf, ownerCellOf, qualsOf, visibleOn } from "../owner-faces.js";
+import { engineScopeOf } from "../engine-identity.js";
+import { sameOccupant } from "../execution-placement.js";
+import { sessionAgentOf } from "../session-agent.js";
+import { deletionHeadReadOf, sessionFaceOfHead } from "../session-incarnation.js";
+import { FACES, fleetOn, listFilterOf, ownerCellOf, qualsOf, recoveredSubject, visibleOn } from "../owner-faces.js";
 import { mintOwnedRow, partsOf, personOf, subjectOf } from "../owner-brands.js";
-import { sessionCellFor } from "../security.js";
+import { claimCallerOf, ownerOfCheckpointScope, sessionCellFor } from "../security.js";
 import { openFaceFaultWire, SessionOwnerUnreadableError } from "../session-error-wire.js";
 import { seatText } from "../trace/exit-seat.js";
-import { actsForDeployment, devOpenDeployment, explicitOperatorOk, gatedSubject, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented } from "./principal-gate.js";
+import { actsForDeployment, explicitOperatorOk, gatedSubject, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented } from "./principal-gate.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage, SESSION_NOT_FOUND_MESSAGE } from "./route-ctx.js";
 import { sendError, sendJson } from "./send.js";
 export function callerOf(req, w) {
     const subject = gatedSubject(req, w.config);
-    const fleet = devOpenDeployment(w.config) ? "dev_open" : actsForDeployment(req, w.config, () => subject) ? "deployment_token" : undefined;
     return {
         subject,
         operator: explicitOperatorOk(subject === undefined ? undefined : personOf(subject), w.config),
-        fleet,
+        fleet: actsForDeployment(req, w.config, () => subject),
         traceRead: traceTokenPresented(req, w.config),
         principalRequired: DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(w.config),
         multiTenant: DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(w.config),
@@ -97,6 +100,11 @@ export const ROUTE_FACES = {
     "assistant-task-preempt": "run.preempt",
     "assistant-task-resume": "run.resume",
     "assistant-task-plan-review": "run.decision",
+    "workflows-list": "workflow.read",
+    "workflow-detail": "workflow.read",
+    "workflow-journal": "workflow.read",
+    "workflow-stream": "workflow.read",
+    "workflow-agent-steer": "workflow.steer",
     "sessions-list": "session.list",
     "sendfile-links": "list.read",
     "fleet-stream": "list.read",
@@ -277,6 +285,9 @@ export function refuse(entry, res, reason, id) {
         case "deleted_false":
             sendJson(res, 200, { deleted: false });
             return;
+        case "workflow_missing":
+            sendError(res, 404, "not_found.workflow", "workflow not found");
+            return;
         case "run_exists":
         case "attach_absent":
         case "omit":
@@ -291,8 +302,10 @@ function rowRead(reading) {
     return reading !== undefined && reading !== null;
 }
 function verdictOn(entry, cell) {
+    return verdictOnQuals(entry, qualsOf(entry.caller, cell));
+}
+function verdictOnQuals(entry, quals) {
     const face = FACES[entry.face];
-    const quals = qualsOf(entry.caller, cell);
     if (face.operator && quals.has("operator"))
         return quals;
     if (doorRefusal(face, entry.face, entry.caller) !== undefined)
@@ -326,14 +339,23 @@ export async function admitRunRow(entry, res, runStore, row, id) {
         refuse(entry, res, "session_mismatch", id);
         return undefined;
     }
+    return observedAdmission(entry, runStore, admitted);
+}
+async function observedAdmission(entry, runStore, admitted) {
     return { ...admitted, row: mintOwnedRow(await runRowAt(entry.mouth, runStore, admitted.row)) };
 }
 export async function admitRunById(entry, res, runStore, taskId) {
     return admitRunRow(entry, res, runStore, await runStore.getRun(taskId), taskId);
 }
+export async function admitRunByIdem(entry, res, runStore, idemKey) {
+    return admitRunRow(entry, res, runStore, await runStore.getRunByIdem(idemKey));
+}
 export async function readVisibleRun(entry, runStore, taskId) {
     const row = await runStore.getRun(taskId);
-    return rowRead(row) && seesRun(entry, row.owner) ? runRowAt(entry.mouth, runStore, row) : undefined;
+    if (!rowRead(row))
+        return undefined;
+    const admitted = judgeRun(entry, row);
+    return admitted === undefined ? undefined : observedAdmission(entry, runStore, admitted);
 }
 export function seesRun(entry, owner) {
     const verdict = verdictOn(entry, ownerCellOf(owner));
@@ -372,9 +394,25 @@ export async function admitSessionRow(entry, res, store, sessionId, reading) {
 export async function judgeSessionRow(entry, store, sessionId, reading) {
     return judge(entry, reading, await sessionCellFor(entry.face, entry.caller, store, sessionId, reading.owner));
 }
+export async function judgeSessionById(entry, store, sessionId) {
+    const head = await readOwnerCell(entry, sessionId, () => store.headOf(sessionId));
+    return sessionRowPresent(head) ? judgeSessionRow(entry, store, sessionId, head) : undefined;
+}
 export async function admitSessionById(entry, res, store, sessionId) {
+    const verdict = await judgeSessionById(entry, store, sessionId);
+    if (verdict === undefined) {
+        refuse(entry, res, "missing");
+        return undefined;
+    }
+    return deliverVerdict(entry, res, verdict);
+}
+export async function readVisibleSession(entry, store, sessionId) {
+    const verdict = await judgeSessionById(entry, store, sessionId);
+    return verdict === undefined || verdict === "door" || verdict === "not_visible" ? undefined : verdict;
+}
+export async function sessionOwnerUnchanged(entry, store, sessionId, admittedOwner) {
     const head = await readOwnerCell(entry, sessionId, () => store.headOf(sessionId));
-    return admitSessionRow(entry, res, store, sessionId, head);
+    return sessionRowPresent(head) && head.owner === admittedOwner;
 }
 export async function judgeSession(entry, store, sessionId, reading) {
     if (!sessionRowPresent(reading))
@@ -391,4 +429,144 @@ export function entryIsFleet(entry) {
 export function routeListFilter(req, w, route) {
     return listFilterOf(faceOfRoute(route), callerOf(req, w));
 }
+export function sealRouteDeps(deps) {
+    return deps;
+}
+export async function runFactsOf(store, taskId) {
+    const row = await store.getRun(taskId);
+    return rowRead(row) ? { status: row.status, instanceId: row.instanceId, sessionId: row.sessionId } : undefined;
+}
+export async function latestRunIdOf(store, sessionId) {
+    return (await store.latestRunForSession(sessionId))?.taskId;
+}
+export function sessionFactsReadOf(store) {
+    const headOf = store?.headOf;
+    if (typeof headOf !== "function")
+        return undefined;
+    return async (sessionId) => {
+        const head = await headOf.call(store, sessionId);
+        return rowRead(head) ? { get leafId() { return head.leafId; } } : undefined;
+    };
+}
+export async function readSessionAgent(store, sessionId) {
+    const placementOf = store?.placementOf;
+    if (placementOf === undefined)
+        return undefined;
+    return sessionAgentOf(await placementOf.call(store, sessionId));
+}
+export function occupantRecheckOf(store) {
+    const headOf = store?.headOf;
+    if (typeof headOf !== "function")
+        return undefined;
+    return async (sessionId, occupant) => {
+        const head = await headOf.call(store, sessionId);
+        if (!rowRead(head))
+            return "gone";
+        return sameOccupant(occupant, head) ? "same" : "replaced";
+    };
+}
+export async function engineRulesKeyOf(store, sessionId, principal) {
+    if (principal === undefined || typeof store?.headOf !== "function")
+        return principal;
+    const owner = (await store.headOf(sessionId))?.owner;
+    if (owner === undefined || owner === null)
+        return principal;
+    return personOf(recoveredSubject(owner)) === principal ? owner : principal;
+}
+export async function readVisibleLatestRun(entry, store, sessionId) {
+    const latest = await store.latestRunForSession(sessionId);
+    return rowRead(latest) && seesRun(entry, latest.owner) ? latest : undefined;
+}
+export function runListOwnerOf(filter, named) {
+    return filter.gateOwner ?? named;
+}
+export function listVisibleRuns(store, filter, named, query) {
+    const owner = runListOwnerOf(filter, named);
+    return store.listRuns({ ...query, ...(owner ? { owner } : {}) });
+}
+export function listRunsOfScope(store, scope, limit) {
+    return store.listRuns({ owner: ownerOfCheckpointScope(scope), limit });
+}
+export function replayHitOf(subject, config, row, clientTaskId) {
+    const sameRun = clientTaskId === undefined || clientTaskId === row.taskId;
+    return sameRun && seesRunAs("run.replay", claimCallerOf(subject, config), row.owner) ? { kind: "visible", row } : { kind: "occupied" };
+}
+export async function readReplayHit(subject, config, store, key, clientTaskId) {
+    const row = "idemKey" in key ? await store.getRunByIdem(key.idemKey) : await store.getRun(key.taskId);
+    return rowRead(row) ? replayHitOf(subject, config, row, clientTaskId) : undefined;
+}
+export async function admitSessionView(entry, res, store, sessionAudit, sessionId, readOpts) {
+    const gated = store !== undefined && typeof store.headOf === "function";
+    if (gated && (await admitSessionById(entry, res, store, sessionId)) === undefined)
+        return undefined;
+    let audit;
+    try {
+        audit = await sessionAudit(sessionId, readOpts);
+    }
+    catch (e) {
+        if (gated)
+            throw e;
+        throw new Error(`session view read failed before ownership could be established: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    if ((await admitSessionRow(entry, res, store, sessionId, audit)) === undefined)
+        return undefined;
+    return audit;
+}
+export async function readSyncGate(entry, store, sessionId) {
+    const live = await store.headOf(sessionId);
+    const face = rowRead(live) ? sessionFaceOfHead(sessionId, live) : undefined;
+    const held = face === undefined ? await deletionHeadReadOf(store)(sessionId) : undefined;
+    const occupant = face ?? (rowRead(held) ? sessionFaceOfHead(sessionId, held) : undefined);
+    const mayTouch = occupant !== undefined && (await judgeSession(entry, store, sessionId, occupant)) !== undefined;
+    return { face, occupant, mayTouch };
+}
+export async function toolResultRefOwned(store, ref, run) {
+    const provenance = store?.ownerOf ? await store.ownerOf(ref) : undefined;
+    return provenance !== undefined && provenance.sessionId === run.sessionId && (provenance.taskId === undefined || provenance.taskId === run.taskId);
+}
+export async function readVisibleLeaderRow(store, id, visible) {
+    const row = await store.getRun(id);
+    return row !== undefined && visible(row.owner) ? row : undefined;
+}
+export const WORKFLOW_SESSION_ASSERTION = {
+    "workflow-detail": { phase: "accept", label: "workflow.detail" },
+    "workflow-journal": { phase: "accept", label: "workflow.journal" },
+    "workflow-stream": { phase: "accept", label: "workflow.stream" },
+    "workflow-agent-steer": { phase: "accept", label: "workflow.agent-steer" },
+};
+export function listVisibleWorkflows(entry, store, opts) {
+    return store.listByScope(engineScopeOf(entry.caller.subject), opts);
+}
+export async function judgeWorkflowRun(entry, store, runId) {
+    const row = await store.get(runId);
+    if (!rowRead(row))
+        return "missing";
+    const engineCaller = { ...entry.caller, subject: recoveredSubject(engineScopeOf(entry.caller.subject)) };
+    const verdict = verdictOnQuals(entry, qualsOf(engineCaller, ownerCellOf(row.scope)));
+    if (verdict === "door" || verdict === "not_visible")
+        return verdict;
+    const rule = Object.hasOwn(WORKFLOW_SESSION_ASSERTION, entry.mouth) ? WORKFLOW_SESSION_ASSERTION[entry.mouth] : undefined;
+    if (rule === undefined)
+        throw new Error(`owner access: mouth ${entry.mouth} judges a workflow row but is not registered in WORKFLOW_SESSION_ASSERTION`);
+    return sessionAsserted(rule, entry.req, row.originatingSessionId, verdict.has("operator")) ? { row, quals: verdict } : "session_mismatch";
+}
+export async function admitWorkflowRun(entry, res, store, runId) {
+    const verdict = await judgeWorkflowRun(entry, store, runId);
+    switch (verdict) {
+        case "missing":
+        case "not_visible":
+        case "session_mismatch":
+            refuse(entry, res, verdict);
+            return undefined;
+        case "door":
+            sendDoorRefusal(entry, res, doorRefusal(FACES[entry.face], entry.face, entry.caller));
+            return undefined;
+        default:
+            return verdict;
+    }
+}
+export async function admitSessionForDeletion(entry, res, store, sessionId) {
+    const placementOf = store.placementOf?.bind(store);
+    return admitSessionById(entry, res, { headOf: deletionHeadReadOf(store), ...(placementOf !== undefined ? { placementOf } : {}) }, sessionId);
+}
 //# sourceMappingURL=owner-access.js.map