@sema-agent/server 7.147.0 → 7.148.0

package/dist/security.d.ts

@@ -1,15 +1,23 @@
 import type { IncomingMessage } from "node:http";
 import { type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+import type { Logger } from "./observability/logger.js";
 import { type DeploymentShapeInput } from "./deployment-shape.js";
+import { type Caller, type FaceId } from "./owner-faces.js";
+import { type DurableOwnerKey, type Person, type Subject, type SubjectParts } from "./owner-brands.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
+import type { SessionDeletionFace } from "./session-deletion.js";
+import { type SessionBirth } from "./session-incarnation.js";
 import type { ClientSessionRowWrite, ReplaySessionRowWrite, ReplaySessionRowWriteOutcome, SessionRowAnswer, SessionRowPatch, SessionRowWriteOutcome } from "./session-row.js";
 import type { ExecutionPlacementSeat } from "./execution-placement.js";
 import type { SessionUnreadable } from "./session-error-wire.js";
 import type { ForkPlacement, ForkTarget, ForkToOutcome } from "./plugins/session-fork.js";
+import { type SessionWithdrawFace } from "./plugins/session-birth.js";
+import type { LocalSessionDeletionSection } from "./session-erase.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
- *  output (§0.5). Mirrors {@link RunStore}'s shipped `SessionSummary` shape so the wire response is unchanged. */
+ *  output (§0.5); same shape as `SessionSummary` in `plugins/store-contracts.ts`. `objectivePreview` = the most recent run whose preview
+ *  column is a non-empty string (the column `GET /v1/tasks` reads; injected blocks stripped, redacted, cut to 120 at write), else `null`. */
 export interface SessionListItem {
     sessionId: string;
     owner: string | null;
@@ -44,6 +52,10 @@ export interface SessionListItem {
      *  A store whose head leaf is a row column (the SQL twins) never carries it. Additive key, passed through unprojected (`sessions-list.ts`).
      *  Same name and meaning as `SessionSummary.unreadable` in `plugins/store-contracts.ts`. */
     unreadable?: SessionUnreadable;
+    /** Fork lineage: the id of the session this one was forked from (core's `SessionMetadata.forkedFrom`, the same word) — present-iff the row was created
+     *  by a fork after lineage was recorded (an older fork is not backfilled: its source is unknown). OMIT-when-absent, never `null`. Additive key, passed
+     *  through unprojected (`sessions-list.ts`). Same name and meaning as `SessionSummary.forkedFrom` in `plugins/store-contracts.ts`. */
+    forkedFrom?: string;
 }
 /**
  * 会话店的行格写原语(规则与判序:`session-row.ts` 头注「写原语」)—— 按入口分两只重载:客户端写(PATCH)的结局闭集四员;行重放(2c 导入落定后的那一笔)
@@ -63,7 +75,7 @@ export interface SessionRowCellsWriter {
  * 而 `DELETE /v1/sessions/:id`(删整条会话)不在其中 —— 同一风险形、爆炸半径**更大**,却没门。
  *
  * 风险形逐字同源(守卫自己的注释):「无 service token + 未开 `ALLOW_UNAUTHED_WRITES`」这一形下
- * fleet 写档(`http/principal-gate.ts` 的 `fleetViewOf`,dev-open 臂)判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
+ * fleet 写档(面表 fleet 列的 `dev_open` 格,`owner-faces.ts` 的 `listFilterOf`)判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
  * policy 腿担心的是「forged principal 能 tighten/DoS 一个会话的工具」;DELETE 直接把会话删掉。
  *
  * ⇒ 枚举改**族判定**:新增一条破坏性会话路由时自动落进门内,不必记得回来加白名单。
@@ -73,26 +85,6 @@ export interface SessionRowCellsWriter {
  * 不含读面,也不含 `POST /v1/tasks` 那条提交腿 —— 它有自己的同族门(别重复拦,双拦会让错误归因变糊)。
  */
 export declare function isDestructiveSessionWrite(method: string, url: string): boolean;
-declare const principalBrand: unique symbol;
-declare const durableOwnerKeyBrand: unique symbol;
-/**
- * 🔴 **两个 owner 不是同一个东西**([ref] RH-3,类型事实):
- *  · {@link Principal} —— **这次请求**验过的调用方身份。铸点闭集:`http/principal-gate.ts` 的 `gatedPrincipal`(验身份的那一只),以及属主存取器
- *    (`http/owner-access.ts`)里一只「上游已验」的适配口(调用方身份经一只纯串结构转手过来的腿 —— 第二期随那只结构带品牌而删);
- *  · {@link DurableOwnerKey} —— **行上 / 存储键里**落下的属主(run 行、会话行的 `owner` 列)。铸点闭集:属主存取器读行处与 {@link sessionOwnerCellOf}。
- * 两者互不可赋、裸 `string` 两者都不可赋;「这个调用方读得到这一行吗」的判官(`runOwnerReadable`)签名两参各带一个品牌,对调即编译红。
- * 铸点按文件计数钉在 `test/owner-gate-single-owner.test.ts` 的品牌铸点普查格里:多一处铸点 = 门红。
- */
-export type Principal = string & {
-    readonly [principalBrand]: true;
-};
-export type DurableOwnerKey = string & {
-    readonly [durableOwnerKeyBrand]: true;
-};
-/** {@link Principal} 的铸造口(只在铸点闭集里调,见上)。 */
-export declare function mintPrincipal(verified: string): Principal;
-/** {@link DurableOwnerKey} 的铸造口(只在铸点闭集里调,见上)。 */
-export declare function mintDurableOwnerKey(persisted: string): DurableOwnerKey;
 /**
  * 会话行属主门读的那一格([ref]):有主的行只有属主;**无主的行**另带「它是不是委派子代的 placed 行」(店的 `placementOf` 答,{@link sessionOwnerCellOf} 读;
  * 不实现 placement 的店没有 placed 行)。`placed` 只在无主时存在 —— 有主的行属主门不看它。
@@ -103,93 +95,33 @@ export type SessionOwnerCell = {
     readonly owner: null;
     readonly placed: boolean;
 };
-/** 会话行属主门的调用方:验过的主体(`gatedPrincipal`)+ 它是不是 **fleet 调用方**(dev-open 部署上的任何调用方,或出示了这台部署的 service 凭据、
- *  不报主体的调用方 —— 除非部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false`)。唯一铸点 `http/principal-gate.ts` 的 `sessionCallerOf`。 */
-export interface SessionCaller {
-    readonly principal: Principal | undefined;
-    readonly fleet: boolean;
-}
 /**
- * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**([ref] 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除 / 同步族的存量互认臂 {@link legacyUnownedSessionOk}、
- * 审批豁免面、notify 面的无主臂都经它,不各写一份):
- *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
- *  · 无主的 **placed** 行(委派子代:属主 = 引擎判的委派树属主,三只持久会话店建行那一笔原样记 `placement.owner`,`null` = 根匿名;`delegated-session-owner.ts` 头注)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
- *    或出示了 service 凭据、不报主体的调用方 —— 只配 token 的单用户部署、BFF 的系统调用;部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时后者不是 fleet)。
- *    任何具名主体(含经 BFF 代发的)与无身份调用方(没有 service 凭据的;声明形上不报主体的 service 凭据)都不成立:
- *    这一行要么属于一棵无身份调用方的树(引擎交的属主是 `null`),要么是属主从没被记下的行 —— 7.144.0 之前写下的存量(7.132.x 及更早建行不记属主;7.133.0–7.143.x 按本服务当年的推断写下,
- *    推断那一刻来源还没有属主的仍无主;SQL 两店由一次性迁移 M23 在它的窗内回填),以及 local 文件店上 7.144.x 及更早建行两笔之间崩溃留下的行(7.145.0 起建行格先、存档后,不再新生)、
- *    同一数据根上 run-local 腿经 core 店写下的 placed 存档(local 没有回填臂)
- *    —— 后者把它当公共行,就是把别人那棵树的子代转录交给拿到 id 的人。
- *  · 有主的行 ⇒ 不在本臂。
+ * 只按「验过的主体 + 部署两格」判的调用方:提交挂接(认领面 `session.attach`,主体 = 提交管线的 `verifiedSubject`)、提交重放与 leader 登记表(主体 = 幂等身份
+ * `IdemCaller.subject`,同一只验身份的读数)、peer 目录席(列表面 `session.list`;主体 = 引擎交来的 scope 经 `partsOf` 恢复)。这几口的面不放运维、不放 fleet(面表那几行 `operator: false`、`fleet: []`,
+ * 结构钉在 `test/owner-access.test.ts`;peer 目录是引擎侧的席,不是 fleet 调用方)⇒ 这两格在这里恒缺,不读请求的 fleet 事实。主体已带品牌进来,这里不铸。
+ * `Caller` 铸点之一(另两只在 `http/owner-access.ts`:`callerOf` / `callerOfDecision`)。
  */
-export declare function ownerlessRowOpen(cell: SessionOwnerCell, caller: SessionCaller): boolean;
-/** 读一只会话行的 {@link SessionOwnerCell}:无主时问一次店的 `placementOf`(既有读口;店不交它 = 不实现 placement = 没有 placed 行)。`owner` = 调用点那一读。 */
+export declare function claimCallerOf(subject: Subject | undefined, config: DeploymentShapeInput<"principal">): Caller;
+/** 提交挂接「没有这只会话」那一答的句子(requireExisting 缺行与认领面看不见同一句;投影 `attach_absent`)。 */
+export declare const ATTACH_ABSENT_MESSAGE = "requireExistingSession: session does not exist (resume.session_not_found)";
+/** 读一只会话行的 {@link SessionOwnerCell}:有主行 = 属主那一格(`owner-faces.ts` 的 `ownerCellOf`,属主列读数的唯一铸法);无主时问一次店的 `placementOf`
+ *  (既有读口;店不交它 = 不实现 placement = 没有 placed 行)。`owner` = 调用点那一读。 */
 export declare function sessionOwnerCellOf(store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, owner: string | null): Promise<SessionOwnerCell>;
-/** [ref] 窄互认第二臂的租户键字面量 —— 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的那一个,
- *  也是壳 [ref]G1 翻面后随请求带的那一个。**不是哨兵**([ref] 措辞):它是单机形的真租户键。 */
-export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
-/**
- * [ref] 窄互认**第二臂**(clay 裁 A / [ref] 下达;cli [ref] 表态即发)—— `legacyShellOwner`
- * (本文件 createAuthorizer 内 + http/server.ts `runOwnerOk`)的对称孪生。
- *
- * 病灶:7.8.0 第一臂承接的是 `owner === "anon:shell-live"` 哨兵行;此后壳把无主表示法归一为
- * **缺席**,于是 1.0.82 及更早留下的存量会话 owner 列是 **null**。壳 1.0.83 起随请求带
- * `default` 主([ref] G1 闸口),`null !== "default"` ⇒ 存量会话在 session 面
- * **列表不出现 / fork 404 / delete 静默 {deleted:false} / workspace 404**(三面矩阵 [ref] 面3;
- * fleet 面与 run 读面天然连续,面1/面2 零施工)。
- *
- * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
- *   ① 单机形(部署形表行 `multiTenant` 不成立)—— 多租部署本臂**死路**(header 必到、键必具名);
- *   ② 存量行恰为无主 `owner === null`、且不是委派子代的 placed 行(无主臂的唯一判据 {@link ownerlessRowOpen})—— 任何具名 owner 的行不受影响;
- *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
- * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租外泄。
- *
- * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
- * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
- *
- * ── 同步族(`…/sync/*`:拉取 / 推送 / 开导入 / 导入第二阶段)──────────────────────────────────
- *  同步族四口自 7.134.0 同走本臂(表态见 7.134.0 发车帖;三条件不变):属主门是 `http/routes/session-sync.ts` 的一只布尔 `mayTouch`,与 fork / 删除同一只谓词、同一对读法
- *  (`sessionCallerOf` + `sessionOwnerCellOf`),不另立判据。这一族带破坏性的 import 腿,但单用户形下 `default` 是唯一用户,与已走本臂的删除同级,没有新增跨租风险;
- *  多租形、非 `default` 主体、无主的 placed 行仍与不存在的会话同码同体。暂存句柄的归属不因本臂放宽(非 fleet 调用方只推自己开的暂存,fleet 调用方照旧可推任何一张)。
- *
- * ── 逐面判过、**刻意不放行**的两处(免得后人当遗漏再补一次)────────────────────────────────
- *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
- *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[ref] 帖文里「单读 404」一句
- *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
- *  · `GET|PUT /v1/sessions/:id/policy` 的 `owner === null ⇒ 409 conflict.session_ownerless`:那是**有意的
- *    fail-closed** —— 规则按「会话 × principal」存、按 run 的 principal 读,而规则路由的存储键就是会话的属主;无主会话没有
- *    这把键,替它读写规则只能**猜**一个 principal(猜错 = 200 说已生效,其实没有哪条 run 读它)。已经存下的规则不受影响:
- *    它们存在当初那个属主的键下,那个 principal 的 run 照读照生效(7.119.0 前 local 后端重启即把属主忘掉,于是那些规则
- *    在跑、却读不到也删不掉 —— 修在属主落盘,不在放宽本门)。放宽它等于制造一条 fail-open,不在本臂辖域。
- *
- * @param deployment 部署形(条件①;读表行 `multiTenant`)
- * @param caller 调用方(条件③ 读它验过的主体;fleet-wide 面不经本臂)
- * @param cell 存量行那一格(条件②:无主,且经无主臂的唯一判据 {@link ownerlessRowOpen} —— 无主的委派子代 placed 行不在本臂,[ref])
- */
-export declare function legacyUnownedSessionOk(deployment: DeploymentShapeInput<"principal">, caller: SessionCaller, cell: SessionOwnerCell): boolean;
 /**
- * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
- *
- * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
- * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
- * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
- * 单实体读/写点(fork/delete/同步族/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
+ * 🔴 **一只会话行在这一口上的行格**(会话面的门与认领门同读这一只):有主行就是属主;无主行的 placed 位按 `owner-faces.ts` 的 `ownerlessCellWithoutRead`
+ * 只在两种假设不都放行时问店;问了、而这只会话的存档读不出({@link archiveUnreadable})⇒ 按面表本口的 `placementUnreadable` 列:`ordinary` 读作普通无主行,
+ * `raise` 原故障上抛;别的读故障(店连接类等)一律上抛,各口按店故障的码族答。
  */
-export declare function legacyUnownedAmnestyOpen(deployment: DeploymentShapeInput<"principal">, gateOwner: string | null): boolean;
-/** [ref] 存量哨兵窄互认的行属主字面量 —— cli ≤1.0.70 在本地单用户模式自发的 principal 头,存量会话的属主列就是它(引擎不发明这个字面量)。 */
-export declare const LEGACY_SHELL_SENTINEL_OWNER = "anon:shell-live";
+export declare function sessionCellFor(face: FaceId, caller: Caller, store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, owner: string | null): Promise<SessionOwnerCell>;
 /**
- * 🔴 **会话属主等价律 —— 「行上记下的属主」与「这一次的调用方 / 住客」是不是同一位,唯一判官**(两只窄互认臂收在这一处,读者不各写一份):
- *  · 字面相等(含两边都无主 —— 单用户形无身份的调用方与无主的行);
- *  · [ref] 窄互认第二臂的身份半支:单机形 ∧ 行无主 ∧ 对方恰为 `default`({@link legacyUnownedAmnestyOpen});
- *  · [ref] 存量哨兵臂:非 `requirePrincipal` ∧ 行恰为 {@link LEGACY_SHELL_SENTINEL_OWNER} ∧ 对方没有主体。
- * **有方向、不传递**:`rowOwner` 是行上记下的(或删前记下的)属主,`principal` 是这一次的调用方 / 住客(没有主体 = `null`);
- * 两条臂各自只认它那一对,不由它们推出 `default` ≡ 哨兵、也不反过来认「`default` 的行 ≡ 无主体的调用方」。
- * 读者:`createAuthorizer` 的会话属主门(有主的行)、`http/principal-gate.ts` 的 `runOwnerReadable`(有主的行)、`deleted-session-ids.ts` 的墓碑读点(删前属主 vs 本次住客)。
- * 不在本判官里的两件(它们问的不是「是不是同一位」):无主的委派子代 placed 行只对 fleet 调用方开放(读面律 {@link ownerlessRowOpen});
- * 删除 / fork / 同步族的放行另有 fleet 臂与 placed 判({@link legacyUnownedSessionOk} = 本判官的第二臂 ∧ {@link ownerlessRowOpen})。
+ * 🔴 **「行上记下的属主」与「这一次的住客」是不是同一位**(本进程删过的会话 id 墓碑 `deleted-session-ids.ts` 的读点与铸点用):属主律事实函数 {@link qualsOf} 的**投影**,不另写第二份判官 ——
+ * 两格资格各取一格:有主的行 ⇒ `owner`(字面同一位);无主的行 ⇒ 两边都无主,或 `j4`(单机形里无主的行 ≡ `default`)。
+ * **有方向、不传递**:`rowOwner` 是行上记下的(或删前记下的)属主,`occupant` 是这一次的住客(没有主体 = `null`);窄臂只认它那一对,
+ * 不由它推出「`default` 的行 ≡ 无主体的调用方」。存量哨兵属主(`anon:shell-live`)在没有身份边界的部署上已由一次性迁移 M48 改写成无主(有身份边界的部署上不改写),不再有按字面量互认的臂 —— 它在这里就是一位普通的具名属主。
+ * 住客是已落成字节的属主列读数(执行上下文解析器交来的根会话行住客),经 {@link recoveredSubject} 恢复成主体 —— 坏形的 `_scn:` 串响亮抛(数据坏,不猜)。
+ * 不是「看得见 / 动得了」的判法(那是面表 {@link visibleOn} 的事:无主的行对任何调用方开放,在这里不算同一位)。
  */
-export declare function sameSessionOwner(deployment: DeploymentShapeInput<"principal">, rowOwner: string | null, principal: string | null): boolean;
+export declare function sameSessionOwner(deployment: DeploymentShapeInput<"principal">, rowOwner: string | null, occupant: string | null): boolean;
 /**
  * 本仓会话店的面 = core `SessionStore` + 本仓的行面(登记 / 列表 / 换装 / 同步……)。
  * 🔴 **按 id 读一行只有一只**:core 的 `headOf(id)`(`{ owner, incarnation, leafId }`,同一行一次读;core 7.55.0 [ref] S2)。
@@ -258,11 +190,15 @@ export type OwnerAwareSessionStore = SessionStore & {
     /** 执行席(规则在 `execution-placement.ts`):根会话行上这一位住客的那一格的唯一读口(`read`)与 place / markMirror 两只写口。三店都有;两只包装原样转发。
      *  缺席 = 会话店没有执行放置(只有不带它的测试走廊 / 嵌入形),调用方各按自己的缺席臂处置。 */
     executionPlacement?: ExecutionPlacementSeat;
-    /** E21 — purge a session's conversation history (session_meta/session_event); idempotent (false if absent).
-     *  `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
-     *  route already owner-gates; this pins the DELETE to the authenticated tenant so even a buggy gate can't purge
-     *  another tenant's history). */
-    deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
+    /** **删除门的头读**(读者只有删除门:`DELETE /v1/sessions/:id` 的属主门,经 `session-incarnation.ts` 的 `deletionHeadReadOf` 一只取法):
+     *  活行 = {@link headOf} 同答;外加在删的行(会话三态 活 → 在删 → 没了 的中间一态,律在 `session-deletion.ts`;local 另有删序停在第一步之后的标记格)的属主与住客 ——
+     *  开始删它的那位属主重发删除(= 接管)就收得完,别的属主得到与「不在」同一句(不可探测)。三只店都交。 */
+    deletionHeadOf?: (sessionId: string) => Promise<SessionHead | undefined>;
+    /** 会话三态的删除面(围栏 `fence` = 删除路唯一的认领判 / 复核 `holds` / 收尾输入 `pending`;律在 `session-deletion.ts`)。三只店都交,包装原样转发。 */
+    sessionDeletion?: SessionDeletionFace;
+    /** 删净一只在删会话的 **local 执行体锁节**(只有 local 店实装;SQL 后端的执行体是执行器的 `eraseSession`,不在会话店上;形与读法见 `session-erase.ts` 的
+     *  {@link LocalSessionDeletionSection})。唯一调用者 `session-erase.ts` 的 `createLocalSessionEraser`。 */
+    deleteSession?: LocalSessionDeletionSection;
     /** 2c session-sync — EXPORT a session's full durable entry log (compaction floor bypassed) for
      *  cross-backend migration; `null` when the source is unknown (the read half of fork, as `SessionTreeEntry[]`). */
     exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;
@@ -325,7 +261,9 @@ export declare function sessionIdShapeIssue(sessionId: unknown): string | undefi
 /** An HTTP error the server maps to a status code (instead of a generic 500). `code` (optional) is a stable
  *  machine-readable identifier the HTTP layer echoes as `{code}` beside the human `{error}` message — the
  *  "typed rejection" posture (structured code on the wire, prose stays with the shell/web).
- *  `extra` (optional) is folded into the error body verbatim (e.g. the scenario allowlist on a reject). */
+ *  `extra` (optional) = the refusal's facts, folded into the error body at its root (e.g. the scenario allowlist on a reject).
+ *  拒体保留键(`http/refusal-body.ts` 的 `REFUSAL_RESERVED_KEYS`)在构造期判:带了 ⇒ 构造即抛 —— 抛出物不是 `HttpError`,落全局兜底的普通 500 臂
+ *  (`request_error` 运维行 + 固定句),而不是等到出线时才发现。构造之后再改 `extra` 由出线点按最终字节判(`http/send.ts`)。 */
 export declare class HttpError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -346,8 +284,12 @@ export declare function createCodedHttpError(status: number, errorCode: string,
  * identity and tenant scope come from the authenticated channel, **never from the request body**.
  */
 export interface AuthContext {
-    /** Authenticated principal, e.g. `user:42` / `org:7`. Undefined when principal auth is off (dev). */
-    principal?: string;
+    /**
+     * 这次请求验过的**主体**(分区键;`owner-brands.ts`):没带场景头 ⇒ 与验过的人逐字节同(`user:42` / `org:7`),带了 ⇒ `_scn:<场景>:<人>`。
+     * 行属主 / 会话认领 / 检查点 scope / 记忆 scope 读它;人面(成本 / 运维 / 场景裁定 / 引擎 `spec.principal`)经 `personOf(subject)` 读。
+     * Undefined when principal auth is off (dev) and the caller sent none.
+     */
+    subject?: Subject;
     /** The session to run against (resolved + ownership-checked here, then returned to the caller). */
     sessionId: string;
     /**
@@ -364,6 +306,12 @@ export interface AuthContext {
      *  (config.projects 查表键 + proj: 键的 projectId 段),不是 capability。main.ts 拿它查 defaultScopes。 */
     resolvedProjectId?: string;
 }
+/** 授权口的入参:请求、体,与提交出口收候选的口(`submission-exit.ts`;只有登记了新行才调,传了也可能一次不调)。 */
+export interface AuthorizeInput {
+    readonly req: IncomingMessage;
+    readonly body: TaskRequestBody;
+    readonly onBirth?: (birth: SessionBirth, face: SessionWithdrawFace) => void;
+}
 /**
  * S6 — close the "sessionId / scope are bearer capabilities" hole.
  *
@@ -379,10 +327,7 @@ export interface AuthContext {
  * Returns a function shaped for `ServiceDeps.authorize`. When `sessionStore` is not the TiDB store
  * (e.g. in-memory dev backend) ownership can't be enforced, so it only derives principal + sessionId.
  */
-export declare function createAuthorizer(config: ServiceConfig, sessionStore: OwnerAwareSessionStore): (ctx: {
-    req: IncomingMessage;
-    body: TaskRequestBody;
-}) => Promise<AuthContext>;
+export declare function createAuthorizer(config: ServiceConfig, sessionStore: OwnerAwareSessionStore, logger?: Pick<Logger, "info">): (ctx: AuthorizeInput) => Promise<AuthContext>;
 /** F1/F3 (codex scope-ledger audit 2026-07-14) — the auth-boundary principal SHAPE gate, applied to every
  *  verified identity source (trusted header, SSO-bridge sub, direct-door JWT sub) so no downstream consumer
  *  ever sees an ambiguous or over-wide principal:
@@ -402,44 +347,32 @@ export declare function createAuthorizer(config: ServiceConfig, sessionStore: Ow
  *     key), `"_leader"` merges with the leader durable-approval owner scope (a tenant so named could list/
  *     decide internal leader approvals), `"_leader-…"` with the leader resource-suspend scope family, and
  *     `"__none__"` with the missing-principal read placeholder of the approval queue faces (≤ 7.132.x replicas).
- *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
- *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
- *     principal would truncate/500 at the INSERT and split one identity into two.
+ *   - more than PRINCIPAL_MAX_BYTES (190) UTF-8 bytes is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
+ *     or VARBINARY(190) (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, mailbox / background-agent key
+ *     columns, …) and the narrowest of them counts bytes — an over-long principal would truncate/500 at the INSERT and split one identity into two.
+ *   - a string that is not well-formed Unicode (a lone surrogate) is `principal_not_a_name`: both SQL drivers store it as U+FFFD, folding it
+ *     onto another principal's rows.
  *  Throws a typed 400 `HttpError` (the HTTP layer maps it): `principal_not_a_name` / `principal_reserved` / `principal_too_long`; the message
  *  names the rule (not a name / a reserved identifier / the length cap), never a secret and never the internal scope's semantics. */
-export declare const PRINCIPAL_MAX_LENGTH = 190;
+export declare function assertPrincipalShape(principal: string): void;
 /**
- * 一个被受理的主体串最多占多少个 UTF-8 字节 —— 按**字节**计宽的身份列(TiDB `VARBINARY(n)`)的列宽**唯一来源**(派生,不手抄第二个数)。
- * {@link PRINCIPAL_MAX_LENGTH} 数的是 UTF-16 码元(`string.length`),一个码元最坏落 3 个 UTF-8 字节:BMP 字符 3 字节;代理对 4 字节 / 2 码元;
- * 孤代理按 U+FFFD 编,3 字节。按**字符**计宽的列(`VARCHAR(n)`:TiDB utf8mb4 / PG 都数码点)直接用 {@link PRINCIPAL_MAX_LENGTH} —— 码点数 ≤ 码元数。
+ * 跨会话信封 `from-scope` 一格编码后的上限(引擎 `agents/cross-session-envelope.js` 的同名上限)。引擎**没有导出**它(也不导常量 —— 引擎给的是一只判官,
+ * 候它到货换读),所以这里是本仓的一份常量 + 一只实读钉(`test/scenario-subject.test.ts` 用引擎自己的信封构造器量它)。
  */
-export declare const PRINCIPAL_MAX_UTF8_BYTES: number;
-/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
- *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
- *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的超范围面。
- *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
- *  resource-suspend scope family); `"__none__"` = the missing-principal read placeholder of the approval
- *  queue faces up to 7.132.x (7.133.0 reads the anonymous group `"_"` instead; still reserved because a 7.132.x replica in the same
- *  rolling upgrade lists that scope for anonymous callers, so a tenant by that name would merge with them there); `"_leader"` = leader durable-approval scope
- *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
- *  (`_leader-resource-<workerId>`, src/leader/wire.ts); prefix `"_orphan:"` = the owner written on a delegated session whose
- *  delegation ancestors are gone (`_orphan:<sessionId>`, src/delegated-session-owner.ts) — a caller allowed to authenticate as it
- *  would read that transcript. NB the `_leader-` prefix REQUIRES the hyphen — a tenant named
- *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
-export declare const RESERVED_PRINCIPALS: readonly string[];
-export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
-/** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
- *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
- *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
- *  principal) reads the verdict instead of catching the throw.
- *
- *  Order: "is it a name at all" first — the other two rules presuppose a name (a reserved identifier / a name too wide for the
- *  column), and the `reserved` sentence echoes the value while the `not_a_name` sentence never does (a string that names nobody may be a
- *  pasted credential). An empty string is `not_a_name` here (the engine's judge says so); a header reader that treats a blank header as
- *  "no principal" decides that before asking. */
-export type PrincipalShapeProblem = "not_a_name" | "reserved" | "too_long";
-export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
-export declare function assertPrincipalShape(principal: string): void;
+export declare const CROSS_SESSION_FROM_SCOPE_MAX_ENCODED = 190;
+/**
+ * 🔴 **带场景的主体编码后最多多宽**(唯一一只预算常量)= 主体真实落点里最严的那一面。主体落进:属主 / scope 列(`VARCHAR(190)`,数原长)、
+ * 跨会话信封的来源 scope(组织投递的发件人来源位,按编码长 ≤ {@link CROSS_SESSION_FROM_SCOPE_MAX_ENCODED};编码 = `[A-Za-z0-9._-]` 原样,其余逐 UTF-8 字节 `%XX`)。
+ * 编码长 ≥ 原长 ⇒ 信封那一面最严 ⇒ 今天 = 190(编码后)。记忆层键**不**是落点:记忆面读人、不读主体(个人段被引擎合规档位当人问),人自己的宽度照旧由
+ * 记忆段判(没带场景的请求同一条既有规则)。与部署形无关:同一只请求换一台部署答案不变。只判**带场景的**主体;不带场景的人维持今天的形判
+ * ({@link PRINCIPAL_MAX_BYTES} 的 UTF-8 字节判)。原长与编码长不是一回事:`_scn:health:` 原长 12、编码长 16(冒号编码成 `%3A`)⇒ 场景 `health` 下人的上界 = 174 编码字符。
+ */
+export declare const SUBJECT_ENCODED_BUDGET = 190;
+/**
+ * 一只主体编码后是否超出 {@link SUBJECT_ENCODED_BUDGET}。判官 = 引擎自己的信封构造器(公开导出;它对来源 scope 编码后超出上限答具名码
+ * `cross_session.invalid_from_scope`)—— 本仓不复刻编码;引擎的来源 scope 判官导出之后改读它。别的码 ⇒ 原样上抛(不是宽度问题,不猜)。
+ */
+export declare function subjectWidthExceeded(subject: Subject): boolean;
 /** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above
  *  ({@link RESERVED_PRINCIPALS}) as the checkpoint/sendfile/resource-suspend scope family's shared value.
  *  Single attested constant + codec pair (naming precedent: {@link SENDFILE_SINGLE_USER_SCOPE} in
@@ -452,8 +385,8 @@ export declare const CHECKPOINT_PUBLIC_SCOPE: "_";
  *
  * 写侧不是本仓能单方面改的:core 的 `treeScope = reviveClaim?.row.scope ?? ctx.principal ??
  * opts.background?.scope` 同时喂**进程内** `defaultTaskRegistry` 与 **durable** 行,而本仓/`core` 全域的
- * 读侧是一整族 `principal ?? "default"`(`runs.ts` markStopSourceForOwner、`boot/session-faces.ts`
- * reapSessionBackground、`http/routes/runs.ts` 的 subagent output/stream 三口、`agents-roster.ts`、
+ * 读侧是一整族 `principal ?? "default"`(`runs.ts` markStopSourceForOwner、会话的引擎租户分区 `session-children-retire.ts`
+ * `sessionTenantScope`(删除协调器的子代 / 信箱 / 后台 shell 三腿)、`http/routes/runs.ts` 的 subagent output/stream 三口、`agents-roster.ts`、
  * `fleet.ts`)。⇒ **把铸点改成 `"_"` 会把这一整族读者一起打瞎**(本车实测:`subagent-tail-content-supply`
  * 的 tail 建连当场 404)。所以归一只能发生在**读侧**:checkpoint 侧拿着 `"_"` 去查 bg 分区时,
  * 显式把这两个键当同一格。
@@ -468,15 +401,31 @@ export declare const BACKGROUND_REGISTRY_ANON_SCOPE: "default";
  * **真名叫 `default`** 的租户必须只匹配自己那格 —— 所以别把别名做成双向。
  */
 export declare function backgroundScopesForCheckpointScope(scope: string): readonly string[];
-/** Encode a principal (or none) as the checkpoint `scope` column value. */
-export declare const encodeCheckpointScope: (principal: string | null | undefined) => string;
-/** Decode a checkpoint `scope` column value back to a principal — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
- *  `undefined` (no principal), everything else passes through verbatim. */
-export declare const decodeCheckpointScope: (scope: string) => string | undefined;
+/** Encode a subject (the partition key — `owner-brands.ts`; or none) as the checkpoint `scope` column value. A row owner read back from a store is the
+ *  same key in its durable form and goes in verbatim; a person never does (the partition is the subject, not the person). */
+export declare const encodeCheckpointScope: (subject: string | null | undefined) => string;
+/** Decode a checkpoint `scope` column value back to the owner it was written for — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
+ *  `undefined` (no principal), everything else verbatim as a {@link DurableOwnerKey} (the scope column is a stored owner key; this is one of
+ *  the brand's two mint points — the other is `owner-faces.ts` `ownerKeyOf`). The run it governs executes in this partition; the person behind it
+ *  (cost / lease / governance / the engine's `spec.principal`) is read ONLY through `owner-brands.ts` `partsOf` — never by feeding the key into a person
+ *  slot. Comparing it with a caller goes through `owner-faces.ts` only (`keyAdmits` / `sameParty`). */
+export declare const decodeCheckpointScope: (scope: string) => DurableOwnerKey | undefined;
 /** A checkpoint `scope` value read as the **owner column** of the rows it governs (run rows, live / crash asks): {@link CHECKPOINT_PUBLIC_SCOPE}
  *  ⇒ `null` (the null-owner rows: tasks submitted without a principal), everything else verbatim. The one translation from the approval faces'
  *  scope to an owner filter — stores filter on the owner column and never recognize `"_"` themselves. */
-export declare const ownerOfCheckpointScope: (scope: string) => string | null;
+export declare const ownerOfCheckpointScope: (scope: string) => DurableOwnerKey | null;
+/** A checkpoint `scope` value recovered into its three cells (`owner-brands.ts` `partsOf`; the internal pipeline — no reserved-prefix / registry /
+ *  width judgment): {@link CHECKPOINT_PUBLIC_SCOPE} ⇒ `undefined` (no subject). The resume family reads the run's partition (`subject`) and the person
+ *  behind it (`person`: cost / lease / usage window / the engine's `spec.principal`) from this one decode. */
+export declare const checkpointPartsOf: (scope: string) => SubjectParts | undefined;
+/**
+ * 🔴 **停驻行 scope 列的行格**(检查点面 `scope.decide` 与迟到决定 `ask.answer` 判的那一格;`owner-faces.ts` 的 `keyAdmits` 吃它):
+ * {@link CHECKPOINT_PUBLIC_SCOPE} = 匿名单用户形写下的行 ⇒ 普通无主行(开放);别的串 ⇒ 有主({@link decodeCheckpointScope} 铸键);
+ * **不是串**(越契约的行体 —— 不做形状校验的 JSON 读取把 scope 读成 nullish)⇒ 坏格(`undefined`:一格行资格都不给,只剩本口放的运维),
+ * 绝不把畸形行折成「公开」。店的轻读(`peekPendingScope` / `peekScopeByToken`)把匿名行读成 `null` 值 —— 那是店契约里的匿名,调用点按契约先换成
+ * {@link CHECKPOINT_PUBLIC_SCOPE} 再交进来(`peeked ?? CHECKPOINT_PUBLIC_SCOPE`)。
+ */
+export declare function scopeCellOf(scope: string): SessionOwnerCell | undefined;
 /** Read the authenticated principal from the trusted header. Never from the body. */
 export declare function principalFrom(req: IncomingMessage, config: ServiceConfig): string | undefined;
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
@@ -502,6 +451,27 @@ export declare function setSsoRole(req: IncomingMessage, role: string): void;
 export declare function ssoVerifiedRole(req: IncomingMessage): string | undefined;
 export declare function setSsoPrincipalInc(req: IncomingMessage, principalInc: string): void;
 export declare function ssoVerifiedPrincipalInc(req: IncomingMessage): string | undefined;
-export declare function verifiedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
-export {};
+/**
+ * 这次请求验过的**人** —— `Person` 品牌的请求面铸点(`owner-brands.ts` 铸点闭集)。身份从哪来只在 {@link verifiedIdentity} 判(三来源,优先序见那里),这里只铸一次。
+ * 人面汇点(成本 / 租约 / 运维名册 / 场景裁定)读它;分区面读 {@link verifiedSubject}(同一个人加上请求的场景)。
+ */
+export declare function verifiedPerson(req: IncomingMessage, config: ServiceConfig): Person | undefined;
+/**
+ * 请求自报场景的头(定名,不加配置键)。带它 = 这次请求在这个人的这一个场景分区里;不带 = 与今天逐字节同。场景是人之内的自选收窄,不是权限主张:
+ * 直连门上它也是自报的,最坏 = 同一个人的另一个分区(专家之间的隔离靠调用方平台不把头交给模型,与 `spec.principal` 同一条控制面契约)。
+ */
+export declare const SCENARIO_HEADER = "x-agent-scenario";
+/** 场景头的原始读数(空白 ⇒ 没带;重复头取第一只,与主体头同读法)。 */
+export declare function scenarioHeaderOf(req: IncomingMessage): string | undefined;
+/** 场景头在、却没有验过的人 ⇒ 400(只收紧:不拒就写出无主行 = 谁都看得见)。码与句一处铸(分派层的头判决与凭据门旁路的读口同用)。 */
+export declare function scenarioWithoutPrincipalError(): HttpError;
+/** 场景头的名字不是这台部署的场景(不合文法的名字不可能在册)⇒ 400 `scenario_unknown`(与任务提交腿点名未知场景同码)。 */
+export declare function scenarioHeaderUnknownError(name: string, known: readonly string[] | undefined): HttpError;
+/**
+ * 🔴 **这次请求验过的主体**(外部管线;`Subject` 的请求面读数,铸点是 `owner-brands.ts` 的 `subjectOf`)。没带场景头 ⇒ 与 {@link verifiedPerson} 逐字节同;
+ * 带了 ⇒ `subjectOf(人, 场景)`,三判只在这里(恢复管线不判):① 没有验过的人 ⇒ {@link scenarioWithoutPrincipalError};② 名字不合场景文法 ⇒ 400 `scenario_unknown`
+ * (在册判在分派层,它读这台部署的场景表);③ 主体编码后超出 {@link SUBJECT_ENCODED_BUDGET} ⇒ 400 `principal_too_long`(句报编码后的预算)。
+ * 人自己的形判(名形 / 保留前缀 / 原长)照旧在 {@link verifiedIdentity} 里先判。按请求对象记忆化:同一只请求的各读口读同一只判决。
+ */
+export declare function verifiedSubject(req: IncomingMessage, config: ServiceConfig): Subject | undefined;
 //# sourceMappingURL=security.d.ts.map