@sema-agent/server 7.138.0 → 7.139.0

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { type Model, type PathRuleBases, type PermissionRule } from "@sema-agent/core";
+import { type ConfigProviderWord } from "./config-types.js";
 import { type CenterEndpoint } from "./web-admin-client/center-request.js";
 import { type Autonomy } from "./runtime-governance.js";
 import { type RunnerEnvNameAllowlistKnob, type ServerEnvNameAllowlistKnob } from "./env-name-allowlist-knobs.js";
@@ -106,6 +107,19 @@ export interface ConfigNotice {
     fields: Record<string, string>;
 }
 export declare function drainConfigNotices(): ConfigNotice[];
+/**
+ * [ref] —— `CONFIG_PROVIDER` 的**唯一**读点。闭集 {@link CONFIG_PROVIDER_WORDS};缺席 / 空串 ⇒ 未表态(`undefined`);
+ * 其余一律**拒启**,拒因句列合法词。逐字比较(不 trim、不折大小写)—— 与本仓其余闭集 env 同律([ref]:认不出的词
+ * 不许被悄悄猜成某一种意思)。
+ *
+ * 修前这根旋钮是开放词,而一个认不出的词在同一进程里被读成两种意思:配置源判官(`configProviderKind`)把它当 `local`
+ * (读 `config.d/`、执行车道合成步照读 `remote-exec.json`),这里的隐式 host 臂与车道落点披露却按字面 `=== "local"`
+ * 判它**不是** local;web-admin 工厂同样按字面只在 `"local"` 上递本地根,于是配置源的根落回 `process.cwd()`、
+ * 合成步读的是 `localRoot` —— 两个根分家。收成闭集 + 一个读点之后,这三处读的是同一个值。
+ * 调用方两处、读的是同一张闭集:`loadConfig` 开头一次;`run-local` 在 `loadConfig` 之前一次(本入口只装本地配置源,词是 `remote` 就在这里拒 ——
+ * 配没配中心地址都一样)。
+ */
+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
@@ -212,6 +226,25 @@ export declare function configKnobTable(): ConfigKnobRecord[];
 export declare const hostBackgroundShellEnabled: () => boolean;
 /** The `host` exec lane's spool-file stdio form; false ⇒ the pre-1.226 pipe fallback (read per exec). */
 export declare const hostExecSpoolEnabled: () => boolean;
+/** 名单在活配置里的落点(服务进程四只旋钮;bake-runner 那只在它自己的进程里,不在 `ServiceConfig`)。 */
+export type EnvNameAllowlistSeats = Pick<ServiceConfig, "lspEnvAllow" | "remoteExec">;
+/**
+ * 沙箱名单(表列 `channel: "sandbox-grant"` 的服务侧旋钮,表派生)此刻交出去的名 —— 起服行 `remote_exec_enabled.sandboxEnvKeys` 读它(`boot/execution-env.ts`,
+ * 排序后只出键名)。只有被选中车道的那一只有落点;e2b / k8s 报的是名单点到的键,不含 `SANDBOX_PKG_SOURCE` 推导出的包源变量(那一组是区域常量,装配点另并)。
+ */
+export declare function sandboxEnvNamesInForce(seats: EnvNameAllowlistSeats): readonly string[];
+/** 声明增长后重判的一处命中:哪只旋钮、它交出去的哪个名、判官的拒因({@link ownCredentialNameProblem} 那一句,只回显名)。 */
+export interface OwnCredentialInForce {
+    readonly knob: ServerEnvNameAllowlistKnob;
+    readonly name: string;
+    readonly problem: string;
+}
+/**
+ * 解析器头注 ② 那条不变量在**声明增长**那一刻的半边:对活配置里每只名单此刻交出去的名问**同一只**判官({@link ownCredentialNameProblem} → 引擎
+ * `inheritEnvPolicyProblem`,读引擎此刻的声明)。读活配置的落点,不重读 env(名单是起服输入;解析那一刻已判过形与当时的声明)。返回每一处命中,空 = 不相交。
+ * 调用点只有一处 = 声明增长的那一处(`apply-effective.ts` 的换代声明,真声明之后、席位换装之前)。
+ */
+export declare function ownCredentialHitsInForce(seats: EnvNameAllowlistSeats): OwnCredentialInForce[];
 /** 名单型 env 旋钮的**唯一**解析器(规则全文见上方 `ENV_NAME_ALLOWLIST_KNOBS` 头注)。`undefined` = 没配(未设 / 空串)。
  *  服务侧旋钮要交本进程的姿态(③);runner 旋钮没有姿态,签名上就不收 —— 读者与行形由叶表的类型一起定,传错是编译红。 */
 export declare function parseEnvNameAllowlist(knob: ServerEnvNameAllowlistKnob, singleUserTurnkey: boolean): readonly string[] | undefined;

package/dist/config.js

@@ -9,6 +9,7 @@ import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { buildRuleListJudgeOptions } from "./permission-rule-list.js";
 import { isV2ScopeKey, memoryReplicationCoverage, replicatesProjectLayersOf } from "./memory-scope.js";
+import { memorySyncPeerOf } from "./memory-sync-client.js";
 import { assertProjectLayerOwnable } from "./project-identity.js";
 import { projectLayerOwnerOf } from "./project-layer-key.js";
 import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
