@sema-agent/server 7.50.0 → 7.51.0

package/dist/execution-lane-caps.js

@@ -0,0 +1,166 @@
+const NO = "unsupported";
+const YES = "supported";
+const SU = "single-user-only";
+export function executionLaneCaps(lane) {
+    switch (lane) {
+        case "in-process":
+            return {
+                callerCwd: NO,
+                backgroundShell: NO,
+                scheduler: NO,
+                lsp: NO,
+                sandboxSendUserFile: NO,
+                isolation: NO,
+                suspendable: NO,
+                remoteScratchpad: NO,
+                sandboxPathAdjudication: NO,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: YES,
+                coreRemoteExecutionEnv: NO,
+            };
+        case "host":
+            return {
+                callerCwd: SU,
+                backgroundShell: SU,
+                scheduler: SU,
+                lsp: SU,
+                sandboxSendUserFile: NO,
+                isolation: NO,
+                suspendable: NO,
+                remoteScratchpad: NO,
+                sandboxPathAdjudication: NO,
+                worktreeIsolation: YES,
+                memoryPersistenceCapable: YES,
+                hostFilePlane: YES,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "e2b":
+            return {
+                callerCwd: NO,
+                backgroundShell: YES,
+                scheduler: NO,
+                lsp: YES,
+                sandboxSendUserFile: YES,
+                isolation: YES,
+                suspendable: YES,
+                remoteScratchpad: YES,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "k8s":
+            return {
+                callerCwd: NO,
+                backgroundShell: YES,
+                scheduler: NO,
+                lsp: YES,
+                sandboxSendUserFile: YES,
+                isolation: YES,
+                suspendable: YES,
+                remoteScratchpad: YES,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "ssh":
+            return {
+                callerCwd: NO,
+                backgroundShell: NO,
+                scheduler: NO,
+                lsp: NO,
+                sandboxSendUserFile: SU,
+                isolation: NO,
+                suspendable: NO,
+                remoteScratchpad: YES,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "adb":
+            return {
+                callerCwd: NO,
+                backgroundShell: NO,
+                scheduler: NO,
+                lsp: NO,
+                sandboxSendUserFile: NO,
+                isolation: NO,
+                suspendable: NO,
+                remoteScratchpad: NO,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "local-docker":
+            return {
+                callerCwd: NO,
+                backgroundShell: NO,
+                scheduler: NO,
+                lsp: NO,
+                sandboxSendUserFile: NO,
+                isolation: YES,
+                suspendable: NO,
+                remoteScratchpad: YES,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+        case "device":
+            return {
+                callerCwd: YES,
+                backgroundShell: NO,
+                scheduler: NO,
+                lsp: NO,
+                sandboxSendUserFile: NO,
+                isolation: NO,
+                suspendable: NO,
+                remoteScratchpad: YES,
+                sandboxPathAdjudication: YES,
+                worktreeIsolation: NO,
+                memoryPersistenceCapable: NO,
+                hostFilePlane: NO,
+                coreRemoteExecutionEnv: YES,
+            };
+    }
+}
+const EXECUTION_LANE_WORDS = {
+    "in-process": true,
+    host: true,
+    e2b: true,
+    k8s: true,
+    ssh: true,
+    adb: true,
+    "local-docker": true,
+    device: true,
+};
+export function isExecutionLane(word) {
+    return Object.hasOwn(EXECUTION_LANE_WORDS, word);
+}
+export const ALL_EXECUTION_LANES = Object.freeze(Object.keys(EXECUTION_LANE_WORDS).filter(isExecutionLane));
+export function executionLaneOf(provider) {
+    if (provider === undefined)
+        return "in-process";
+    return isExecutionLane(provider) ? provider : undefined;
+}
+export function laneCapabilityHolds(cap, deployment) {
+    switch (cap) {
+        case "supported":
+            return true;
+        case "unsupported":
+            return false;
+        case "single-user-only":
+            return deployment.requirePrincipal !== true;
+    }
+}
+export const PLANNED_LANE_DIVERGENCES = Object.freeze([]);
+//# sourceMappingURL=execution-lane-caps.js.map

package/dist/http/routes/capabilities.js

@@ -2,7 +2,8 @@ import { DEFAULT_EFFORT_LEVELS, expandTiers, routePairingStatus } from "@sema-ag
 import { isModelAllowlisted } from "../../model-select.js";
 import { resolveModelApiKey } from "../../key-resolver.js";
 import { isSealedKeyPoison } from "../../sealed-key.js";
-import { cwdHonored } from "../../task-cwd.js";
+import { cwdHonored, deviceCwdHonored } from "../../task-cwd.js";
+import { DEVICE_PROTOCOL_VERSION, DEVICE_WS_PATH } from "../../device-ws-protocol.js";
 import { a2aInjectionHonored } from "../../task-a2a.js";
 import { mcpInjectionHonored } from "../../task-mcp.js";
 import { sendJson, sendError } from "../send.js";
@@ -47,6 +48,9 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             artifacts: Boolean(deps.runStore),
             approvals: Boolean(deps.checkpointStore),
             sessions: Boolean(deps.sessionAudit),
+            deviceExecutor: deps.deviceHub
+                ? { enabled: true, protocolVersion: DEVICE_PROTOCOL_VERSION, maxInflightPerDevice: deps.config.remoteExec?.provider === "device" ? (deps.config.remoteExec.maxInflightPerDevice ?? 4) : 4, wsPath: DEVICE_WS_PATH }
+                : false,
             sessionEvents: Boolean(deps.sessionWatch && deps.sessionStorage?.getLeafId && deps.sessionStorage?.ownerOf),
             fleet: deps.fleetBus
                 ? { stream: true, sessionScope: true, observe: true, resume: "snapshot", bgNotifyFailClosed: true, steerPriority: "advisory", hookFailureNotice: true }
@@ -86,7 +90,7 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             scratchpadDir: true,
             subagentSteer: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
             subagentResume: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
-            taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: cwdHonored(deps.config), hooks: deps.config.requirePrincipal !== true },
+            taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: cwdHonored(deps.config) || deviceCwdHonored(deps.config), hooks: deps.config.requirePrincipal !== true },
             modeShellGateTranslation: true,
             permissionModeAuto: {
                 accepted: true,
@@ -103,6 +107,7 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             retainBackgroundProcesses: deps.config.requirePrincipal !== true,
             interactiveTools: true,
             projectContext: cwdHonored(deps.config),
+            callerCwd: cwdHonored(deps.config) || deviceCwdHonored(deps.config),
             mcpInjection: mcpInjectionHonored(deps.config),
             a2a: true,
             a2aInjection: a2aInjectionHonored(deps.config),

package/dist/http/server.d.ts

@@ -242,6 +242,20 @@ export interface ServiceCoordinatorDeps {
  *  重组零件——见 backend 的同款论证)。parked-revive 三件是同族的构件缝(boot 期从生产装配取的裸
  *  ToolSpec + 成员集 + 父约束重建器),与 backgroundAgentStore 齐备才构成赎回腿。 */
 export interface ServiceSeamDeps {
+    /**
+     * device lane 的 WS 汇聚端(design/device-executor-lane-v2 §5,车A-3)—— 本仓**首个** WS 服务端。
+     * 给了就把 `GET /v1/device/ws` 的 upgrade 处理器挂到这台 `http.Server` 上;缺席 = 本部署没有 device
+     * 车道 ⇒ 该路径连 upgrade 都不认(与 `REMOTE_EXEC=device` 的拒启门同一条诚实线)。
+     *
+     * ⚠️ 排空联动由**装配层**驱动:`drainState.draining` 翻真时,main.ts 须同时调 `deviceHub.beginDrain()`
+     * ——两者刻意不在这里自动耦合,因为 §8-R7 的顺序(新提交 503 → 新 upgrade 拒 → 停发新指令 →
+     * 在途结果照收 → 才断连)是**部署编排**的语义,不是 HTTP 层能自作主张的。
+     *
+     * 🔴 **当前生产装配恒缺席,这是有意的**(`parkedKnownAgentTypes` 同族形):车A-3 只交汇聚端与这条
+     * 挂载缝;`main.ts` 侧的真装配(建店 → 建 hub → 传这个键 → 与 `drainState` 联动 → 与
+     * `REMOTE_EXEC=device` 拒启门对齐)属**车A-4/端点车**。在那之前本键只有测试口消费,不是死枝。
+     */
+    deviceHub?: import("../device-ws-hub.js").DeviceWsHub;
     /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. */
     sessionAudit?: (sessionId: string) => Promise<({
         owner: string | null;

package/dist/http/server.js

@@ -244,6 +244,7 @@ export function createHttpServer(rawDeps) {
                 res.end();
         });
     });
+    deps.deviceHub?.attach(server);
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
@@ -1604,6 +1605,8 @@ export function createHttpServer(rawDeps) {
                     e.code === "resume.constraint_unprojectable" ||
                     e.code === "resume.usage_window_exhausted" ||
                     e.code === "resume.principal_mismatch" ||
+                    e.code === "resume.placement_mismatch" ||
+                    e.code === "resume.preflight_rejected" ||
                     e.code.startsWith("wake.") ||
                     (e.code === "checkpoint.unsupported_version" && checkpointRowRedeemableElsewhere(e.detail?.reason));
                 if (claimedRow && taskId && deps.runStore) {
@@ -1633,7 +1636,7 @@ export function createHttpServer(rawDeps) {
                             ? (outcome.gate === "policy_ask" ? "approval_binding_mismatch" : "resume_outcome_invalid")
                             : e.code,
                         ...(e.detail?.field ? { field: e.detail.field } : {}),
-                        ...(e.code === "resume.usage_window_exhausted" && typeof e.detail?.retryAfterMs === "number" && Number.isFinite(e.detail.retryAfterMs) && e.detail.retryAfterMs > 0
+                        ...((e.code === "resume.usage_window_exhausted" || e.code === "resume.preflight_rejected") && typeof e.detail?.retryAfterMs === "number" && Number.isFinite(e.detail.retryAfterMs) && e.detail.retryAfterMs > 0
                             ? { retryAfterSec: Math.max(1, Math.ceil(e.detail.retryAfterMs / 1000)) }
                             : {}),
                         ...(retriable ? { retriable: true } : {}),

package/dist/leader/wire.js

@@ -366,7 +366,8 @@ export function createLeaderRunner(cfg) {
         };
         const provisionIntegrationSandbox = async () => {
             if (cfg.envFactory) {
-                const env = cfg.envFactory({ sessionId: `leader-integ-${Date.now()}` });
+                const integSessionId = `leader-integ-${Date.now()}`;
+                const env = cfg.envFactory({ sessionId: integSessionId, placementRootSessionId: integSessionId });
                 try {
                     await sh(env)(body.seedCmd);
                     await injectOracles(env);
@@ -412,7 +413,8 @@ export function createLeaderRunner(cfg) {
         const resolveRepair = async (solo, _sub) => {
             let env;
             if (cfg.envFactory) {
-                env = cfg.envFactory({ sessionId: `leader-grader-${Date.now()}` });
+                const graderSessionId = `leader-grader-${Date.now()}`;
+                env = cfg.envFactory({ sessionId: graderSessionId, placementRootSessionId: graderSessionId });
             }
             else {
                 if (!cfg.e2bApiKey)

package/dist/main.js

@@ -50,6 +50,7 @@ import { assertRetentionLaneWirable, startRetentionLane, RETENTION_LEASE_TTL_FAC
 import { assertConsolidationDriverWirable, buildConsolidationValveAudit, createMemoryConsolidationFaces, resolveConsolidationDriverSeat } from "./boot/memory-consolidation.js";
 import { startFleetReconciler } from "./fleet/fleet-reconciler.js";
 import { openStores } from "./boot/stores.js";
+import { assertDeviceLaneWired, createDeviceLane } from "./boot/device-lane.js";
 import { runAdoptionBootScan } from "./boot/adoption.js";
 import { auditDormantPermissionRules } from "./boot/permission-rules-audit.js";
 import { createBudgetAndTracing } from "./boot/budget-tracing.js";
@@ -117,6 +118,7 @@ async function main() {
     const configCenter = await createConfigCenterRuntime({ config, logger, metrics, localRoot });
     await configCenter.applyLocalRemoteExec();
     const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, usageWindowStore, memoryPosture, taskListLane, } = await openStores({ config, logger, metrics, localRoot });
+    const instanceId = uuidv7();
     const memoryBundleFaces = memoryEngine ? createMemoryBundleFaces(memoryEngine) : undefined;
     const memoryComplianceFaces = memoryEngine
         ? createMemoryComplianceFaces(memoryEngine, {
@@ -144,7 +146,9 @@ async function main() {
         });
     }
     await auditDormantPermissionRules({ stores: permissionRuleStores, logger, explicit: config.permissionRulesEnabledExplicit });
-    const { perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, } = createExecutionEnv({ config, logger, metrics, taskAttachmentStore });
+    const deviceLane = config.remoteExec?.provider === "device" ? createDeviceLane({ config, logger, metrics, backend, replicaId: instanceId, rateGate: () => rateLimiter }) : undefined;
+    const { perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, fenceSessionOwner, dropSessionScoped, executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, } = createExecutionEnv({ config, logger, metrics, taskAttachmentStore, ...(deviceLane ? { deviceLane } : {}) });
+    assertDeviceLaneWired(config.remoteExec?.provider === "device", deviceLane, executionEnvFactory !== undefined);
     const toolTracer = config.toolTrace ? createToolTracer(logger) : undefined;
     if (toolTracer)
         logger.info("tool_trace_enabled", {});
@@ -328,7 +332,6 @@ async function main() {
     const runStore = backend ? backend.run() : undefined;
     const resumeAnchorStore = backend ? backend.resumeAnchor() : undefined;
     const approvalExemptionStore = backend ? backend.approvalExemption() : undefined;
-    const instanceId = uuidv7();
     const taskTimeoutSec = Math.max(0, Math.floor(numEnv("TASK_TIMEOUT_SEC", "0")));
     const capEnv = (name) => {
         const r = parseCapEnv(name, process.env[name]);
@@ -515,6 +518,8 @@ async function main() {
     configCenter.startRefreshLoop({ runnerTierFrozen, pricing, limitSync, swapRunnerModels });
     configCenter.initKeyResolver();
     const { ownerAware, sessionAudit, sessionWatchRegistry, purgeSession, instrumentDegenerate, planCacheProbe } = createSessionFaces({
+        deviceStore: deviceLane?.store,
+        dropSessionScoped,
         config, logger, metrics, localRoot, backend, sessionStore, runStore, checkpointStore, toolResultStore,
         resumeAnchorStore, approvalExemptionStore, sessionPolicyStore, taskAttachmentStore, fileSnapshotStore,
         workflowCompletionInbox, taskListLane,
@@ -585,6 +590,7 @@ async function main() {
         sessionTitler: sessionTitler ? sessionTitler : undefined,
     };
     const seams = {
+        deviceHub: deviceLane?.hub,
         sessionAudit,
         routeJudgeBrain: brain,
         purgeSession: purgeSession ? purgeSession : undefined,
@@ -665,7 +671,7 @@ async function main() {
         config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver,
         getCenterPrompts: () => configCenter.getCenterPrompts(),
         getKeyResolver: () => configCenter.getKeyResolver(),
-        taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv,
+        taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, fenceSessionOwner,
         hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec,
         selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore,
         singleUserAutoAcceptBaseline, checkpointStore, deploymentHooks, imageIndex, perTaskImage,
@@ -785,6 +791,7 @@ async function main() {
         version: serviceVersion(),
         runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState,
         storeLiveProbe, configCenter,
+        deviceHub: deviceLane?.hub,
         retentionLane: retentionLaneStarted,
         releaseRetentionLease: retentionLaneStore !== undefined ? () => retentionLaneStore.release(instanceId) : undefined,
     });

package/dist/orchestration/hardened-vm-runner.d.ts

@@ -62,6 +62,13 @@ export interface HardenedVmLimits {
      *  A script exceeding it OOMs the WORKER (killed), never the shared main process. Default 128. */
     maxHeapMb?: number;
 }
+/** [5434]①(clay 亲机四 run 三次恰在 600s 整点全灭):workflow 总超时默认与旋钮的**单点**。
+ *  旧默认 600_000(10 分钟)对真实 workflow(验证 agent 逐条重跑清单/任何带审批等待的车)结构性不够——
+ *  默认抬到 **1 小时**;部署经 `WORKFLOW_TOTAL_TIMEOUT_MS` 显式配,域 [60_000, 86_400_000](1 分钟..24h),
+ *  坏值**响亮拒**(#210 立律:旋钮坏值禁静默回默认)。0/负数不是「禁用」:无界 runaway 脚本会吞掉共享
+ *  副本的事件循环/堆,禁用臂刻意不提供——要更久就把值配大。模块加载时读一次(坏 env = boot fail-loud)。
+ *  超时终态分型(partial vs failed,[5434]① 后半)涉 wire status 语义,与 core workflow 终态形另批对表。 */
+export declare function workflowTotalTimeoutMsDefault(): number;
 /**
  * The realm test itself, exported so there is exactly ONE ruler for "did this rejection come from an untrusted
  * script?" in the process. A promise minted INSIDE a vm context fails `instanceof` against the HOST `Promise`

package/dist/orchestration/hardened-vm-runner.js

@@ -1,7 +1,17 @@
 import vm from "node:vm";
 import { splitWorkflowMeta, WorkflowScriptError, } from "@sema-agent/core";
+export function workflowTotalTimeoutMsDefault() {
+    const raw = process.env.WORKFLOW_TOTAL_TIMEOUT_MS;
+    if (raw === undefined || raw === "")
+        return 3_600_000;
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n) || n < 60_000 || n > 86_400_000) {
+        throw new Error(`env WORKFLOW_TOTAL_TIMEOUT_MS must be an integer in [60000, 86400000] ms (got ${JSON.stringify(raw)}) — unset it for the 3600000 default`);
+    }
+    return n;
+}
 const DEFAULTS = {
-    totalTimeoutMs: 600_000,
+    totalTimeoutMs: workflowTotalTimeoutMsDefault(),
     syncTimeoutMs: 5_000,
     maxAgents: 1000,
     concurrency: 12,

package/dist/orchestration/hardened-vm-worker-runner.js

@@ -1,7 +1,7 @@
 import { Worker } from "node:worker_threads";
 import { WorkflowScriptError } from "@sema-agent/core";
-import { scopedPhaseGate } from "./hardened-vm-runner.js";
-const DEFAULTS = { totalTimeoutMs: 600_000, syncTimeoutMs: 5_000, maxAgents: 1000, concurrency: 12, maxHeapMb: 128 };
+import { scopedPhaseGate, workflowTotalTimeoutMsDefault } from "./hardened-vm-runner.js";
+const DEFAULTS = { totalTimeoutMs: workflowTotalTimeoutMsDefault(), syncTimeoutMs: 5_000, maxAgents: 1000, concurrency: 12, maxHeapMb: 128 };
 const IS_TS = import.meta.url.endsWith(".ts");
 const WORKER_URL = new URL(IS_TS ? "./hardened-vm-worker.ts" : "./hardened-vm-worker.js", import.meta.url);
 const WORKER_EXEC_ARGV = IS_TS ? ["--import", "tsx/esm"] : undefined;

package/dist/plugins/device-store-sql.d.ts

@@ -0,0 +1,130 @@
+/**
+ * device lane 四表持久层(design/device-executor-lane-v2 §6)—— `DeviceStore` 双方言实现
+ * (`TiDBDeviceStore` / `PgDeviceStore`,SINGLE-FILE DUAL-DIALECT,design/158 A12 形:一个
+ * `SqlDeviceStore` 接 `SqlDriver`,两个薄 ctor 子类落方言绑定)。语义真源 = `../device-store.js`
+ * (类型 + 闭集 + InMemory 参照实现),准入链 = `../device-enrollment.js`。
+ *
+ * 四张表:
+ *   · `devices`              —— 设备注册簿 + presence 投影(单设备单活连 ⇒ 1:1,省一次 join,§6 注①)
+ *   · `device_enroll_tokens` —— 一次性 enrollment 凭据(明文一现,落库只有 sha256)
+ *   · `device_sessions`      —— **根会话**↔设备绑定(resume 路由真源,§4.5)
+ *   · `device_audit`         —— 安全轴事件审计(§4.8 标「审计行」的 8 个 event)
+ * 刻意**没有** `device_instructions` 表:指令 pending 表是内存态(§6 注③——指令比 run 短命,落库只会
+ * 造「表里 pending、run 已死」的僵尸行;at-most-once 靠 §5.3 投递边界,不靠指令落库)。
+ *
+ * ── CAS 铁则(与 approval-ask-store-sql.ts 头注同源,写在这里防遗忘)─────────────────────────────
+ * 1. 一切转移带 `WHERE <前态>`,赢 = affected 恰为 1。禁读-改-写两步(TOCTOU 窗口)。
+ * 2. 🔴 MySQL/TiDB `affectedRows` 坑:同值 UPDATE(SET 的新值与当前列逐字节相同)affectedRows=0
+ *    ——**所有** CAS UPDATE 因此必须带一个恒变列(`rev = rev + 1`)。本文件每一条 CAS UPDATE 都带。
+ *    在本店这条尤其致命:心跳续租在「同一毫秒内重复心跳」时 SET 的值可能与当前值相同,没有 rev
+ *    就会被判成「本连接已失权」⇒ 设备被自己的心跳踢下线。
+ * 3. 事务:`SqlDriver.connect()` → `begin()`/`beginPessimistic()` → `query()` → `commit()`,失败
+ *    `rollback()`。**失败臂的回读必须走当前这条 `conn`**(approval 店复审 F1 的真缺陷:走池级 query
+ *    会与自己持有的连接死锁),且**先 rollback 再读**(读到最新已提交视图)。
+ *
+ * ── 方言差异(A12 doctrine:每处显式写在调用点)────────────────────────────────────────────────────
+ *   - `?`(位置序) vs `$n`(显式编号);动态 WHERE(`listAudit`)靠 `ph(dialect, n)` 生成。
+ *   - `INSERT IGNORE` vs `ON CONFLICT (pk) DO NOTHING`(`bindSession` 的首绑 CAS)。
+ *   - `AUTO_INCREMENT` vs `BIGSERIAL`;`JSON` vs `JSONB`(+ `$n::jsonb` 显式 cast)。
+ *   - `KEY …` 内联 vs 独立 `CREATE INDEX IF NOT EXISTS`。
+ *   - 回读名单:PG 用 `UPDATE … RETURNING`,TiDB 无 RETURNING ⇒ 同事务 `UPDATE` 后 `SELECT`。
+ *   - 时长运算:`NOW(3) + INTERVAL ? SECOND` vs `now() + ($n::double precision * INTERVAL '1 second')`。
+ *   - 键列字节等价:MySQL `VARBINARY` vs PG `VARCHAR … COLLATE "C"`(理由见 ../device-store.ts 头注;
+ *     `utf8mb4_bin` **不够**,它仍是 PAD SPACE collation)。
+ *   - VARBINARY 的读回:mysql2 给 **Buffer**,PG 给 string ⇒ 一律过 `bufToStr`(mailbox 真库坑同解)。
+ *
+ * ── 时间列的存取形(§4.6 task-R3-F18「时间权威 = DB」的落地)──────────────────────────────────────
+ * 列是原生 `DATETIME(3)` / `TIMESTAMPTZ(3)`,但**跨边界一律是 epoch 毫秒**:写侧送**时长秒**由 SQL 从
+ * DB 的 now 起算,读侧在 SELECT 里就转成 `*_ms`。
+ * 🔴 为什么不让驱动把时间戳解成 JS `Date` 再比:①mysql2 按**进程**时区解析 DATETIME,DB 会话时区与
+ * Node 时区不同即整体偏移几小时(而这条偏移落在「租约还有效吗」上就是双主);②`Date.now()` 一旦进入
+ * 判据,副本时钟落后即越租。两条都在 SELECT 表达式里就地关掉。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+import { type AcquireConnectionInput, type AcquireConnectionResult, type AppendAuditInput, type BindSessionInput, type BindSessionResult, type ConsumeEnrollTokenInput, type ConsumeEnrollTokenResult, type DeviceAdmissionView, type DeviceAuditRow, type DeviceEnrollTokenRow, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type HeartbeatConnectionInput, type IssueEnrollTokenInput, type ListAuditFilter, type RevokeDeviceInput, type RevokeDeviceResult } from "../device-store.js";
+/**
+ * ── 命名(**落库一律单数**,与设计稿的复数形不同)──────────────────────────────────────────────────
+ * design v2 §6 的 DDL 写的是 `devices` / `device_sessions` / `device_enrollment_tokens`(复数),但本仓有一条
+ * 常驻机器门:`test/schema-naming-invariants.test.ts` 判据① —— 建表的表名必须在 `TABLE_VOCABULARY` 闭集里
+ * **且词表全是单数形**。#270 车1 的 `retention_hold` / `retention_tombstone` 是同一处先例(那份设计稿同样
+ * 写的复数,落库单数)。所以四张表落库名为 `device` / `device_session` / `device_enroll_token` /
+ * `device_audit`,**表结构与设计稿逐列一致**,只有名字随仓规。新表 = 先进词表再建。
+ */
+export declare const DEVICES_TABLE = "device";
+export declare const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
+export declare const DEVICE_SESSIONS_TABLE = "device_session";
+export declare const DEVICE_AUDIT_TABLE = "device_audit";
+export declare const TIDB_DEVICE_STATEMENTS: readonly string[];
+/** {@link TIDB_DEVICE_STATEMENTS} 的遍历壳(集成测试用;生产装配由中央 ensureSchema 展开同一份数组)。 */
+export declare function ensureTiDBDeviceSchema(pool: MySqlPool): Promise<void>;
+type PgQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
+export declare function ensurePgDeviceSchema(q: PgQuery): Promise<void>;
+export declare class SqlDeviceStore implements DeviceStore {
+    private readonly db;
+    constructor(db: SqlDriver);
+    private q;
+    private json;
+    issueEnrollToken(input: IssueEnrollTokenInput): Promise<DeviceEnrollTokenRow>;
+    getEnrollToken(tokenHash: string): Promise<DeviceEnrollTokenRow | null>;
+    /**
+     * §6 注册协议 —— **单事务**:消费 CAS + INSERT devices + 审计行一起提交。
+     *
+     * 谓词四件(缺一即 affected=0):`consumed_at IS NULL`(一次性)、`expires_at > NOW(3)`(TTL,DB 钟)、
+     * `target_tenant/target_subject` 等值(绑定 principal)。affected=0 的**理由**靠回滚后的回读判别 ——
+     * 顺序刻意是「先 principal 后消费态」:token 不是你的就连「它被没被用过」都不告诉你。
+     */
+    consumeEnrollToken(input: ConsumeEnrollTokenInput): Promise<ConsumeEnrollTokenResult>;
+    /** 事务内/持连接期间的设备回读(见 consumeEnrollToken 的 F2 注:此期间**禁**走池级读)。 */
+    private readDeviceOn;
+    readDeviceForAdmission(deviceId: string, owner: DeviceOwner): Promise<DeviceAdmissionView | null>;
+    getDeviceUnscoped(deviceId: string): Promise<DeviceRow | null>;
+    listDevicesByOwner(owner: DeviceOwner): Promise<DeviceRow[]>;
+    /**
+     * 吊销 = 终态 CAS(`status='active'` 前态)+ **租约作废 + 世代推进**(§8-R4 在途语义):
+     * 世代一推,在途连接的每一次带世代谓词的写(心跳/结果帧入账)当场影响 0 行 ⇒ 设备侧立即失权。
+     */
+    revokeDevice(input: RevokeDeviceInput): Promise<RevokeDeviceResult>;
+    /**
+     * 连接建立 = 带 expiry 的租约 CAS。谓词 `lease_expires_at IS NULL OR <= NOW(3)`:**活租约恒不被撕**
+     * (§5.2 单活连不变量;`DEVICE_SUPERSEDE=stale_only` 的语义就在这一句),过期租约才可被新连夺取。
+     * 赢家 `conn_generation` 单调 +1,后续所有写都带这个世代谓词。
+     */
+    acquireConnection(input: AcquireConnectionInput): Promise<AcquireConnectionResult>;
+    /**
+     * 心跳续租 —— 谓词 = **世代等值 + active**。影响 0 行 = 本连接已失权(被顶替 / 被吊销)⇒ 调用方
+     * 主动断开(§4.6 步 2)。
+     *
+     * 🔴 允许续一条**已过期但没被别人夺走**的租约(generation 未变 ⇒ 排他性仍在本连接手上);夺租者
+     * 一旦成功,generation 就变了,这条心跳当场 0 行。`rev = rev + 1` 是 CAS 铁则②:同毫秒重复心跳的
+     * SET 值可能与当前逐字节相同,没有它 MySQL 会把「成功」报成 affectedRows=0。
+     */
+    heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
+    releaseConnection(deviceId: string, generation: number): Promise<boolean>;
+    /**
+     * §4.3.2 首绑写协议 —— **单事务**:设备校验(active ∧ owner)与 `INSERT IGNORE` 在一个事务里。
+     *
+     * 🔴 `beginPessimistic` + `FOR UPDATE`:设备行必须是**当前读**。快照读下,一次与吊销并发的绑定会
+     * 读到「还 active」的旧版本,于是把 session 绑到一台**刚被吊销**的设备上(sql-driver.ts 头注点名的
+     * double-admit 形)。
+     * 并发首绑:`INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected 是引擎对「谁赢」的权威回答;
+     * 输家回读既有行 —— 同 deviceId = 幂等成功,异 deviceId = `conflict`(无未定义态)。
+     */
+    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
+    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
+    deleteByRootSession(rootSessionId: string): Promise<number>;
+    appendAudit(input: AppendAuditInput): Promise<void>;
+    /** 审计写的**唯一**语句(池级与事务内共用;`SqlExec` 是两者的公共面)。 */
+    private insertAuditOn;
+    listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
+}
+/** 方言绑定薄壳(A12 形:ctor 收池,行为全在基类)。 */
+export declare class TiDBDeviceStore extends SqlDeviceStore {
+    constructor(pool: MySqlPool);
+}
+export declare class PgDeviceStore extends SqlDeviceStore {
+    constructor(pool: PgPool);
+}
+export {};
+//# sourceMappingURL=device-store-sql.d.ts.map