@sema-agent/server 7.150.0 → 7.151.0

package/dist/config-types.d.ts

@@ -19,7 +19,7 @@ import type { QuestionThrottle } from "./question.js";
 import type { UnattendedApprovalPolicy } from "./tool-approval.js";
 import type { InfraCostRates } from "./observability/cost-taxonomy.js";
 import type { Autonomy, CommandRule } from "./runtime-governance.js";
-import type { CenterCredentialSource } from "./center-credential.js";
+import type { CenterCredentialSource, DeclaredCredentialOrigin } from "./center-credential.js";
 import type { GitApiKind } from "./git-api-kind.js";
 import type { CustomPkgSource } from "./sandbox-pkg-source.js";
 import type { MemoryEngineBackend, StoreBackend as StoreBackendWord } from "@sema-agent/settings-schema/execution-lanes";
@@ -828,8 +828,9 @@ export interface ServiceConfigFlat {
      *  models/roles; mutateInPlace keeps the reference. */
     tiers: Record<string, string>;
     /** 项目登记簿(settings-schema `projects` 域):键 = projectId(小写规范 UUID),值 = settings-schema 的 `ProjectRegistration` **原样**
-     *  (本仓不持第二份项目型、不挑键 —— 形与判官只在 settings-schema)。读者:`GET /v1/projects` 读面(`http/routes/projects.ts`);
-     *  `defaultScopes` 作 `TaskSpec.memory.scopes` 的种子(v2 scope 键串,OPEN 值域 —— 本表只登记不解释)与 org 记忆准入的部署 scope 集。
+     *  (本仓不持第二份项目型、不挑键 —— 形与判官只在 settings-schema)。按调用方读(可见性判 + 按 id 取)只经 `project-registry.ts`:`GET /v1/projects` 读面
+     *  (`http/routes/projects.ts`)、项目上下文继承、`defaultScopes` 作 `TaskSpec.memory.scopes` 的种子(v2 scope 键串,OPEN 值域 —— 本表只登记不解释);
+     *  部署级聚合(org 记忆准入的部署 scope 集,`boot/org-memory.ts`)整表读。
      *  NO env source —— 只由 applyEffective 经 settings-schema 的视图面读函数判过后填(mutateInPlace,boot + refresh 整表替换);
      *  本地腿恒空(settings-schema 的本地读取集不收 `projects`)。 */
     projects: Record<string, ProjectRegistration>;
@@ -2340,12 +2341,17 @@ export interface ServiceConfigFlat {
      *  `liveBaseUrl`(编排器片 2,env `SEMA_WEB_ADMIN_LIVE_URL`):fleet 活性组(心跳 / 注销、服务租约 —— settings-schema `FLEET_LIVE_PATHS`)的基址,
      *  给「管理面在就绪门后、活性面另走一条不看就绪的入口」的部署;缺席 ⇒ 活性组也打 `baseUrl`(这条缺省只在 `centerFetch` 读)。
      *  `webBaseUrl`(7.121.0,env `SEMA_WEB_ADMIN_WEB_URL`):这个中心的 **web 面固定基址**,运维声明、引擎原样转述到 `/health.center.webBaseUrl`
-     *  (壳按它拼会话深链;路径怎么拼归壳)。起服时判成「可拼路径的基址」:http(s)、不带凭据 / query / fragment,否则拒启;缺席即缺席,引擎不拼不猜。 */
+     *  (壳按它拼会话深链;路径怎么拼归壳)。起服时判成「可拼路径的基址」:http(s)、不带凭据 / query / fragment,否则拒启;缺席即缺席,引擎不拼不猜。
+     *  `assertionToken`([ref]):web-admin 断言令牌(`SEMA_WEB_ADMIN_ASSERTION_TOKEN` / `_FILE`,二选一,都设拒启)的**声明读数**,非秘密投影 ——
+     *  声明在 ⇒ 来源两形之一(`env` / `file` + 绝对路径);没声明 ⇒ 这一格缺席(`loadConfig` 只在声明在时写它;缺席只有一种读法 = 没声明)。
+     *  值不进配置:本版只读声明、不向中心出示;读者 = `/health.center.assertionToken` 与起服日志 `center_assertion_token`。读口与 `credential` 同一只
+     *  (`center-credential.ts` 的 `readWebAdminCredentialDeclaration`)。 */
     webAdmin?: {
         baseUrl: string;
         liveBaseUrl?: string;
         webBaseUrl?: string;
         credential: CenterCredentialSource;
+        assertionToken?: DeclaredCredentialOrigin;
         dryRun: boolean;
         worker?: string;
     };

package/dist/config.d.ts

@@ -124,7 +124,10 @@ export declare function parseConfigProvider(): ConfigProviderWord | undefined;
 /** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [ref]④ boot
  *  notices) in one place. EVERY entrypoint that calls loadConfig() then builds a logger must call this right
  *  after (main.ts, run-local.ts) — a new entry that forgets it would silently drop operator-facing diagnostics
- *  (run-local historically did exactly that), so the drain lives beside the collectors, not in one entrypoint. */
+ *  (run-local historically did exactly that), so the drain lives beside the collectors, not in one entrypoint.
+ *  Draining is repeatable: a read made AFTER the boot drain (the execution-lane composition step reads the env of a lane the config file chose;
+ *  `boot/execution-lane.ts`) calls it again right after, so its soft-knob rejects and knob registrations reach the log instead of piling up
+ *  undrained — the polarity table (debug) is then printed again, now covering that read too. */
 export declare function logConfigDiagnostics(logger: {
     warn: (event: string, fields?: Record<string, unknown>) => void;
     info?: (event: string, fields?: Record<string, unknown>) => void;
@@ -192,10 +195,56 @@ export declare function buildUnpricedCeilingNotice(models: Record<string, Model>
 export type EntryDeclarableLane = Extract<ExecutionLane, "host" | "none">;
 /**
  * 这两条车道的配置形(唯一铸点):env 声明了它们时由 {@link loadConfig} 的车道链调,入口程序自身声明它们时由执行车道合成步调 —— 坐标 env 同一读法。
- * DUAL-MODE §5:`host` = 在这台机器上跑、无容器(坐标 `HOST_WORKSPACE_BASE` / `HOST_COMMAND_TIMEOUT_MS` 可选,无必需 env)。
+ * DUAL-MODE §5:`host` = 在这台机器上跑、无容器(坐标 `HOST_WORKSPACE_BASE` / `HOST_COMMAND_TIMEOUT_MS` 可选,无必需 env;读数见 {@link parseHostLaneEnv})。
  * 契约 18.0.0:`none` = 部署声明「智能体的工具没有执行环境」(零字段、无必需 env)。
  */
 export declare function entryDeclarableRemoteExec(lane: EntryDeclarableLane): RemoteExecConfig;
+/** `host` 车道的配置块(型从 {@link RemoteExecConfig} 判别联合取,不另写第二份字段表)。 */
+type HostRemoteExec = Extract<RemoteExecConfig, {
+    provider: "host";
+}>;
+/** `local-docker` 车道的配置块(同上)。 */
+type LocalDockerRemoteExec = Extract<RemoteExecConfig, {
+    provider: "local-docker";
+}>;
+/** env 一侧对 `host` 车道的读数(块去掉判别位)。 */
+export type HostEnvReading = Omit<HostRemoteExec, "provider">;
+/** env 一侧对 `local-docker` 车道的读数(块去掉判别位;`image` 改可选 —— `DOCKER_IMAGE` 是本车道的必需 env,读数本身不判必需,判官是车道必需 env 门)。 */
+export type LocalDockerEnvReading = Omit<LocalDockerRemoteExec, "provider" | "image"> & {
+    image?: string;
+};
+/**
+ * **`host` 车道的 env 读数**(唯一读者):`HOST_WORKSPACE_BASE` / `HOST_COMMAND_TIMEOUT_MS`。env 声明路径({@link entryDeclarableRemoteExec})、入口自身声明、
+ * 文件腿(`config.d/remote-exec.json` 选定 host 车道时,车道参数仍由 env 读)读的都是这一只。求值时点:`REMOTE_EXEC` 声明的车道在 `loadConfig` 里求值(早于文件);
+ * 文件选定而 env 没声明它 ⇒ 执行车道合成步现读;没被选中的车道不求值 —— 那里它们是无关配置。
+ */
+export declare function parseHostLaneEnv(): HostEnvReading;
+/**
+ * **`local-docker` 车道的 env 读数**(唯一读者):`DOCKER_*` 的全部坐标与车道参数(含容器帽、pids 限额、丢 capability、带外 env 名单)。env 声明路径
+ * ({@link loadConfig} 的车道链)与文件腿(`config.d/remote-exec.json` 选定 local-docker 车道时)读的是这一只:文件只定「哪条车道」,车道参数仍只有 env 一处可写,
+ * 文件里有同名格的那几格由文件胜(`FILE_LANE_CELL_ENV` 列的五格)。只在本车道被选中(env 声明,或文件选定)时求值 —— 其它车道上它们是无关配置。
+ * `singleUserTurnkey` = 本部署是不是单用户姿态(`REQUIRE_PRINCIPAL !== "true"`;名单型旋钮 `DOCKER_SANDBOX_ENV` 的姿态判)。
+ */
+export declare function parseLocalDockerLaneEnv(singleUserTurnkey: boolean): LocalDockerEnvReading;
+/**
+ * **文件格 ↔ env 键的对表**(`config.d/remote-exec.json` 与 env 对「同一件事」各有一个名字):文件选定车道后,块 = env 读数 ∪ 文件格,**同名格文件赢**;
+ * 两处在同一格上给了不同的值 ⇒ 文件赢并响亮点名那一格的 env 键(`remote_exec_file_overrides`,执行车道合成步)。表序 = 点名序。
+ * 格名取块的字段名(`satisfies` 钉住:块改名而表不跟 ⇒ 编译红);env 键须是车道表里这条车道的坐标键、且上面两只读者真的读它(`test/remote-exec-file-lane-env-params.test.ts` 钉)。
+ * 文件腿读不到 env 键字面 —— 键名只住在读者与这张表里。
+ */
+export declare const FILE_LANE_CELL_ENV: {
+    readonly host: {
+        readonly workspaceBase: "HOST_WORKSPACE_BASE";
+        readonly commandTimeoutMs: "HOST_COMMAND_TIMEOUT_MS";
+    };
+    readonly "local-docker": {
+        readonly image: "DOCKER_IMAGE";
+        readonly mountPath: "DOCKER_MOUNT_PATH";
+        readonly memory: "DOCKER_MEMORY";
+        readonly cpus: "DOCKER_CPUS";
+        readonly network: "DOCKER_NETWORK";
+    };
+};
 /** [ref] N8/N9 — the BOOLEAN member of this module's env-parser family (`env`/`env2`/`numEnv`/
  *  `numEnvBounded`/`optFinitePositiveEnv`/`enumEnv`/`headerNameEnv`). Until now booleans were the
  *  one type parsed by a hand-written literal comparison at every single site, and that is exactly why the same

package/dist/config.js

@@ -49,7 +49,7 @@ import { AUTONOMY_MODES } from "./runtime-governance.js";
 import { deploymentRuleRefusal } from "./rule-issue-reading.js";
 import { MAX_NAMED_INERT_ENTRIES, allowLayerEntryCountIssue, describeInertRuleEntries, inertRuleEntriesOf, inertRuleEntryGuidance, ruleEntryListShapeOk } from "./rule-entry-list.js";
 import { readReadDenyEntry } from "./read-deny-entry.js";
-import { createCenterCredentialSource, readCenterCredentialDeclaration } from "./center-credential.js";
+import { createCenterCredentialSource, credentialOriginOf, readWebAdminCredentialDeclaration } from "./center-credential.js";
 import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js";
 import { catalogBrainLane, modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
@@ -408,15 +408,39 @@ function parseDeviceRelayUrlEnv(raw) {
 export function entryDeclarableRemoteExec(lane) {
     switch (lane) {
         case "host":
-            return {
-                provider: "host",
-                ...(process.env.HOST_WORKSPACE_BASE ? { workspaceBase: process.env.HOST_WORKSPACE_BASE } : {}),
-                ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("HOST_COMMAND_TIMEOUT_MS")),
-            };
+            return { provider: "host", ...parseHostLaneEnv() };
         case "none":
             return { provider: "none" };
     }
 }
+export function parseHostLaneEnv() {
+    return {
+        ...(process.env.HOST_WORKSPACE_BASE ? { workspaceBase: process.env.HOST_WORKSPACE_BASE } : {}),
+        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("HOST_COMMAND_TIMEOUT_MS")),
+    };
+}
+export function parseLocalDockerLaneEnv(singleUserTurnkey) {
+    return {
+        ...(process.env.DOCKER_IMAGE ? { image: process.env.DOCKER_IMAGE } : {}),
+        ...(process.env.DOCKER_MOUNT_PATH ? { mountPath: process.env.DOCKER_MOUNT_PATH } : {}),
+        ...(process.env.DOCKER_PATH ? { dockerPath: process.env.DOCKER_PATH } : {}),
+        ...(process.env.DOCKER_HOST ? { dockerHost: process.env.DOCKER_HOST } : {}),
+        ...(process.env.DOCKER_MEMORY ? { memory: process.env.DOCKER_MEMORY } : {}),
+        ...((n) => (n !== undefined ? { cpus: n } : {}))(optNumEnvStrict("DOCKER_CPUS")),
+        ...((n) => (n !== undefined ? { pidsLimit: n } : {}))(optFinitePositiveEnv("DOCKER_PIDS_LIMIT")),
+        ...(boolEnv("DOCKER_DROP_CAPS", false) ? { dropAllCaps: true } : {}),
+        ...(process.env.DOCKER_NETWORK
+            ? { network: enumEnv("DOCKER_NETWORK", "bridge", ["none", "bridge", "host"]) }
+            : {}),
+        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("DOCKER_COMMAND_TIMEOUT_MS")),
+        ...((names) => (names !== undefined ? { env: allowlistedEnv(names, process.env) } : {}))(parseEnvNameAllowlist("DOCKER_SANDBOX_ENV", singleUserTurnkey)),
+        ...((capacity) => (capacity !== undefined ? { capacity } : {}))(parseLocalDockerCapacityEnv()),
+    };
+}
+export const FILE_LANE_CELL_ENV = {
+    host: { workspaceBase: "HOST_WORKSPACE_BASE", commandTimeoutMs: "HOST_COMMAND_TIMEOUT_MS" },
+    "local-docker": { image: "DOCKER_IMAGE", mountPath: "DOCKER_MOUNT_PATH", memory: "DOCKER_MEMORY", cpus: "DOCKER_CPUS", network: "DOCKER_NETWORK" },
+};
 const envNamesNoLane = (raw) => raw === undefined || raw === "";
 function declaredExecutionLane(raw) {
     if (envNamesNoLane(raw))
@@ -2127,23 +2151,8 @@ function parseOrchestrationDomain(ctx) {
                                             ? entryDeclarableRemoteExec(declaredLane)
                                             :
                                                 declaredLane === "local-docker" && process.env.DOCKER_IMAGE
-                                                    ? {
-                                                        provider: "local-docker",
-                                                        image: process.env.DOCKER_IMAGE,
-                                                        ...(process.env.DOCKER_MOUNT_PATH ? { mountPath: process.env.DOCKER_MOUNT_PATH } : {}),
-                                                        ...(process.env.DOCKER_PATH ? { dockerPath: process.env.DOCKER_PATH } : {}),
-                                                        ...(process.env.DOCKER_HOST ? { dockerHost: process.env.DOCKER_HOST } : {}),
-                                                        ...(process.env.DOCKER_MEMORY ? { memory: process.env.DOCKER_MEMORY } : {}),
-                                                        ...((n) => (n !== undefined ? { cpus: n } : {}))(optNumEnvStrict("DOCKER_CPUS")),
-                                                        ...((n) => (n !== undefined ? { pidsLimit: n } : {}))(optFinitePositiveEnv("DOCKER_PIDS_LIMIT")),
-                                                        ...(boolEnv("DOCKER_DROP_CAPS", false) ? { dropAllCaps: true } : {}),
-                                                        ...(process.env.DOCKER_NETWORK
-                                                            ? { network: enumEnv("DOCKER_NETWORK", "bridge", ["none", "bridge", "host"]) }
-                                                            : {}),
-                                                        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("DOCKER_COMMAND_TIMEOUT_MS")),
-                                                        ...((names) => (names !== undefined ? { env: allowlistedEnv(names, process.env) } : {}))(parseEnvNameAllowlist("DOCKER_SANDBOX_ENV", singleUserTurnkey)),
-                                                        ...((capacity) => (capacity !== undefined ? { capacity } : {}))(parseLocalDockerCapacityEnv()),
-                                                    }
+                                                    ?
+                                                        { provider: "local-docker", ...parseLocalDockerLaneEnv(singleUserTurnkey), image: process.env.DOCKER_IMAGE }
                                                     :
                                                         declaredLane === "device"
                                                             ? {
@@ -2488,12 +2497,14 @@ function parseCenterBaseUrl(name, raw, role) {
 }
 function parseWebAdmin(baseUrl, requirePrincipal, liveBaseUrl, webBaseUrl) {
     const worker = process.env[WEB_ADMIN_ENV.worker] || undefined;
-    const declared = readCenterCredentialDeclaration();
+    const declared = readWebAdminCredentialDeclaration("access");
+    const assertion = credentialOriginOf(readWebAdminCredentialDeclaration("assertion"));
     return {
         baseUrl,
         ...(liveBaseUrl !== undefined ? { liveBaseUrl } : {}),
         ...(webBaseUrl !== undefined ? { webBaseUrl } : {}),
         credential: createCenterCredentialSource(declared.from === "file" ? { ...declared, multiTenant: requirePrincipal } : declared, worker),
+        ...(assertion.from !== "absent" ? { assertionToken: assertion } : {}),
         dryRun: boolEnv(WEB_ADMIN_ENV.dryRun, false),
         worker,
     };

package/dist/deployment-shape.d.ts

@@ -17,7 +17,7 @@
  * `holds` 的入参型 = 所声明轴读入形的交叉({@link DeploymentShapeInput}),所以调用方递完整 `ServiceConfig` 或只递那几键的窄形都行。
  *
  * ## 什么进表、什么不进
- * 进表的是**形规则**:只由部署形事实决定的布尔(去重后 15 行;同一条规则的多个消费者读同一行,不各成一行)。
+ * 进表的是**形规则**:只由部署形事实决定的布尔(去重后 16 行;同一条规则的多个消费者读同一行,不各成一行)。
  * 把一行与**非形事实**(锁键、合规档位、审批意图、请求身份、请求体)合取的能力判据是**消费者**,住在它自己的模块
  * (`mcpInjectionHonored` = 锁 ∧ 合规 ∧ `!multiTenant`;`taskHooksHonored`;身份门 …),读行、不读原始键。
  * 车道表(`execution-lane-caps.ts`)按车道词键控的布尔列(`laneIsolated` 等)是车道轴自己的事实表,不是「部署」的谓词;行读它们。
@@ -111,6 +111,14 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 一次性迁移 M48 的输入(`plugins/store-backend.ts`:有边界 ⇒ 不改写哨兵属主)。
      */
     identityBoundary: DeploymentShapePredicate<"principal" | "identity">;
+    /**
+     * 「这台部署接没接**过凭据门**的来源」的问法 —— 身份来源律 5(`identity-source.ts` 头注)在部署上的投影:配置接了的来源里有凭据门认的那一类
+     * (service 凭据,或鉴权桥 issuer —— 含中心回退;`passesCredentialGate` 那一列)。**不是** {@link DEPLOYMENT_SHAPE_PREDICATES.identityBoundary}:
+     * 那一行把 `REQUIRE_PRINCIPAL` / 只读 trace 凭据 / 直连门也算作边界(它们让主体头不再是 dev-open 的自报),本行只问「有没有一类凭据过得了门」——
+     * 三样都不过,所以只配其中之一的部署两行答案相反,这是两问,不是一问两答。没接 ⇒ 写门(问请求)对每一次请求都拒(`ALLOW_UNAUTHED_WRITES` 之外)。
+     * 读者:记忆整理阀门的启动期告警(`boot/stage-06-runners.ts`;「这台部署上 run 口对谁都开不了」)。请求面不读本行:写门问的是请求。
+     */
+    credentialGateSource: DeploymentShapePredicate<"identity">;
     /**
      * 租户轴的问法。今天与 {@link DEPLOYMENT_SHAPE_PREDICATES.principalRequired} 读**同一个声明**([ref] ①:托管 / 多租 ⇔ `REQUIRE_PRINCIPAL=true`,
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。

package/dist/deployment-shape.js

@@ -1,5 +1,5 @@
 import { capabilitiesFor, executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane, laneWiresExecutionEnv } from "./execution-lane-caps.js";
-import { configuredIdentitySources } from "./identity-source.js";
+import { configuredIdentitySources, passesCredentialGate } from "./identity-source.js";
 function readPrincipalAxis(deployment) {
     return { declared: deployment.requirePrincipal === true };
 }
@@ -54,6 +54,7 @@ const VM_ISOLATION_RUNTIME_CLASSES = new Set(["kata", "kata-qemu", "kata-clh", "
 export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
     principalRequired: createPredicate(["principal"], "身份轴:运维声明了 REQUIRE_PRINCIPAL=true —— 每个调用方都必须带一个验过的主体。", ({ principal }) => principal.declared),
     identityBoundary: createPredicate(["principal", "identity"], "身份轴:这台部署有身份边界 —— 声明了 REQUIRE_PRINCIPAL,或配置接了任一已验身份来源(service 凭据 / 鉴权桥 / 直连门),或声明了只读 trace 凭据。", ({ principal, identity }) => principal.declared || identity.sources.length > 0 || identity.traceTokenDeclared),
+    credentialGateSource: createPredicate(["identity"], "身份轴:这台部署接了一类过凭据门的来源 —— service 凭据,或鉴权桥(登录令牌);只开 REQUIRE_PRINCIPAL / 只配 trace 凭据 / 只开直连门都不算。", ({ identity }) => identity.sources.some(passesCredentialGate)),
     multiTenant: createPredicate(["principal"], "租户轴:这台部署服务不止一个主人(托管 / 多租;C-R100 ① 由 REQUIRE_PRINCIPAL=true 声明)。", ({ principal }) => principal.declared),
     callerCwd: createPredicate(["lane", "principal"], "车道 × 租户 / 设备归属:调用方送来的 cwd(与 settings.env)被尊重 —— host 车道且单主,或 device 车道。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.callerCwd, principal)),
     callerOwnsWorkerDisk: createPredicate(["lane", "principal"], "车道 × 租户:手就在本 worker 的盘上且部署只有一个主人 —— 这块盘上的路径就是调用方自己的。", ({ lane, principal }) => lane.lane !== undefined && handsOnWorkerFilePlane(lane.lane) && !principal.declared),

package/dist/device-protocol.d.ts

@@ -7,11 +7,12 @@
  *
  * 为什么是精选而不是把 `device-ws-protocol.ts` 整只暴露:那个模块里还有**服务端**自己的半场(帧解析与准入、
  * 验签、各种铸 id)。把它们变成公开面,等于替实现细节背上 semver。这里只再导出 executor **会用到**的:
- * 闭集常量、两向帧型、构造握手签名字节所需的两只纯函数,以及两份「随协议修订号走」的事实:结局码按修订号分行的增量表
- * (`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` + 取集函数 `deviceOutcomeErrorCodesAt`:executor 按自己声明的修订号裁剪会发的词)与
+ * 闭集常量、两向帧型、构造握手签名字节所需的两只纯函数,以及三份「随协议修订号走」的事实:结局码按修订号分行的增量表
+ * (`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` + 取集函数 `deviceOutcomeErrorCodesAt`:executor 按自己声明的修订号裁剪会发的词)、指令 kind 按修订号分行的增量表
+ * (`DEVICE_INSTRUCTION_KINDS_BY_REVISION` + 取集函数 `deviceInstructionKindsAt`:executor 按自己声明的修订号裁剪 `hello.supports` —— 高于它的 kind 声明了也不会下发)与
  * helloAck 数值位的界表(`DEVICE_HELLO_ACK_BOUNDS` + 判据 `deviceHelloAckNumberFlaw`:executor 读到越界值 ⇒ 协议违例)。要加名字 = 改这只文件 + 同批改
  * `test/device-protocol-subpath.test.ts` 的闭集(新增公开面必须是一次有意的动作)。
  */
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
-export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceOutcomeErrorCode, DeviceProtocolRevision, DeviceHelloAckNumericField, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_INSTRUCTION_KINDS_BY_REVISION, DEVICE_BOUND_READ_OPS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceInstructionKindsAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
+export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceBoundReadOp, DeviceOutcomeErrorCode, DeviceProtocolRevision, DeviceHelloAckNumericField, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.d.ts.map

package/dist/device-protocol.js

@@ -1,2 +1,2 @@
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_INSTRUCTION_KINDS_BY_REVISION, DEVICE_BOUND_READ_OPS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceInstructionKindsAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.js.map

package/dist/device-ws-hub.js

@@ -5,7 +5,7 @@ import { WebSocketServer } from "ws";
 import { DEVICE_DRAINING_CODE, DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, assertDeviceIdShape, } from "./device-store.js";
 import { MAX_TIMER_DELAY_MS } from "./config-types.js";
 import { canonicalAddress, createTrustedProxySet } from "./net-address.js";
-import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, deviceProtocolRevisionRefusal, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
+import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKindAt, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, deviceProtocolRevisionRefusal, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
 const OUTCOME_UNKNOWN_SENTENCE = "outcome unknown — the command may have already executed on the device; verify its effect before re-running";
 const SETTLED_MEMO_MAX = 512;
 const DRAIN_RETRY_AFTER_SEC = 15;
@@ -66,6 +66,7 @@ const ALLOWED_SUCCESS_OUTCOME_KINDS = {
     remove: ["void"],
     createTempDir: ["write"],
     createTempFile: ["write"],
+    openBound: ["stat", "read"],
 };
 const HELLO_ACK_FIELD_SOURCES = {
     heartbeatIntervalMs: "option heartbeatIntervalMs",
@@ -500,7 +501,7 @@ export function createDeviceWsHub(options) {
         conn.workspaceRoot = frame.workspaceRoot;
         const supported = new Set();
         for (const s of frame.supports) {
-            const k = asInstructionKind(s);
+            const k = asInstructionKindAt(s, frame.protocolVersion);
             if (k !== null)
                 supported.add(k);
         }

package/dist/device-ws-protocol.d.ts

@@ -5,16 +5,20 @@ export declare const DEVICE_WS_PATH = "/v1/device/ws";
  * 本 server 铸/认的协议**修订号**(wire 上的 `protocolVersion`)。
  *
  * 规则(真源 = 协议文档 `docs/DEVICE-EXECUTOR-PROTOCOL.md` §2.1「Protocol revisions」段,此处只转述):加帧 / 加字段 = additive 不升号;
- * 其余变更一律升号并在增量表加一行,已发布的行不改 —— **server 受理的闭集(executor → server 方向,今天 = 结局 `errorCode` 词集)加词 = 升号**,
- * **语义变更(server 下发的帧意思变了)= 升号**。修订号是 executor 在发 hello 之前唯一能读到的「这台 server 受理什么、发来的帧是什么意思」的事实
- * (challenge 帧带它),所以 server 受理的词集必须是修订号的函数({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION},协议文档同名表),不另发第二份列表;
- * 闭集变了而修订号没变 = 同一个修订号两种受理集(7.132.0 给结局码加 `liveness_no_output` 时没抬号,7.136.0 补到 2)。类型锁:抬了号而表没有这一行 ⇒ 编译红。
+ * 其余变更一律升号并在增量表加一行,已发布的行不改 —— **指令两向的闭集加词 = 升号**:server 受理的结局 `errorCode` 词集(executor → server)
+ * 与 server 下发的指令 kind 集(server → executor),各一张按修订号分行的表({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION} /
+ * {@link DEVICE_INSTRUCTION_KINDS_BY_REVISION},同一组行键;协议文档是同一张修订号表的两栏);**语义变更(server 下发的帧意思变了)= 升号**。
+ * 修订号是 executor 在发 hello 之前唯一能读到的「这台 server 受理什么、会发来什么、发来的帧是什么意思」的事实(challenge 帧带它),所以两个闭集
+ * 都必须是修订号的函数,不另发第二份列表;闭集变了而修订号没变 = 同一个修订号两种集合(7.132.0 给结局码加 `liveness_no_output` 时没抬号,7.136.0 补到 2)。
+ * 下发方向的读法:汇聚端只认**这条连接协商的修订号**那一份 kind 集({@link asInstructionKindAt}),高于它的 kind 与认不出的词同读 —— 恒不下发。
+ * 类型锁:抬了号而任一张表没有这一行 ⇒ 编译红。
  */
 export declare const DEVICE_PROTOCOL_VERSION: DeviceProtocolRevision;
 /**
  * 受理下沿:低于它 ⇒ `helloReject: protocol_version_unsupported`(带 `minProtocolVersion` 与一句 {@link deviceProtocolRevisionRefusal},响亮拒,不静默降级,[ref])。
  * 兼容窗 = [MIN, 当前]。律(协议文档 §2.1 规则句):升号的变更旧修订的 executor 守不住 ⇒ 同一版把下沿抬到那一修订号 —— 旧 executor 在 hello 被拒一次,
  * 而不是逐调用失败。今天 = 5:修订号 5 起路径只锚不折(下沿理由见 {@link DEVICE_FLOOR_CHANGE}),写给修订号 ≤ 4 的 executor 认的是折过的路径。
+ * 修订号 6(kind 集加 `openBound`)不抬下沿:那个 kind 只派给协商修订号 ≥ 6 的连接,修订号 5 的 executor 收不到它 ⇒ 守得住。
  * 这是**本 server** 的受理下沿,不是 executor 协商时的下界(executor 一侧修订号是累积的:实现了 5 的照样能按 4 服务老 server)。
  */
 export declare const DEVICE_MIN_PROTOCOL_VERSION: DeviceProtocolRevision;
@@ -71,11 +75,44 @@ export type DeviceCancelState = (typeof DEVICE_CANCEL_STATES)[number];
  */
 export declare const DEVICE_INSTRUCTION_STATES: readonly ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
 export type DeviceInstructionState = (typeof DEVICE_INSTRUCTION_STATES)[number];
-/** 指令 kind ↔ core 的 FileSystem+Shell 面 1:1(§5.1;双端穷举 switch)。 */
-export declare const DEVICE_INSTRUCTION_KINDS: readonly ["exec", "execStream", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile", "fileInfo", "listDir", "canonicalPath", "exists", "readLink", "createDir", "remove", "createTempDir", "createTempFile", "statBatch"];
-export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS)[number];
-/** 认得就收窄,认不出就 null(**不猜**:未知 kind 恒不下发,fail-closed 方向)。 */
-export declare function asInstructionKind(v: string): DeviceInstructionKind | null;
+/**
+ * 指令 kind ↔ core 的 FileSystem+Shell 面 1:1(§5.1;双端穷举 switch)—— **按修订号分行的增量表,是这个闭集唯一的一份来源**(与结局码同一条律):
+ * 修订号 N 的 kind 集 = 行 ≤ N 的并、按行序({@link deviceInstructionKindsAt}),{@link DEVICE_INSTRUCTION_KINDS} 是当前修订号的那一份(派生)。
+ * 汇聚端对一条连接只认它协商的修订号那一份({@link asInstructionKindAt}):executor 在 `hello.supports` 里声明了一个高于自己修订号的 kind,与声明了
+ * 一个认不出的词同读 —— 不进声明集、恒不下发。已发布修订号的行不许改(测试冻结了每个修订号的集合哈希);加 kind = 抬 {@link DEVICE_PROTOCOL_VERSION} + 加一行。
+ * 行键与 {@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION} 同一组(`satisfies` 锁:少一行 / 多一行 ⇒ 编译红)。
+ */
+export declare const DEVICE_INSTRUCTION_KINDS_BY_REVISION: {
+    readonly 1: readonly ["exec", "execStream", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile", "fileInfo", "listDir", "canonicalPath", "exists", "readLink", "createDir", "remove", "createTempDir", "createTempFile", "statBatch"];
+    readonly 2: readonly [];
+    readonly 3: readonly [];
+    readonly 4: readonly [];
+    readonly 5: readonly [];
+    /**
+     * 7.151.0:绑定读 —— 判过的那只对象就是读到的那只。协议没有跨指令的句柄,所以 `BoundFileObject` 的每一答是一条指令
+     * ({@link DeviceInstructionArgsByKind}`.openBound.op` 四选一):执行器在本机打开这条路径(叶链接不跟)、核对这只打开的对象此刻就在这条路径上
+     * (且 `identity` / `kind` 在场时等于它们)、经这一次打开作答、关掉。executor 必须实现才答得出 ⇒ 加词抬号;只派给协商修订号 ≥ 6 的连接,
+     * 修订号 5 的 executor 收不到它(受理下沿不动)。presence-typed(同 `writeFileGuarded` / `readLink`):执行器在 `hello.supports` 声明才装这一面;
+     * 没声明 ⇒ 这一面缺席(引擎不绑定读,附件不附),**不许**用 `fileInfo` + `readBinaryFile` 仿真。
+     */
+    readonly 6: readonly ["openBound"];
+};
+export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS_BY_REVISION)[DeviceProtocolRevision][number];
+/**
+ * 协议修订号 `revision` 下发的指令 kind 全集(行 ≤ revision 的并,按行序 —— 协议文档 §3.1 的表同序)。executor 按**自己声明的修订号**取这一份,
+ * 决定 `hello.supports` 里能声明哪些 kind。不是本包认得的修订号 ⇒ 抛 `RangeError`(不静默给空集或全集)。
+ */
+export declare function deviceInstructionKindsAt(revision: number): readonly DeviceInstructionKind[];
+/** 当前修订号下发的 kind 全集(派生自增量表;§3.1 的表就是它)。 */
+export declare const DEVICE_INSTRUCTION_KINDS: readonly DeviceInstructionKind[];
+/** `openBound` 指令的四个答(一个 `BoundFileObject` 成员一个;`open` 是开答)。 */
+export declare const DEVICE_BOUND_READ_OPS: readonly ["open", "size", "readBytes", "list"];
+export type DeviceBoundReadOp = (typeof DEVICE_BOUND_READ_OPS)[number];
+/**
+ * 认词 **按协商修订号**:`v` 在修订号 `revision` 的 kind 集里就收窄,不在就 null(**不猜**:高于协商修订号的 kind 与认不出的词同读,恒不下发,fail-closed 方向)。
+ * 不是本包认得的修订号 ⇒ 抛 `RangeError`(汇聚端在 hello 的版本窗之后才调它,窗外到不了这里;到了就是响亮的缺陷,不静默给全集)。
+ */
+export declare function asInstructionKindAt(v: string, revision: number): DeviceInstructionKind | null;
 /**
  * 结果帧的错误码闭集 = core 的 `FileErrorCode ∪ ExecutionErrorCode`(§5.1「error code 全闭集」:
  * 未知值映射为协议错误而非透传 string)—— **按修订号分行的增量表,是这个闭集唯一的一份来源**:
@@ -88,6 +125,7 @@ export declare const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION: {
     readonly 3: readonly ["name_too_long"];
     readonly 4: readonly ["symlink_loop"];
     readonly 5: readonly [];
+    readonly 6: readonly [];
 };
 /** 本包认得的协议修订号(= 增量表的行键)。 */
 export type DeviceProtocolRevision = keyof typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION;
@@ -151,7 +189,9 @@ export type DeviceInstructionOutcome = {
 } | {
     ok: true;
     kind: "read";
-} | {
+}
+/** `identity` 是 additive 扩键(`openBound` 开答:被打开对象的 `<dev>:<inode>`,之后每一答的对拍凭据)。 */
+ | {
     ok: true;
     kind: "stat";
     info?: WireFileInfo;
@@ -159,6 +199,7 @@ export type DeviceInstructionOutcome = {
     existsValue?: boolean;
     canonicalPath?: string;
     linkTarget?: string | null;
+    identity?: string;
 }
 /** 写面的**落盘对象收据**(§4.3.1 / core `WriteReceipt`)。`created` 是 additive 扩键(车A-4):
  *  core 的收据形要求它,缺席 = adapter 只能猜「是新建还是覆盖」,而猜出来的收据就是假收据。 */
@@ -255,6 +296,18 @@ export interface DeviceInstructionArgsByKind {
     statBatch: {
         paths: string[];
     };
+    /**
+     * 绑定读的一答。`op`:`open` ⇒ `stat` 结局带 `identity` 与 `info`(`kind` 只许 `file` / `dir`);`size` ⇒ `stat` 带 `info`(`size` = 此刻大小);
+     * `readBytes` ⇒ `read` 结局 + `data` 片(大小 > `max` ⇒ `invalid`,一个字节不读);`list` ⇒ `stat` 带 `entries`(经这只打开的目录列,链接不跟)。
+     * `identity` / `kind` 在场(开答之后的三答)⇒ 这一次打开的对象须与它们都相等,否则 `precondition_failed`;开后不在这条路径上同拒。
+     */
+    openBound: {
+        path: string;
+        op: DeviceBoundReadOp;
+        identity?: string;
+        kind?: "file" | "directory";
+        max?: number;
+    };
 }
 export type DeviceChallengeFrame = {
     t: "challenge";

package/dist/device-ws-protocol.js

@@ -1,7 +1,7 @@
 import { createPublicKey, randomBytes, randomInt, verify as edVerify } from "node:crypto";
 import { MAX_TIMER_DELAY_MS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 export const DEVICE_WS_PATH = "/v1/device/ws";
-export const DEVICE_PROTOCOL_VERSION = 5;
+export const DEVICE_PROTOCOL_VERSION = 6;
 export const DEVICE_MIN_PROTOCOL_VERSION = 5;
 const DEVICE_FLOOR_CHANGE = 'since server 7.150.0 every path an instruction carries (args.path, args.paths, cwd) arrives unfolded, with "." / ".." / empty segments kept for the device\'s filesystem to resolve';
 export function deviceProtocolRevisionRefusal(declared) {
@@ -24,30 +24,54 @@ export const DEVICE_GOODBYE_REASONS = ["shutdown", "sleep", "user_stop"];
 export const DEVICE_CHUNK_KINDS = ["stdout", "stderr", "data", "exit"];
 export const DEVICE_CANCEL_STATES = ["not_started", "killed"];
 export const DEVICE_INSTRUCTION_STATES = ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
-export const DEVICE_INSTRUCTION_KINDS = [
-    "exec",
-    "execStream",
-    "readTextFile",
-    "readTextLines",
-    "readBinaryFile",
-    "writeFile",
-    "writeFileExclusive",
-    "writeFileGuarded",
-    "appendFile",
-    "fileInfo",
-    "listDir",
-    "canonicalPath",
-    "exists",
-    "readLink",
-    "createDir",
-    "remove",
-    "createTempDir",
-    "createTempFile",
-    "statBatch",
-];
-const INSTRUCTION_KIND_SET = new Set(DEVICE_INSTRUCTION_KINDS);
-export function asInstructionKind(v) {
-    return INSTRUCTION_KIND_SET.has(v) ? v : null;
+export const DEVICE_INSTRUCTION_KINDS_BY_REVISION = {
+    1: [
+        "exec",
+        "execStream",
+        "readTextFile",
+        "readTextLines",
+        "readBinaryFile",
+        "writeFile",
+        "writeFileExclusive",
+        "writeFileGuarded",
+        "appendFile",
+        "fileInfo",
+        "listDir",
+        "canonicalPath",
+        "exists",
+        "readLink",
+        "createDir",
+        "remove",
+        "createTempDir",
+        "createTempFile",
+        "statBatch",
+    ],
+    2: [],
+    3: [],
+    4: [],
+    5: [],
+    6: ["openBound"],
+};
+export function deviceInstructionKindsAt(revision) {
+    if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {
+        throw new RangeError(`device-ws: no instruction-kind set for protocol revision ${String(revision)} (this package knows revisions 1..${DEVICE_PROTOCOL_VERSION})`);
+    }
+    const out = [];
+    for (const [rev, kinds] of Object.entries(DEVICE_INSTRUCTION_KINDS_BY_REVISION)) {
+        if (Number(rev) <= revision)
+            out.push(...kinds);
+    }
+    return out;
+}
+export const DEVICE_INSTRUCTION_KINDS = deviceInstructionKindsAt(DEVICE_PROTOCOL_VERSION);
+export const DEVICE_BOUND_READ_OPS = ["open", "size", "readBytes", "list"];
+const INSTRUCTION_KIND_SETS = new Map(Object.keys(DEVICE_INSTRUCTION_KINDS_BY_REVISION).map((rev) => [Number(rev), new Set(deviceInstructionKindsAt(Number(rev)))]));
+export function asInstructionKindAt(v, revision) {
+    const kinds = INSTRUCTION_KIND_SETS.get(revision);
+    if (kinds === undefined) {
+        throw new RangeError(`device-ws: no instruction-kind set for protocol revision ${String(revision)} (this package knows revisions 1..${DEVICE_PROTOCOL_VERSION})`);
+    }
+    return kinds.has(v) ? v : null;
 }
 export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
     1: [
@@ -75,6 +99,7 @@ export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
     3: ["name_too_long"],
     4: ["symlink_loop"],
     5: [],
+    6: [],
 };
 export function deviceOutcomeErrorCodesAt(revision) {
     if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {
@@ -232,6 +257,12 @@ function parseOutcome(v) {
                     return null;
                 out.linkTarget = v.linkTarget;
             }
+            if (v.identity !== undefined) {
+                const id = str(v.identity);
+                if (id === null)
+                    return null;
+                out.identity = id;
+            }
             return out;
         }
         case "write": {

package/dist/engine-identity.d.ts

@@ -5,9 +5,11 @@
  * 与本仓的人面汇点同轴);`isolationScope` = **带场景的主体**(只在请求带了场景时有;引擎按它分登记域 / offload 租界 / 后台登记 / peer 目录 / 工作流 scope,
  * 引擎的读法是「隔离格缺席 ⇒ 读 `principal`」)。没带场景的请求只有 `principal`,与今天逐字节同。检查点的分区走本仓自己供的 `scope` 格。
  *
- * 今天的引擎还没有隔离格:{@link taskSpecIdentityOf} 是**唯一的落点**,今天只写 `principal`;隔离格到货后改那一行(钉在 `test/scenario-subject.test.ts`)。
- * 落点之前引擎自己按 `spec.principal` 分的那几面按人分(同一个人的各场景在那几面互见)—— 本仓镜像这几面的读口(工作流读面、后台登记簿的停止标记、
- * leader 子任务的 spec)同读 {@link taskSpecIdentityOf},读到的就是引擎写下的那一个值,不各写一份。
+ * 今天的引擎还没有隔离格:{@link taskSpecIdentityOf} 是**唯一的落点**,今天只写 `principal`;隔离格到货后改那一行(钉在 `test/scenario-subject.test.ts`),
+ * {@link engineScopeOf} 同一提交换读(钉在 `test/workflow-scope-core-parity.test.ts`)。
+ * 落点之前引擎自己按 `spec.principal` 分的那几面按人分(同一个人的各场景在那几面互见)。本仓读这几面(工作流行的 `scope` 列、后台登记簿与它的停止标记、
+ * 会话信箱盒与被扣来信的队列、名册)时「一只主体 ⇒ 那一格 scope」只有一只换算 {@link engineScopeOf},读到的就是引擎写下的那一个值,不各写一份;
+ * leader 子任务与提交腿的 spec 同经落点 {@link taskSpecIdentityOf}。
  */
 import { type Person, type Subject, type SubjectParts } from "./owner-brands.js";
 /** 引擎交界的身份(本仓的类型;二元)。 */
@@ -20,15 +22,25 @@ export interface EngineIdentity {
 export declare function specIdentityOf(parts: SubjectParts | undefined): EngineIdentity;
 /**
  * 落进 `TaskSpec` 的身份格(**唯一落点**)。今天的引擎没有隔离格 ⇒ 只写 `principal`,`isolationScope` 在这里不落(引擎按人分它自己的那几面);
- * 引擎的隔离格到货 ⇒ 这里加一格,别处不动。
+ * 引擎的隔离格到货 ⇒ 这里加一格,同一提交里 {@link engineScopeOf} 改读 core 的 `isolationScopeOf`(身份格闭集型在那里编译红,逼读法表态),别处不动。
  */
 export declare function taskSpecIdentityOf(parts: SubjectParts | undefined): {
     readonly principal?: string;
 };
 /**
- * 引擎按身份分的那几面落下的 **scope**(core 写侧 `spec.principal ?? "default"` 的同一条读法;工作流行的 `scope` 列就是它):一只主体 ⇒ 落点 {@link taskSpecIdentityOf}
- * 写下的人;匿名 ⇒ 单机形的租户键 `"default"`(`owner-faces.ts` 的 `LEGACY_UNOWNED_AMNESTY_TENANT`)。读者只在属主存取器(`http/owner-access.ts`):工作流按 id 的门
- * (调用方一侧按它换成引擎身份再与行的 scope 比)与工作流列表的属主过滤同读这一只;承认之后 journal / 流按承认的那一行的 scope 读。
+ * 🔴 **一只主体在引擎按身份分的那几面上的 scope —— 唯一一只换算**(工作流行的 `scope` 列 / 后台登记簿 / 会话信箱盒与被扣来信的队列 / 停止标记 / 名册:
+ * 引擎写下它们时用的那一个值)。规则 = core 写侧那一条,落在本仓交给引擎的身份格({@link taskSpecIdentityOf})上 ⇒ {@link scopeOfLanded}:
+ *  · core 7.66.0(本仓钉的版本):工作流行 `scope` = `ctx.principal ?? 挂载 scope`(`createRunWorkflowTool` 的 `execute` 里的 `taskScope`;`startWorkflow` 缺席落
+ *    `"default"`)—— `ctx.principal` 是 Runner 填的 `spec.principal`;挂载 scope 与后台登记簿 / 被扣来信队列同一个量,即 Runner 准备任务时算的任务 scope
+ *    `registryScope ?? spec.principal ?? "default"`(同一个值挂进 `run_workflow`、交给信箱排空腿开 held 队列)。本仓不供 `registryScope` ⇒ 各面同值 = 落下的
+ *    `principal`,匿名 = `"default"`。
+ *  · core 的下一形([ref] 隔离格随 7.68.0 到货;[ref] 同版根导出 `callScopeOf` / `isolationScopeOf`):`callScopeOf(ctx, 挂载) = ctx.isolationScope ?? 挂载.scope`,
+ *    Runner 把 `ctx.isolationScope` 填成 `isolationScopeOf(spec) = spec.isolationScope || spec.principal`;落点只写 `principal` 时两形同值。
+ * **随 core [ref] 到货换读、退本读法**:提货车让落点写出隔离格的同一提交里,这里改读 core 根导出的 `isolationScopeOf`(落下的身份格 ⇒ `?? "default"`),
+ * {@link scopeOfLanded} 退役 —— 落点多一格而读法没表态 = 编译红(身份格闭集,见它)。真 core 对拍钉:`test/workflow-scope-core-parity.test.ts`。
+ * 工作流行「归谁」只在属主存取器经它判(`http/owner-access.ts` 的 `workflowScopeOf`:列表 / 按 id / 舰队流同读)。
  */
 export declare function engineScopeOf(subject: Subject | undefined): string;
+/** 一只**持久的**属主串(会话 / run 行的属主列、续跑腿交来的属主、请求鉴权句柄的纯串主体)在那几面上的 scope:先过内部恢复管线,再经 {@link engineScopeOf};无主 ⇒ 匿名那一格。 */
+export declare function engineScopeOfOwner(owner: string | null | undefined): string;
 //# sourceMappingURL=engine-identity.d.ts.map

package/dist/engine-identity.js

@@ -1,5 +1,5 @@
 import { partsOf } from "./owner-brands.js";
-import { LEGACY_UNOWNED_AMNESTY_TENANT } from "./owner-faces.js";
+import { LEGACY_UNOWNED_AMNESTY_TENANT, recoveredSubject } from "./owner-faces.js";
 export function specIdentityOf(parts) {
     if (parts === undefined)
         return { principal: undefined };
@@ -10,6 +10,14 @@ export function taskSpecIdentityOf(parts) {
     return principal === undefined ? {} : { principal };
 }
 export function engineScopeOf(subject) {
-    return taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? LEGACY_UNOWNED_AMNESTY_TENANT;
+    return scopeOfLanded(taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)));
+}
+export function engineScopeOfOwner(owner) {
+    return engineScopeOf(recoveredSubject(owner));
+}
+function scopeOfLanded(landed) {
+    const { principal, ...unread } = landed;
+    unread;
+    return principal ?? LEGACY_UNOWNED_AMNESTY_TENANT;
 }
 //# sourceMappingURL=engine-identity.js.map