@@ -26,7 +27,7 @@ import { THINKING_LEVELS, THINKING_FORMATS, buildModelCompat, isThinkingFormat,
 import {} from "./posture-source.js";
 import { COST_QUOTA_WINDOW_SEC_RANGE, costQuotaWindowSecInRange } from "./observability/cost-quota.js";
 import { NAME_TABLE_BEHAVIOR, TOOL_NAME_ROSTER, describeUnmatchableRuleName, ruleEntryToolName, unmatchableRuleNameOf } from "./namespaced-rule-name.js";
-import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, workflowParkDecisionDomainRefusal } from "./config-invariants.js";
+import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, remoteConfigProviderUrlRefusal, retentionLaneRefusal, workflowParkDecisionDomainRefusal } from "./config-invariants.js";
 import { declaredSemaConfigDir } from "./sema-config-dir.js";
 import { lkgPathOverrideOf } from "./config-lkg.js";
 import { K8S_WORKSPACE_MOUNT_DEFAULT, WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_RANGE, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE, parseWorkspaceSnapshotExclude, parseWorkspaceSnapshotPrefix } from "./workspace-space.js";
@@ -35,7 +36,7 @@ import { laneLivenessOf } from "./exec-bounds.js";
 import { SANDBOX_IPV6_DEFAULT, SANDBOX_IPV6_WORDS } from "./sandbox-egress-policy.js";
 import { WORKSPACE_CACHE_DEFAULT, WORKSPACE_CACHE_MOUNT_DEFAULT, WORKSPACE_CACHE_MOUNT_RESERVED, WORKSPACE_CACHE_SIZE_DEFAULT, WORKSPACE_CACHE_WORDS, isK8sQuantity, mountsOverlap, reservedMountCollision } from "./workspace-cache.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
-import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, laneRequiredEnv } from "./execution-lane-caps.js";
+import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, laneMissingEnv } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
 import { AUTONOMY_MODES } from "./runtime-governance.js";
 import { MAX_NAMED_INERT_ENTRIES, allowLayerEntryCountIssue, describeInertRuleEntries, inertRuleEntriesOf, inertRuleEntryGuidance, ruleEntryListShapeOk } from "./rule-entry-list.js";
@@ -195,7 +196,7 @@ function buildExecLaneNotice(remoteExec) {
     };
 }
 const ENV_VALUE_ECHO_CHARS = 120;
-function parseConfigProvider() {
+export function parseConfigProvider() {
     const raw = process.env.CONFIG_PROVIDER;
     if (raw === undefined || raw === "")
         return undefined;
@@ -509,11 +510,32 @@ function parseNameListEnv(name, raw, opts) {
 }
 const ENV_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ENV_NAME_ALLOWLIST_WITHHELD = "<withheld: entries are not echoed — a value pasted in place of a name can pass the name check>";
-function ownCredentialPutBackProblem(name) {
+const OWN_CREDENTIAL_HANDOFF = {
+    "host-put-back": { where: "a put-back list hands the named variable back, as written, to the child the engine withheld it from", whom: "that child" },
+    "sandbox-grant": { where: "a sandbox list puts the named variable, as written, into a sandbox the model can read", whom: "the sandbox" },
+};
+function ownCredentialNameProblem(name, channel) {
     const engine = inheritEnvPolicyProblem([name]);
-    return engine === undefined
-        ? undefined
-        : `this deployment's own credential — a put-back list hands the named variable back, as written, to the child the engine withheld it from (the engine refuses it on any allow list: ${engine})`;
+    if (engine === undefined)
+        return undefined;
+    const { where, whom } = OWN_CREDENTIAL_HANDOFF[channel];
+    return `this deployment's own credential — ${where}; give ${whom} a credential of its own (another name and another value) and list that name instead (the engine refuses it on any allow list: ${engine})`;
+}
+const NAMES_IN_FORCE = {
+    LSP_ENV_ALLOW: (c) => c.lspEnvAllow,
+    E2B_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "e2b" ? Object.keys(c.remoteExec.sandboxEnv ?? {}) : []),
+    K8S_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "k8s" ? Object.keys(c.remoteExec.sandboxEnv ?? {}) : []),
+    DOCKER_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "local-docker" ? Object.keys(c.remoteExec.env ?? {}) : []),
+};
+const SERVER_ENV_NAME_ALLOWLIST_KNOBS = Object.keys(NAMES_IN_FORCE);
+export function sandboxEnvNamesInForce(seats) {
+    return SERVER_ENV_NAME_ALLOWLIST_KNOBS.filter((knob) => ENV_NAME_ALLOWLIST_KNOBS[knob].channel === "sandbox-grant").flatMap((knob) => NAMES_IN_FORCE[knob](seats));
+}
+export function ownCredentialHitsInForce(seats) {
+    return SERVER_ENV_NAME_ALLOWLIST_KNOBS.flatMap((knob) => NAMES_IN_FORCE[knob](seats).flatMap((name) => {
+        const problem = ownCredentialNameProblem(name, ENV_NAME_ALLOWLIST_KNOBS[knob].channel);
+        return problem === undefined ? [] : [{ knob, name, problem }];
+    }));
 }
 export function parseEnvNameAllowlist(knob, singleUserTurnkey) {
     const raw = process.env[knob];
@@ -528,9 +550,7 @@ export function parseEnvNameAllowlist(knob, singleUserTurnkey) {
                 ? 'not an environment-variable name (letters, digits and "_", not starting with a digit)'
                 : ENV_NAME_ALLOWLIST_KNOB_NAMES.has(seg.toUpperCase())
                     ? `the name of a name-list knob (${[...ENV_NAME_ALLOWLIST_KNOB_NAMES].join(" / ")}: their raw text is withheld from every child process and sandbox; naming one would put that text back)`
-                    : spec.channel === "host-put-back"
-                        ? ownCredentialPutBackProblem(seg)
-                        : undefined;
+                    : ownCredentialNameProblem(seg, spec.channel);
         if (problem === undefined)
             return;
         throw new Error(`env ${knob}: entry #${i + 1} of ${segments.length} is ${problem}` +
@@ -1704,6 +1724,7 @@ function parseMemoryDomain(ctx) {
         if (memorySyncToken === undefined) {
             throw new Error("MEMORY_SYNC_URL is set but MEMORY_SYNC_TOKEN is not — refusing to start half-configured (the central sync face requires a bearer token)");
         }
+        memorySyncPeerOf(memorySyncUrl);
         if (memorySyncScopeRaw === undefined && memoryScope !== undefined && !isV2ScopeKey(memoryScope)) {
             throw new Error(`MEMORY_SYNC_URL is set but MEMORY_SYNC_SCOPE is not set and MEMORY_SCOPE (${JSON.stringify(memoryScope)}) is not a typed scope key — the sync leg replicates exactly ONE scope by name ` +
                 "(core syncMemoryScope takes the entries whose scope === the sync scope and POSTs them under that same name), so deriving `user:<MEMORY_SCOPE>` would name a scope this deployment never writes and nothing would ever be synced (S-964). " +
@@ -1902,10 +1923,10 @@ function parseOrchestrationDomain(ctx) {
                 throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: ${REMOTE_EXEC_PROVIDER_WORDS.join(" | ")}. ` +
                     `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
             }
-            const missing = laneRequiredEnv(word).filter((name) => !process.env[name]);
+            const missing = laneMissingEnv(word, process.env);
             if (missing.length > 0) {
-                throw new Error(`REMOTE_EXEC=${lane} but required env ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} missing/empty — ` +
-                    `refusing to start rather than silently downgrading to the host/in-process lane (#157; unset REMOTE_EXEC if you meant no sandbox lane).`);
+                throw new Error(`REMOTE_EXEC=${lane} but required env ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} unset, empty or whitespace-only — it counts as absent: ` +
+                    `refusing to start rather than silently downgrading to the host/in-process lane (#157; set ${missing.length === 1 ? "it" : "them"}, or unset REMOTE_EXEC if you meant no sandbox lane).`);
             }
         }
     }
@@ -1951,7 +1972,7 @@ function parseOrchestrationDomain(ctx) {
                 orphanReclaim: boolEnv("E2B_ORPHAN_RECLAIM", true),
             }
             :
-                process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE
+                process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE && process.env.K8S_NAMESPACE
                     ? {
                         provider: "k8s",
                         image: process.env.K8S_SANDBOX_IMAGE,
@@ -1959,7 +1980,7 @@ function parseOrchestrationDomain(ctx) {
                         ...(process.env.K8S_TOKEN ? { token: process.env.K8S_TOKEN } : {}),
                         ...(process.env.K8S_CA_CERT_B64 ? { caCert: Buffer.from(process.env.K8S_CA_CERT_B64, "base64").toString("utf8") } : {}),
                         ...(boolEnv("K8S_INSECURE_TLS", false) ? { insecureTls: true } : {}),
-                        ...(process.env.K8S_NAMESPACE ? { namespace: process.env.K8S_NAMESPACE } : {}),
+                        namespace: process.env.K8S_NAMESPACE,
                         ...(process.env.K8S_RUNTIME_CLASS != null ? { runtimeClass: process.env.K8S_RUNTIME_CLASS } : {}),
                         ...(process.env.K8S_MOUNT_PATH ? { mountPath: process.env.K8S_MOUNT_PATH } : {}),
                         ...((n) => (n !== undefined ? { timeoutMs: n } : {}))(optNumEnvStrict("K8S_TIMEOUT_MS")),
@@ -2602,6 +2623,14 @@ export function loadConfig() {
     if (centerIdentity !== undefined) {
         throw new Error(centerIdentity);
     }
+    const remoteSourceRefusal = remoteConfigProviderUrlRefusal({ configProvider: integrations.configProvider, webAdmin: integrations.webAdmin });
+    if (remoteSourceRefusal !== undefined) {
+        throw new Error(remoteSourceRefusal);
+    }
+    const retentionRefusal = retentionLaneRefusal({ retentionPolicy: auth.retentionPolicy, retentionSweep: auth.retentionSweep });
+    if (retentionRefusal !== undefined) {
+        throw new Error(retentionRefusal);
+    }
     const { directApprovalDoor, durableApproval: dgDurable, approvalHmacKeys: dgHmacKeys } = approval;
     const { principalJwtPubkeys, principalJwtIss, principalJwtAud, operatorPrincipals: dgOperators, operatorSingleUser, authTokens } = auth;
     const directDoorActive = directApprovalDoor && dgDurable && dgHmacKeys.length > 0 && principalJwtPubkeys.length > 0 && !!principalJwtIss && !!principalJwtAud;

package/dist/delegated-session-owner.d.ts

@@ -38,7 +38,7 @@
  *    M23 回填了无主的父)⇒ 写下的仍是判断时的读数 —— 按律如此;那一行若因此无主,照上一节处置。
  *  · **停驻挂点**(`plugins/session-store.ts` 的 `ensureChildSessionDurableWithPromotion`;快路 + 晋升):来源 = **调用方交出的委派树根,只有这一只**,连同
  *    调用方判断那一刻读到的根行住客({@link DelegationRootWitness};见证值,判断用,不进 CAS):请求腿 = 本请求经鉴权解析的会话,住客 = 受理时那一读
- *    (`boot/resolve-spec.ts`);`/decide` 的赎回腿 = 行上的 `rootSessionId`,住客 = 赎回腿 claim 前后两读的那一位(`parked-revive-surface.ts`,每一行都交)。
+ *    (`boot/resolve-spec.ts`);`/decide` 的赎回腿 = 行上的 `rootSessionId`,住客 = 赎回腿写口放行的那一位(认领之前解析器那一读;`parked-revive-surface.ts`,每一行都交)。
  *    挂点先读一次根行:它在而住客不是见证的那一位 ⇒ 根被删、同 id 换了住客 ⇒ **拒**(不按新住客晋升 / 认领,{@link assertRootStillWitnessed});它不在 ⇒ 律给哨兵
  *    (根真没了)。不回落父:core 的挂点 `ensureChildSessionDurable(sessionId)` 只交子代 id,父 id 在这一写点拿不到;两条候选读法都读不到东西 ——
  *    ① 读 `session_meta(子代).placement_parent_session_id`:晋升的拷贝分支恰恰只在子代**没有** placed 行时才走(有 placed 行 ⇒ 快路),这一列按构造为空;
@@ -134,7 +134,7 @@ export interface PlacedRowWriter {
 export declare function createPlacedSessionRow(sessionId: string, placement: PlacementSources, io: PlacedRowWriter, log: OrphanOwnerLog): Promise<void>;
 /**
  * 停驻挂点的**见证**:调用方交出的委派树根 + 调用方判断那一刻读到的根行住客(化身;`null` = 那一读里根行不在)。请求腿 = 鉴权解析的会话与受理时那一读;
- * 赎回腿 = 行上的根与 claim 前后两读的那一位住客。
+ * 赎回腿 = 行上的根与写口放行的那一位住客(认领之前解析器那一读)。
  */
 export interface DelegationRootWitness {
     readonly sessionId: string;

package/dist/deployment-shape.d.ts

@@ -92,7 +92,7 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。
      */
     multiTenant: DeploymentShapePredicate<"principal">;
-    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由 `device_session` 绑定验过,不要求单主)。 */
+    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由根会话行执行格上的设备绑定验过,不要求单主)。 */
     callerCwd: DeploymentShapePredicate<"lane" | "principal">;
     /** 调用方给的宿主绝对路径(附加目录 / 项目上下文 / 本机 SendUserFile / 指令文件探针)只在「手就在本 worker 的盘上 ∧ 单主」时指向调用方自己的东西。 */
     callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;

package/dist/device-enrollment.d.ts

@@ -18,12 +18,21 @@
  * 上是**同一个** `device.enrollment_invalid`;设备读面的「不存在」与「不是你的」是同一个
  * `not_found.device`。细分只进审计。
  *
+ * ── 绑定从哪读(一只读)─────────────────────────────────────────────────────────────────────────────
+ * 根会话 ↔ 设备的绑定是根会话行上这一位住客的执行格 writer(device, D)(`execution-placement.ts` 头注)。准入链**不另读**:
+ * 读只有会话店的执行席 `seat.read(root)` 一只({@link DeviceEnrollment.readPlacement},装配点把会话店的执行席交进来 ——
+ * device 车道只在 SQL 后端 ⇒ 席恒在,缺 ⇒ 装配期响亮抛);{@link DeviceEnrollment.admitSession} 判的是调用方交进来的**那一读**,
+ * 于是提交意图「判已绑 / 未绑」与它记下的住客出自同一次行读。「这一格放在哪台设备上」只有一种读法 `boundDeviceOf`。
+ *
  * ── 吊销在途语义(§8-R4)──────────────────────────────────────────────────────────────────────────
  * `revoked` 是终态:①绑定的 session 后续提交 = `device.revoked`(admitSession 步 2,**先于** presence
  * 判定);②吊销同事务把连接租约作废并把 `conn_generation` 推进一格 ⇒ 在途连接的每一次带世代谓词的写
  * 都会影响 0 行,设备侧因此立刻失权(§4.6 步 2);③重新 enrollment = 新 deviceId,不复活旧行。
  */
-import { type DeviceErrorCode, type DeviceOwner, type DeviceRejectCode, type DeviceEnrollTokenRow, type DeviceRow, type DeviceSessionRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+import { type DeviceErrorCode, type DeviceOwner, type DeviceRejectCode, type DeviceEnrollTokenRow, type DeviceRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+import { type ExecutionDeviceCell, type ExecutionPlacementReading, type ExecutionPlacementSeat } from "./execution-placement.js";
+import type { ExecutionLane } from "./execution-lane-caps.js";
+import type { SessionFace } from "./session-incarnation.js";
 /** typed 拒绝 —— 端点层只负责把它翻成 HTTP(status 已在体内,不许调用方另算)。 */
 export interface DeviceRejection {
     /** [ref]:含两个借用位(`limit.rate_exceeded` 429 / `draining` 503);enrollment 本文件只铸前者,
@@ -68,10 +77,34 @@ export interface EnrollDeviceValue {
 }
 export interface AdmitSessionInput {
     rootSessionId: string;
+    /** 调用方读的**那一读**(会话店执行席 `seat.read(rootSessionId)` 的答案,经 {@link DeviceEnrollment.readPlacement})—— 准入链只判它,不另读。 */
+    placement: ExecutionPlacementReading | undefined;
     requester: DeviceOwner;
     /** 提交体携带的 deviceId(§4.3.2:仅根任务携;缺席 = 沿用绑定)。 */
     requestedDeviceId?: string;
 }
+/**
+ * 首绑({@link DeviceEnrollment.bindPlacement})的结果:成立(`device` = 落下的格)、设备闭集的 typed 拒(异设备 `device.claim_conflict` /
+ * 设备 404 / 已吊销),或会话行那一侧的三种结局 —— 住客不是判过的那一位 / 行不在(`gone`)、写者在别处(`mirror`)、格在别的车道上(`tree_bound`)。
+ * 后三者不在设备闭集里(它们说的是会话,不是设备),由提交点(`http/execution-context.ts` 的 `commitExecutionContext`)各答各的码。
+ */
+export type BindPlacementOutcome = {
+    readonly ok: true;
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly ok: false;
+    readonly reject: DeviceRejection;
+} | {
+    readonly ok: false;
+    readonly placement: "gone";
+} | {
+    readonly ok: false;
+    readonly placement: "mirror";
+} | {
+    readonly ok: false;
+    readonly placement: "tree_bound";
+    readonly boundLane: ExecutionLane;
+};
 export interface AdmitSessionValue {
     deviceId: string;
     device: DeviceRow;
@@ -110,11 +143,15 @@ export interface DeviceEnrollment {
     /** §7-T5 五件的第 ①②③ 件的**写入侧**:绑定复合身份 + TTL + 一次性摘要落库(明文一现)。 */
     issueEnrollToken(input: IssueEnrollTokenRequest): Promise<DeviceOutcome<IssuedEnrollToken>>;
     enroll(input: EnrollDeviceInput): Promise<DeviceOutcome<EnrollDeviceValue>>;
+    /** 绑定的唯一读:会话店执行席的 `read(root)`(一次行读:住客 + 格;行不在 ⇒ `undefined`;读故障抛,不吞成「未绑」)。 */
+    readPlacement(rootSessionId: string): Promise<ExecutionPlacementReading | undefined>;
+    /** 首绑(认领之后的初始放置写):按意图那一读的住客定址,设备店一只事务。 */
     bindPlacement(input: {
         rootSessionId: string;
+        occupant: SessionFace;
         deviceId: string;
         requester: DeviceOwner;
-    }): Promise<DeviceOutcome<DeviceSessionRow>>;
+    }): Promise<BindPlacementOutcome>;
     admitSession(input: AdmitSessionInput): Promise<DeviceOutcome<AdmitSessionValue>>;
     revoke(input: {
         deviceId: string;
@@ -125,6 +162,8 @@ export interface DeviceEnrollment {
 }
 export interface DeviceEnrollmentDeps {
     store: DeviceStore;
+    /** 会话店的执行席(绑定的唯一载体与唯一读;装配点交会话店的 `executionPlacement`)。 */
+    seat: ExecutionPlacementSeat;
     /** 缺席 = 不限速(端点车必须传;见文件头注 ⑤)。 */
     rateLimiter?: DeviceEnrollRateLimiter;
     /** 测试可注入确定性铸造;默认 `mintDeviceId()`。 */

package/dist/device-enrollment.js

@@ -1,4 +1,5 @@
 import { DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, DEVICE_RATE_LIMIT_CODE, assertDeviceIdShape, assertDeviceOwnerShape, assertDevicePubkeyShape, assertEnrollTokenHashShape, assertRootSessionIdShape, hashEnrollToken, mintDeviceId, mintEnrollToken, } from "./device-store.js";
+import { boundDeviceOf } from "./execution-placement.js";
 export const DEFAULT_ENROLL_TOKEN_TTL_SEC = 900;
 export function buildDeviceRejection(errorCode, message) {
     return { code: errorCode, status: DEVICE_ERROR_STATUS[errorCode], message };
@@ -13,7 +14,7 @@ function rejectNotFound() {
     return reject(DEVICE_ERROR_CODES.NOT_FOUND, "device not found");
 }
 export function createDeviceEnrollment(deps) {
-    const { store } = deps;
+    const { store, seat } = deps;
     const mintId = deps.mintId ?? mintDeviceId;
     async function rateGate(key) {
         if (!deps.rateLimiter)
@@ -87,21 +88,35 @@ export function createDeviceEnrollment(deps) {
                 return rejectEnrollment();
         }
     }
+    async function readPlacement(rootSessionId) {
+        assertRootSessionIdShape(rootSessionId);
+        return seat.read(rootSessionId);
+    }
     async function bindPlacement(input) {
         assertRootSessionIdShape(input.rootSessionId);
         assertDeviceIdShape(input.deviceId);
         assertDeviceOwnerShape(input.requester);
-        const result = await store.bindSession({ rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.requester });
+        const result = await store.placeDeviceExecution({ root: input.rootSessionId, occupant: input.occupant, deviceId: input.deviceId, owner: input.requester });
         switch (result.outcome) {
             case "bound":
-            case "idempotent":
-                return { ok: true, value: result.row };
-            case "conflict":
+            case "same":
+                return { ok: true, device: result.device };
+            case "device_conflict":
                 return reject(DEVICE_ERROR_CODES.CLAIM_CONFLICT, "this session is already bound to a different device");
             case "device_not_found":
                 return rejectNotFound();
             case "device_revoked":
                 return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+            case "gone":
+                return { ok: false, placement: "gone" };
+            case "mirror":
+                return { ok: false, placement: "mirror" };
+            case "tree_bound":
+                return { ok: false, placement: "tree_bound", boundLane: result.boundLane };
+            default: {
+                const unhandled = result;
+                throw new Error(`bindPlacement: unknown store outcome ${JSON.stringify(unhandled)}`);
+            }
         }
     }
     async function admitSession(input) {
@@ -109,22 +124,22 @@ export function createDeviceEnrollment(deps) {
         assertDeviceOwnerShape(input.requester);
         if (input.requestedDeviceId !== undefined)
             assertDeviceIdShape(input.requestedDeviceId);
-        const binding = await store.getSessionBinding(input.rootSessionId);
-        if (!binding)
+        const bound = input.placement === undefined ? undefined : boundDeviceOf(input.placement.cell);
+        if (!bound)
             return reject(DEVICE_ERROR_CODES.NOT_BOUND, "this session has no device binding");
-        if (binding.owner.tenant !== input.requester.tenant || binding.owner.subject !== input.requester.subject)
+        if (bound.owner.tenant !== input.requester.tenant || bound.owner.subject !== input.requester.subject)
             return rejectNotFound();
-        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== binding.deviceId) {
+        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== bound.id) {
             return reject(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, "the requested device is not the one bound to this session");
         }
-        const view = await store.readDeviceForAdmission(binding.deviceId, input.requester);
+        const view = await store.readDeviceForAdmission(bound.id, input.requester);
         if (!view)
             return rejectNotFound();
         if (view.row.status === "revoked")
             return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
         if (!view.online)
             return reject(DEVICE_ERROR_CODES.OFFLINE, "device is not connected");
-        return { ok: true, value: { deviceId: binding.deviceId, device: view.row, connGeneration: view.row.connGeneration } };
+        return { ok: true, value: { deviceId: bound.id, device: view.row, connGeneration: view.row.connGeneration } };
     }
     async function revoke(input) {
         assertDeviceIdShape(input.deviceId);
@@ -138,7 +153,7 @@ export function createDeviceEnrollment(deps) {
                 return rejectNotFound();
         }
     }
-    return { issueEnrollToken, enroll, bindPlacement, admitSession, revoke };
+    return { issueEnrollToken, enroll, readPlacement, bindPlacement, admitSession, revoke };
 }
 export function createFixedWindowRateLimiter(opts) {
     const now = opts.now ?? (() => Date.now());

package/dist/device-store.d.ts

@@ -1,3 +1,5 @@
+import type { DeviceBindOutcome, DeviceRebindOutcome, InMemoryExecutionPlacementSeat } from "./execution-placement.js";
+import type { SessionFace } from "./session-incarnation.js";
 /**
  * device lane 的 HTTP 错误码闭集(v2 §4.8 逐字)。**唯一导出点** —— 端点车(A-3/车C)从这里取,
  * 禁在路由里手抄字面量(§4.8 task-R1-12:「下表即闭集全集,禁四份手抄」)。
@@ -33,7 +35,7 @@ export declare const DEVICE_ERROR_CODES: {
      *  (管理面,`http/routes/devices.ts`);adapter/准入链结构上不产它。 */
     readonly REBIND_REV_CONFLICT: "device.rebind_rev_conflict";
     /** O4 换绑动词(v2 稿 §2 步 4):该根会话名下有非终态 run(durable 判据 = run store 的 session
-     *  claim;hub 内存在途计数**不作门**——跨副本不可见)—— 体带 `activeTaskId`。铸造点同上一条。 */
+     *  claim;hub 内存在途计数**不作门**——跨副本不可见;保证 = 设备店换绑事务内锁根行后那一读,池级读只作早拒)—— 体带 `activeTaskId`。铸造点同上一条。 */
     readonly REBIND_ACTIVE_RUN: "device.rebind_active_run";
 };
 /** {@link DEVICE_ERROR_CODES} 的值联合 —— 闭集(未知码 = 编译错误,[ref] 词表纪律)。 */
@@ -113,14 +115,6 @@ export interface DeviceRow {
     createdAtMs: number;
     rev: number;
 }
-export interface DeviceSessionRow {
-    /** 键 = **根**会话(task-R1-3:后代继承不另绑)。 */
-    rootSessionId: string;
-    deviceId: string;
-    owner: DeviceOwner;
-    boundAtMs: number;
-    rev: number;
-}
 export interface DeviceAuditRow {
     id: number;
     atMs: number;
@@ -147,7 +141,7 @@ export interface DeviceEnrollTokenRow {
 export declare const DEVICE_KEY_MAX_BYTES = 190;
 /** `device_id` 列宽(`dev_` + 26 位 Crockford base32 ULID = 30 字节,64 是三倍余量)。 */
 export declare const DEVICE_ID_MAX_BYTES = 64;
-/** `root_session_id` 列宽(提交入口硬拒 >64 的 sessionId,128 留一倍余量)。 */
+/** 根会话 id 的形门上界(换绑路由的路径段;会话行 `session_id` 宽 64,提交入口硬拒 >64 的 sessionId,128 留一倍余量 —— 超宽的 id 等值读不到任何行)。 */
 export declare const DEVICE_SESSION_ID_MAX_BYTES = 128;
 /** `pubkey` / `token_hash` 列宽(Ed25519 b64 = 44,sha256 hex = 64)。 */
 export declare const DEVICE_PUBKEY_MAX_BYTES = 128;
@@ -176,10 +170,12 @@ export declare function assertDevicePubkeyShape(pubkey: string): void;
 export declare function assertNewDeviceShape(input: NewDeviceInput): void;
 export declare function assertIssueTokenShape(input: IssueEnrollTokenInput): void;
 export declare function assertRevokeShape(input: RevokeDeviceInput): void;
+/** device 首绑入参的整形门(三形共用:内存参照实现与两方言从同一处过)。 */
+export declare function assertPlaceDeviceShape(input: PlaceDeviceExecutionInput): void;
 /** O4 换绑入参的整形门(三形共用)。`expectedRev` 收窄为非负整数:它要进 SQL 等值谓词,小数/负数/NaN
  *  在两方言的 BIGINT 比对下不是「不匹配」而是各自的隐式转换歧义面 —— 在门口拒,方言分歧面消失。
  *  ⚠️ HTTP 层对坏形先答 400(业务拒绝);这里的抛是**编程/装配错误**的兜底,不是 wire 分支。 */
-export declare function assertRebindShape(input: RebindSessionInput): void;
+export declare function assertRebindShape(input: RebindDeviceExecutionInput): void;
 export declare function assertAcquireShape(input: AcquireConnectionInput): void;
 /** token 摘要必须是**规范形**(小写 sha256 hex):大小写混形在 VARBINARY/COLLATE "C" 下是两个键,
  *  于是同一个明文 token 能被消费两次 —— 这是 §7-T5 ③「一次性 CAS」的直接跳过面。 */
@@ -268,73 +264,53 @@ export type ConsumeEnrollTokenResult =
  | {
     outcome: "pubkey_taken";
 };
-export interface BindSessionInput {
-    rootSessionId: string;
-    deviceId: string;
-    /** 验证过的复合身份;与 devices 行的 owner 在**同一事务**内比对(§4.3.2 首绑)。 */
-    owner: DeviceOwner;
-}
-/** §4.3.2 首绑协议的判别式结果 —— 并发争抢**单赢家,无未定义态**。 */
-export type BindSessionResult = {
-    outcome: "bound";
-    row: DeviceSessionRow;
-}
-/** 并发输家或重试,但绑的是**同一台**设备 ⇒ 幂等成功。 */
- | {
-    outcome: "idempotent";
-    row: DeviceSessionRow;
-}
-/** 根会话已绑**另一台**设备(或另一个 owner)⇒ `device.claim_conflict`。 */
- | {
-    outcome: "conflict";
-    row: DeviceSessionRow;
+/**
+ * device 车道的**首绑**(§4.3.2;认领之后的初始放置写,§3.3 转换表 place / bind 两行):根会话行上这一位住客的执行格
+ * absent → writer(device, D),或迁移回填的 writer(device, ∅) → writer(device, D)。绑定**住在会话行上**(唯一载体;
+ * 列与语句的属主 = `plugins/execution-placement-sql.ts`),本店只负责「设备行判 + 写格」同一事务(锁序:设备行 → 根 `session_meta`)。
+ */
+export interface PlaceDeviceExecutionInput {
+    /** 根会话(放置键;后代继承,不另绑)。 */
+    readonly root: string;
+    /** 意图那一读的住客(会话店执行席 `seat.read(root)` 交出的那一位)—— 写按住客谓词定址:住客换了 ⇒ `gone`,永不写到新住客身上。 */
+    readonly occupant: SessionFace;
+    readonly deviceId: string;
+    /** 验证过的复合身份;与设备行的 owner 在**同一事务**内比对,写进格的两属主列(绑定属主 = 设备属主)。 */
+    readonly owner: DeviceOwner;
 }
-/** 设备不存在**或**不是请求方的 —— 反枚举同形(见文件头注)。 */
- | {
-    outcome: "device_not_found";
+/**
+ * 首绑的判别式结果 —— 并发争抢**单赢家,无未定义态**。格的那几臂与判官同一张表(`DeviceBindOutcome`:`bound` / 同设备 `same`(幂等成功)/
+ * 异设备 `device_conflict` / 异车道 `tree_bound` / `mirror` / 住客不是判过的那一位或行不在 `gone`),外加设备行的两臂:
+ * 设备不存在**或**不是请求方的(反枚举同形,见文件头注)/ 已吊销。
+ */
+export type PlaceDeviceExecutionResult = DeviceBindOutcome | {
+    readonly outcome: "device_not_found";
 } | {
-    outcome: "device_revoked";
+    readonly outcome: "device_revoked";
 };
 /**
- * O4 显式换绑(2026-08-30 v2 稿 §2)。`owner` = **绑定行的**复合身份(HTTP 层已裁决:属主同域或
- * explicit operator;operator 代操作时传的也是行的 owner,不是操作员自己)——店内所有谓词恒带它,
- * 判别位在店里就消失(反枚举,文件头注)。`expectedRev` = 壳从 S-4 读面拿到的前态(强制显式,
- * 防两操作员并发换绑互踩)。
+ * O4 显式换绑(2026-08-30 v2 稿 §2;§3.3 转换表 rebind 行)。`occupant` = 换绑门那一读的住客;`owner` = 门判过的**格上**两属主列
+ * (HTTP 层已裁决:属主同域或 explicit operator;operator 代操作时传的也是格上的 owner,不是操作员自己)——店内所有谓词恒带它,
+ * 判别位在店里就消失(反枚举,文件头注)。`expectedRev` = 壳从执行放置读面拿到的前态(强制显式,防两操作员并发换绑互踩)。
  */
-export interface RebindSessionInput {
-    rootSessionId: string;
-    toDeviceId: string;
-    expectedRev: number;
-    owner: DeviceOwner;
+export interface RebindDeviceExecutionInput {
+    readonly root: string;
+    readonly occupant: SessionFace;
+    readonly owner: DeviceOwner;
+    readonly expectedRev: number;
+    readonly targetDeviceId: string;
 }
 /**
- * O4 换绑的判别式结果(门序 = v2 稿 §2:目标设备在场 → 幂等短路 → 前态 CAS → 审计;活跃 run 门在
- * **HTTP 层**、CAS 之前判 —— run store 是另一只店,CAS 语句不兼职)。
+ * O4 换绑的判别式结果(门序 = v2 稿 §2 + 读写序律:目标设备在场 → 锁根行读认领 → 幂等短路 → 前态 CAS → 审计)。格的那几臂与判官同一张表
+ * (`DeviceRebindOutcome`:`rebound` 带被换下的那台 / 真幂等 `idempotent` / 前态输 `rev_conflict` 携当前格 / `gone` = 行不在、住客换了、不是 writer(device, D)、
+ * 或绑定属主不是判过的那一位 —— 反枚举同形),外加:目标设备不在 / 不是该 owner 的 / **已吊销**(三臂同折 404;吊销不单列 = 判别位在店里就消失);
+ * 写事务内锁根行后读到认领 `active_run`(SQL 后端;读写序律只在 SQL 后端立 —— 内存参照实现没有认领表,答不出这一臂,内存走廊的认领判据是路由的早拒)。
  */
-export type RebindSessionResult = 
-/** CAS 赢家:`rev+1` + `bound_at` 刷新 + `session_rebound` 审计行**同一事务**提交。 */
-{
-    outcome: "rebound";
-    row: DeviceSessionRow;
-}
-/** 真幂等:`toDeviceId` ≡ 当前绑定 ∧ `expectedRev` ≡ 当前 rev ⇒ 回显不加 rev、不写审计。 */
- | {
-    outcome: "idempotent";
-    row: DeviceSessionRow;
-}
-/** 前态输(rev 不符,含「toDeviceId 同但 rev 错」——前态错就是错)⇒ 携当前行供壳一跳重定位。 */
- | {
-    outcome: "rev_conflict";
-    row: DeviceSessionRow;
-}
-/** 绑定行不在**或**不是该 owner 的 —— 反枚举同形(HTTP 层折 404 同串)。 */
- | {
-    outcome: "binding_not_found";
-}
-/** 目标设备不在 / 不是该 owner 的 / **已吊销** —— v2 稿 §2 步 2:三臂同折 404(设备 id 也是
- *  不可枚举面);吊销不单列 = 判别位在店里就消失,消费层想泄也泄不出来。 */
- | {
-    outcome: "device_not_found";
+export type RebindDeviceExecutionResult = DeviceRebindOutcome | {
+    readonly outcome: "device_not_found";
+} | {
+    readonly outcome: "active_run";
+    readonly activeTaskId: string;
 };
 export interface RevokeDeviceInput {
     deviceId: string;
@@ -415,14 +391,10 @@ export interface DeviceStore {
     /** 世代谓词命中 = true;0 行 = 已失权。 */
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
-    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
-    /** O4 显式换绑(v2 稿 §2 步 2/3/5):目标设备门 + 前态 CAS + `session_rebound` 审计行同一事务。
-     *  活跃 run 门**不在这里**(run store 是另一只店)—— 由 HTTP 层在调用前判(v2 稿 §2 步 4)。 */
-    rebindSession(input: RebindSessionInput): Promise<RebindSessionResult>;
-    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
-    /** purge coordinator 座(§6 注②:core 的会话删除是**逐 store 显式调用**,不是 DB 自动扫;
-     *  只建表不接 purge = 删会话后绑定残留 ⇒ sessionId 重用致旧设备粘连/claim conflict/隐私残留)。 */
-    deleteByRootSession(rootSessionId: string): Promise<number>;
+    /** 首绑(认领之后的初始放置写):设备行判(active ∧ 属主)+ 写格同一事务,按住客谓词定址。 */
+    placeDeviceExecution(input: PlaceDeviceExecutionInput): Promise<PlaceDeviceExecutionResult>;
+    /** O4 显式换绑(v2 稿 §2 步 2/3/5):目标设备门 + 写事务内锁根行读认领 + 前态 CAS + `session_rebound` 审计行同一事务。 */
+    rebindDeviceExecution(input: RebindDeviceExecutionInput): Promise<RebindDeviceExecutionResult>;
     appendAudit(input: AppendAuditInput): Promise<void>;
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }
@@ -432,15 +404,19 @@ declare function cloneOwner(o: DeviceOwner): DeviceOwner;
  * 语义 oracle。**单线程 JS 的原子性**替代 SQL 事务:每个方法体内没有 `await`(除了返回值),所以
  * 「读-判-写」在事件循环上不可分割 —— 与 SQL 侧的单事务 CAS 语义等价,这也是为什么并发格
  * (两个并发消费同一 token)在这一形上必须给出与真库**同一个**赢家/输家分布。
+ *
+ * 绑定不在本店:它是会话行上的执行格。构造**必收**测试走廊的会话行 {@link InMemoryExecutionPlacementSeat}(同为参照实现,生产零引用)——
+ * 首绑 / 换绑在它上面做(判官与 SQL 语句模块同一组),读者经同一只席的 `read(root)` 读。
  */
 export declare class InMemoryDeviceStore implements DeviceStore {
     private readonly devices;
-    private readonly sessions;
     private readonly tokens;
     private readonly audit;
     private auditSeq;
     private readonly now;
-    constructor(opts?: {
+    private readonly seat;
+    constructor(opts: {
+        seat: InMemoryExecutionPlacementSeat;
         now?: () => number;
     });
     issueEnrollToken(input: IssueEnrollTokenInput): Promise<DeviceEnrollTokenRow>;
@@ -454,17 +430,14 @@ export declare class InMemoryDeviceStore implements DeviceStore {
     acquireConnection(input: AcquireConnectionInput): Promise<AcquireConnectionResult>;
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
-    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
-    rebindSession(input: RebindSessionInput): Promise<RebindSessionResult>;
-    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
-    deleteByRootSession(rootSessionId: string): Promise<number>;
+    placeDeviceExecution(input: PlaceDeviceExecutionInput): Promise<PlaceDeviceExecutionResult>;
+    rebindDeviceExecution(input: RebindDeviceExecutionInput): Promise<RebindDeviceExecutionResult>;
     appendAudit(input: AppendAuditInput): Promise<void>;
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
     private isOnline;
     private pushAudit;
     /** 返回**拷贝**:调用方拿到的行改了也不能污染店内状态(SQL 侧天然如此,InMemory 必须显式做)。 */
     private snapshotDevice;
-    private snapshotSession;
 }
 export { sameOwner as sameDeviceOwner, cloneOwner as cloneDeviceOwner };
 //# sourceMappingURL=device-store.d.ts.map