@sema-agent/server 7.50.0 → 7.52.0

package/dist/device-store.js

@@ -0,0 +1,407 @@
+import { createHash, randomBytes, randomInt } from "node:crypto";
+export const DEVICE_ERROR_CODES = {
+    NOT_BOUND: "device.not_bound",
+    OFFLINE: "device.offline",
+    IDENTITY_MISMATCH: "device.identity_mismatch",
+    REVOKED: "device.revoked",
+    PROVIDER_MISMATCH: "device.provider_mismatch",
+    ATTACHED_ELSEWHERE: "device.attached_elsewhere",
+    CLAIM_CONFLICT: "device.claim_conflict",
+    BUSY: "device.busy",
+    ENROLLMENT_INVALID: "device.enrollment_invalid",
+    NOT_FOUND: "not_found.device",
+};
+export const DEVICE_RATE_LIMIT_CODE = "limit.rate_exceeded";
+export const DEVICE_ERROR_STATUS = {
+    "device.not_bound": 409,
+    "device.offline": 409,
+    "device.identity_mismatch": 403,
+    "device.revoked": 403,
+    "device.provider_mismatch": 409,
+    "device.attached_elsewhere": 409,
+    "device.claim_conflict": 409,
+    "device.busy": 429,
+    "device.enrollment_invalid": 403,
+    "not_found.device": 404,
+    "limit.rate_exceeded": 429,
+};
+export const DEVICE_AUDIT_EVENTS = [
+    "device_enrolled",
+    "device_revoked",
+    "device_token_rotated",
+    "device_enroll_token_reuse",
+    "device_frame_unexpected",
+    "device_identity_mismatch",
+    "device_superseded",
+    "device_attached_elsewhere",
+];
+export const DEVICE_PLATFORM_OS = ["darwin", "linux"];
+export const DEVICE_STATUSES = ["active", "revoked"];
+export const DEVICE_KEY_MAX_BYTES = 190;
+export const DEVICE_ID_MAX_BYTES = 64;
+export const DEVICE_SESSION_ID_MAX_BYTES = 128;
+export const DEVICE_PUBKEY_MAX_BYTES = 128;
+function assertIdentityKey(what, v, maxBytes) {
+    if (v.length === 0)
+        throw new Error(`device-store: ${what} must not be empty (identity keys are byte-exact addressable)`);
+    for (let i = 0; i < v.length; i++) {
+        const c = v.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const next = v.charCodeAt(i + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new Error(`device-store: ${what} is not well-formed Unicode (lone high surrogate at ${i}) — it would be silently replaced with U+FFFD on the wire and alias a different key`);
+            i++;
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            throw new Error(`device-store: ${what} is not well-formed Unicode (lone low surrogate at ${i}) — it would be silently replaced with U+FFFD on the wire and alias a different key`);
+        }
+    }
+    if (v.trim() !== v)
+        throw new Error(`device-store: ${what} has leading/trailing whitespace (MySQL PAD SPACE would make it collide with the trimmed key)`);
+    if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f)) {
+        throw new Error(`device-store: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`);
+    }
+    if (Buffer.byteLength(v, "utf8") > maxBytes) {
+        throw new Error(`device-store: ${what} exceeds the ${maxBytes}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`);
+    }
+}
+function assertBoundedText(what, v, maxBytes) {
+    if (Buffer.byteLength(v, "utf8") > maxBytes) {
+        throw new Error(`device-store: ${what} exceeds the ${maxBytes}-byte column (refusing — a silently truncated value is a different value)`);
+    }
+}
+export const DEVICE_TEXT_LIMITS = {
+    displayName: 255,
+    platformArch: 32,
+    workspaceRoot: 1024,
+    actor: 190,
+    revokeReason: 512,
+    connEpoch: 64,
+    replicaId: 128,
+};
+export function assertDeviceOwnerShape(owner) {
+    assertIdentityKey("owner.tenant", owner.tenant, DEVICE_KEY_MAX_BYTES);
+    assertIdentityKey("owner.subject", owner.subject, DEVICE_KEY_MAX_BYTES);
+}
+export function assertDeviceIdShape(deviceId) {
+    assertIdentityKey("deviceId", deviceId, DEVICE_ID_MAX_BYTES);
+}
+export function assertRootSessionIdShape(rootSessionId) {
+    assertIdentityKey("rootSessionId", rootSessionId, DEVICE_SESSION_ID_MAX_BYTES);
+}
+export function assertDevicePubkeyShape(pubkey) {
+    assertIdentityKey("pubkey", pubkey, DEVICE_PUBKEY_MAX_BYTES);
+}
+export function assertNewDeviceShape(input) {
+    assertDeviceIdShape(input.deviceId);
+    assertDeviceOwnerShape(input.owner);
+    assertDevicePubkeyShape(input.pubkey);
+    assertBoundedText("displayName", input.displayName ?? "", DEVICE_TEXT_LIMITS.displayName);
+    assertBoundedText("platformArch", input.platformArch ?? "", DEVICE_TEXT_LIMITS.platformArch);
+    assertBoundedText("workspaceRoot", input.workspaceRoot, DEVICE_TEXT_LIMITS.workspaceRoot);
+}
+export function assertIssueTokenShape(input) {
+    assertEnrollTokenHashShape(input.tokenHash);
+    assertDeviceOwnerShape(input.target);
+    assertWholeSeconds("ttlSeconds", input.ttlSeconds);
+    assertBoundedText("createdBy", input.createdBy, DEVICE_TEXT_LIMITS.actor);
+}
+export function assertRevokeShape(input) {
+    assertDeviceIdShape(input.deviceId);
+    assertDeviceOwnerShape(input.owner);
+    assertBoundedText("revokedBy", input.revokedBy, DEVICE_TEXT_LIMITS.actor);
+    assertBoundedText("revokeReason", input.reason ?? "", DEVICE_TEXT_LIMITS.revokeReason);
+}
+export function assertAcquireShape(input) {
+    assertDeviceIdShape(input.deviceId);
+    assertDeviceOwnerShape(input.owner);
+    assertWholeSeconds("leaseSeconds", input.leaseSeconds);
+    assertBoundedText("connEpoch", input.connEpoch, DEVICE_TEXT_LIMITS.connEpoch);
+    assertBoundedText("replicaId", input.replicaId, DEVICE_TEXT_LIMITS.replicaId);
+}
+export function assertEnrollTokenHashShape(tokenHash) {
+    if (!/^[0-9a-f]{64}$/.test(tokenHash)) {
+        throw new Error(`device-store: tokenHash must be a lowercase sha256 hex digest (64 chars) — a non-canonical form would be a second key for the same token`);
+    }
+}
+export function parseDeviceStatus(v) {
+    const hit = DEVICE_STATUSES.find((s) => s === v);
+    if (!hit)
+        throw new Error(`device-store: unknown device status ${JSON.stringify(v)} (closed set: ${DEVICE_STATUSES.join("|")})`);
+    return hit;
+}
+export function parseDevicePlatformOs(v) {
+    const hit = DEVICE_PLATFORM_OS.find((s) => s === v);
+    if (!hit)
+        throw new Error(`device-store: unknown platform os ${JSON.stringify(v)} (closed set: ${DEVICE_PLATFORM_OS.join("|")})`);
+    return hit;
+}
+export function parseDeviceAuditEvent(v) {
+    const hit = DEVICE_AUDIT_EVENTS.find((s) => s === v);
+    if (!hit)
+        throw new Error(`device-store: unknown device audit event ${JSON.stringify(v)} (closed set: ${DEVICE_AUDIT_EVENTS.join("|")})`);
+    return hit;
+}
+export function assertWholeSeconds(what, seconds) {
+    if (!Number.isInteger(seconds))
+        throw new Error(`device-store: ${what} must be a whole number of seconds (got ${seconds}) — fractional INTERVAL semantics diverge between MySQL and PostgreSQL`);
+    if (!Number.isFinite(seconds) || Math.abs(seconds) > 86_400 * 365)
+        throw new Error(`device-store: ${what} out of range (got ${seconds})`);
+}
+export function hashEnrollToken(plaintext) {
+    return createHash("sha256").update(plaintext, "utf8").digest("hex");
+}
+export function mintEnrollToken() {
+    return randomBytes(16).toString("base64url");
+}
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function mintDeviceId(nowMs = Date.now()) {
+    let ts = Math.max(0, Math.floor(nowMs));
+    const time = [];
+    for (let i = 0; i < 10; i++) {
+        time.unshift(CROCKFORD[ts % 32]);
+        ts = Math.floor(ts / 32);
+    }
+    let rand = "";
+    for (let i = 0; i < 16; i++)
+        rand += CROCKFORD[randomInt(32)];
+    return `dev_${time.join("")}${rand}`;
+}
+function sameOwner(a, b) {
+    return a.tenant === b.tenant && a.subject === b.subject;
+}
+function cloneOwner(o) {
+    return { tenant: o.tenant, subject: o.subject };
+}
+export class InMemoryDeviceStore {
+    devices = new Map();
+    sessions = new Map();
+    tokens = new Map();
+    audit = [];
+    auditSeq = 0;
+    now;
+    constructor(opts) {
+        this.now = opts?.now ?? (() => Date.now());
+    }
+    async issueEnrollToken(input) {
+        assertIssueTokenShape(input);
+        const now = this.now();
+        const row = {
+            tokenHash: input.tokenHash,
+            target: cloneOwner(input.target),
+            createdBy: input.createdBy,
+            createdAtMs: now,
+            expiresAtMs: now + Math.round(input.ttlSeconds * 1000),
+            consumedAtMs: null,
+            consumedDeviceId: null,
+            consumedPubkey: null,
+            rev: 0,
+        };
+        if (this.tokens.has(row.tokenHash))
+            throw new Error("device-store: enrollment token hash already exists (a token hash is minted once)");
+        this.tokens.set(row.tokenHash, row);
+        return { ...row, target: cloneOwner(row.target) };
+    }
+    async consumeEnrollToken(input) {
+        assertEnrollTokenHashShape(input.tokenHash);
+        assertDeviceOwnerShape(input.requester);
+        assertNewDeviceShape(input.device);
+        const token = this.tokens.get(input.tokenHash);
+        if (!token)
+            return { outcome: "unknown_token" };
+        if (!sameOwner(token.target, input.requester))
+            return { outcome: "principal_mismatch" };
+        if (!sameOwner(input.device.owner, input.requester))
+            return { outcome: "principal_mismatch" };
+        const now = this.now();
+        if (token.consumedAtMs !== null) {
+            if (token.consumedPubkey !== input.device.pubkey)
+                return { outcome: "token_reuse" };
+            const existing = token.consumedDeviceId ? this.devices.get(token.consumedDeviceId) : undefined;
+            return { outcome: "replayed", device: existing ? this.snapshotDevice(existing) : null };
+        }
+        if (token.expiresAtMs <= now)
+            return { outcome: "expired" };
+        for (const d of this.devices.values()) {
+            if (d.owner.tenant === input.device.owner.tenant && d.pubkey === input.device.pubkey)
+                return { outcome: "pubkey_taken" };
+        }
+        if (this.devices.has(input.device.deviceId)) {
+            throw new Error(`device-store: minted deviceId ${JSON.stringify(input.device.deviceId)} collided with an existing row (server-minted ids must be unique)`);
+        }
+        const device = {
+            deviceId: input.device.deviceId,
+            owner: cloneOwner(input.device.owner),
+            displayName: input.device.displayName ?? "",
+            platformOs: input.device.platformOs,
+            platformArch: input.device.platformArch ?? "",
+            pubkey: input.device.pubkey,
+            pubkeyRotatedAtMs: null,
+            workspaceRoot: input.device.workspaceRoot,
+            workspaceRootRev: 0,
+            status: "active",
+            revokedAtMs: null,
+            revokedBy: null,
+            revokeReason: null,
+            connEpoch: null,
+            replicaId: null,
+            connGeneration: 0,
+            leaseExpiresAtMs: null,
+            connectedAtMs: null,
+            lastSeenAtMs: null,
+            createdAtMs: now,
+            rev: 0,
+        };
+        token.consumedAtMs = now;
+        token.consumedDeviceId = device.deviceId;
+        token.consumedPubkey = device.pubkey;
+        token.rev += 1;
+        this.devices.set(device.deviceId, device);
+        this.pushAudit({ event: "device_enrolled", deviceId: device.deviceId, owner: device.owner, detail: { platformOs: device.platformOs } });
+        return { outcome: "enrolled", device: this.snapshotDevice(device) };
+    }
+    async getEnrollToken(tokenHash) {
+        assertEnrollTokenHashShape(tokenHash);
+        const row = this.tokens.get(tokenHash);
+        return row ? { ...row, target: cloneOwner(row.target) } : null;
+    }
+    async readDeviceForAdmission(deviceId, owner) {
+        assertDeviceIdShape(deviceId);
+        assertDeviceOwnerShape(owner);
+        const row = this.devices.get(deviceId);
+        if (!row || !sameOwner(row.owner, owner))
+            return null;
+        return { row: this.snapshotDevice(row), online: this.isOnline(row) };
+    }
+    async getDeviceUnscoped(deviceId) {
+        assertDeviceIdShape(deviceId);
+        const row = this.devices.get(deviceId);
+        return row ? this.snapshotDevice(row) : null;
+    }
+    async listDevicesByOwner(owner) {
+        assertDeviceOwnerShape(owner);
+        return [...this.devices.values()].filter((d) => sameOwner(d.owner, owner)).sort((a, b) => (a.deviceId < b.deviceId ? -1 : 1)).map((d) => this.snapshotDevice(d));
+    }
+    async revokeDevice(input) {
+        assertRevokeShape(input);
+        const row = this.devices.get(input.deviceId);
+        if (!row || !sameOwner(row.owner, input.owner))
+            return { outcome: "not_found" };
+        if (row.status === "revoked")
+            return { outcome: "already_revoked", row: this.snapshotDevice(row) };
+        row.status = "revoked";
+        row.revokedAtMs = this.now();
+        row.revokedBy = input.revokedBy;
+        row.revokeReason = input.reason ?? null;
+        row.leaseExpiresAtMs = null;
+        row.connGeneration += 1;
+        row.rev += 1;
+        this.pushAudit({ event: "device_revoked", deviceId: row.deviceId, owner: row.owner, detail: { revokedBy: input.revokedBy, reason: input.reason ?? null } });
+        return { outcome: "revoked", row: this.snapshotDevice(row) };
+    }
+    async acquireConnection(input) {
+        assertAcquireShape(input);
+        const row = this.devices.get(input.deviceId);
+        if (!row || !sameOwner(row.owner, input.owner))
+            return { outcome: "device_not_found" };
+        if (row.status !== "active")
+            return { outcome: "device_revoked" };
+        const now = this.now();
+        if (row.leaseExpiresAtMs !== null && row.leaseExpiresAtMs > now)
+            return { outcome: "attached_elsewhere", generation: row.connGeneration };
+        row.connGeneration += 1;
+        row.connEpoch = input.connEpoch;
+        row.replicaId = input.replicaId;
+        row.leaseExpiresAtMs = now + Math.round(input.leaseSeconds * 1000);
+        row.connectedAtMs = now;
+        row.lastSeenAtMs = now;
+        row.rev += 1;
+        return { outcome: "acquired", generation: row.connGeneration };
+    }
+    async heartbeatConnection(input) {
+        assertDeviceIdShape(input.deviceId);
+        assertWholeSeconds("leaseSeconds", input.leaseSeconds);
+        const row = this.devices.get(input.deviceId);
+        if (!row || row.connGeneration !== input.generation || row.status !== "active")
+            return false;
+        const now = this.now();
+        row.lastSeenAtMs = now;
+        row.leaseExpiresAtMs = now + Math.round(input.leaseSeconds * 1000);
+        row.rev += 1;
+        return true;
+    }
+    async releaseConnection(deviceId, generation) {
+        assertDeviceIdShape(deviceId);
+        const row = this.devices.get(deviceId);
+        if (!row || row.connGeneration !== generation)
+            return false;
+        row.leaseExpiresAtMs = null;
+        row.rev += 1;
+        return true;
+    }
+    async bindSession(input) {
+        assertRootSessionIdShape(input.rootSessionId);
+        assertDeviceIdShape(input.deviceId);
+        assertDeviceOwnerShape(input.owner);
+        const device = this.devices.get(input.deviceId);
+        if (!device || !sameOwner(device.owner, input.owner))
+            return { outcome: "device_not_found" };
+        if (device.status !== "active")
+            return { outcome: "device_revoked" };
+        const existing = this.sessions.get(input.rootSessionId);
+        if (existing) {
+            const same = existing.deviceId === input.deviceId && sameOwner(existing.owner, input.owner);
+            return { outcome: same ? "idempotent" : "conflict", row: this.snapshotSession(existing) };
+        }
+        const row = {
+            rootSessionId: input.rootSessionId,
+            deviceId: input.deviceId,
+            owner: cloneOwner(input.owner),
+            boundAtMs: this.now(),
+            rev: 0,
+        };
+        this.sessions.set(row.rootSessionId, row);
+        return { outcome: "bound", row: this.snapshotSession(row) };
+    }
+    async getSessionBinding(rootSessionId) {
+        assertRootSessionIdShape(rootSessionId);
+        const row = this.sessions.get(rootSessionId);
+        return row ? this.snapshotSession(row) : null;
+    }
+    async deleteByRootSession(rootSessionId) {
+        assertRootSessionIdShape(rootSessionId);
+        return this.sessions.delete(rootSessionId) ? 1 : 0;
+    }
+    async appendAudit(input) {
+        this.pushAudit(input);
+    }
+    async listAudit(filter) {
+        const limit = filter?.limit ?? 100;
+        return this.audit
+            .filter((r) => (filter?.deviceId === undefined || r.deviceId === filter.deviceId) && (filter?.event === undefined || r.event === filter.event) && (filter?.owner === undefined || (r.owner !== null && sameOwner(r.owner, filter.owner))))
+            .slice(0, limit)
+            .map((r) => ({ ...r, owner: r.owner ? cloneOwner(r.owner) : null }));
+    }
+    isOnline(row) {
+        return row.status === "active" && row.leaseExpiresAtMs !== null && row.leaseExpiresAtMs > this.now();
+    }
+    pushAudit(input) {
+        this.auditSeq += 1;
+        this.audit.push({
+            id: this.auditSeq,
+            atMs: this.now(),
+            event: input.event,
+            deviceId: input.deviceId ?? null,
+            owner: input.owner ? cloneOwner(input.owner) : null,
+            detail: input.detail === undefined ? null : structuredClone(input.detail),
+        });
+    }
+    snapshotDevice(row) {
+        return { ...row, owner: cloneOwner(row.owner) };
+    }
+    snapshotSession(row) {
+        return { ...row, owner: cloneOwner(row.owner) };
+    }
+}
+export { sameOwner as sameDeviceOwner, cloneOwner as cloneDeviceOwner };
+//# sourceMappingURL=device-store.js.map

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

@@ -0,0 +1,182 @@
+/**
+ * device lane **WS 汇聚端**(design/device-executor-lane-v2 §5.2 连接状态机 / §5.3 双层超时 /
+ * §5.4 重连与幂等 / §5.5 背压 / §8-R7 发版排空)—— 本仓**首个** WS 服务端。
+ *
+ * ── 三条它必须同时守住的不变量 ───────────────────────────────────────────────────────────────────
+ *  ① **at-most-once**:一条指令至多在设备上执行一次。`dispatch_committed` 是**不可回退的单向门**,
+ *     且在**首次 socket 写之前**原子落定 —— `ws.send()` 成功只证明字节进了本机缓冲。commit 之后的
+ *     一切不确定恒收敛到 `outcome_unknown`,**永不重发**(§5.3/§5.4)。
+ *  ② **世代闸**:设备侧**所有**可变状态帧携 `gen`,判据 = **严格等于**本 socket 协商世代(非 ≥)。
+ *     旧世代的 result/chunk/heartbeat/goodbye 在进任何缓冲之前即被拒 + 审计(D-P4 四格)。
+ *  ③ **结果帧四不变量**(§5.1):已鉴权且 deviceId 与 pending 行一致 / instructionId 在本进程 pending
+ *     表且态 = `dispatch_committed` / `deviceSeq` 单调(重复 = 幂等吸收) / `streamSeq` 连续
+ *     (乱序缓冲,缺片 = 指令失败**而不是**静默截断)。
+ *
+ * ── A-2 → A-3 的移交义务(工作稿「着陆实况」三条,逐条兑现在哪儿)────────────────────────────────
+ *  ① **下发边界必须重新断言世代**(codex F4):`admitSession` 给的 `connGeneration` 只是一个**快照**,
+ *     它与真正写 socket 之间可以插进一次 `revokeDevice`。所以 {@link createDeviceWsHub} 的 dispatch 在
+ *     写 socket 之前做三重断言:socket 世代 === 判决世代、本 conn 仍是该设备的当前连接、以及一次
+ *     **带世代谓词的库写**(`heartbeatConnection`)—— 影响 0 行 = 本连接已失权 ⇒ 停发 + `bye` + 断连。
+ *     🔴 **诚实残余**:这三条关不掉「断言通过之后、`ws.send` 之前」的那一瞬。窗口上界 = 租约续期拍距
+ *     (`leaseRenewIntervalMs`,默认 = 心跳周期):吊销后最迟一拍,连接就会在续租里发现失权并断开。
+ *     窗内已发出的指令按 §8-R4 记账 —— 在途结果帧丢弃 + 审计,对应调用按 outcome-unknown 收尾。
+ *     真正的最终防线在**设备侧**(§5.4 ⑦ 单实例锁 + 严格等值世代判据),云侧关不了这一格。
+ *  ② 事务内回读同连接(`readDeviceOn`)是**店内**规矩;本车不新增任何 SQL,只消费店契约。
+ *  ③ 消费 A-2 预留的两个码(`device.busy` / `device.attached_elsewhere`)与两个审计词
+ *     (`device_frame_unexpected` / `device_superseded`)—— 见下方各自的落点。
+ *
+ * ── 为什么 upgrade 处理器必须显式处理「不认的路径」────────────────────────────────────────────────
+ * node 的默认行为是「没有 'upgrade' 监听器就销毁 socket」。挂上第一个监听器之后那条默认**失效**,
+ * 于是不认的路径若直接 `return`,socket 会挂着直到超时。所以这里显式回 404 并销毁。
+ * ⚠️ 将来出现**第二个** upgrade 消费方时,这里要改成一张路由表 —— 两个 `server.on("upgrade")`
+ * 监听器会**同时**收到每一次 upgrade,各自「不认就 404」会互相把对方的连接打死。
+ *
+ * ── 安全轴姿势(#157)────────────────────────────────────────────────────────────────────────────
+ * 未知帧型 / 坏形帧 / 世代不符 / pending 外 instructionId = **响亮拒 + 审计行**,没有一处空 catch,
+ * 没有一处「认不出就当默认值」。审计写失败本身也是响亮的(logger.error + 计数),不是静默吞。
+ */
+import http from "node:http";
+import { type DeviceOwner, type DeviceStore } from "./device-store.js";
+import type { DeviceEnrollment, DeviceRejection } from "./device-enrollment.js";
+import { type DeviceChunkKind, type DeviceInstructionArgsByKind, type DeviceInstructionKind, type DeviceInstructionOutcome } from "./device-ws-protocol.js";
+/** 交给调用方的一片上行流(`data` 已从 base64 解回字节)。 */
+export interface DeviceChunkDelivery {
+    streamSeq: number;
+    kind: DeviceChunkKind;
+    data?: Buffer;
+    exitCode?: number;
+}
+/**
+ * 一次下发的入参。`kind` 与 `args` **按 kind 判别**(§5.1 task-R1-8),不是 `any`。
+ *
+ * `payload` = 大载荷下行(writeFile 族):内容不进指令帧,走 `payload` begin→chunk→commit 子序;
+ * 长度与 sha256 由**本层**按真字节重算写回 args —— 调用方报的摘要不作数(它不是那份字节的权威)。
+ */
+export type DeviceDispatchInput = {
+    [K in DeviceInstructionKind]: {
+        rootSessionId: string;
+        requester: DeviceOwner;
+        kind: K;
+        args: DeviceInstructionArgsByKind[K];
+        cwd?: string;
+        shellEnv?: Record<string, string>;
+        timeoutMs: number;
+        payload?: Uint8Array;
+        payloadPartBytes?: number;
+        onChunk?: (chunk: DeviceChunkDelivery) => void;
+        /**
+         * 铸造期快照的**否定面**(codex R3-F1):调用方在铸自己那一刻**没有**看到这几个指令 kind,
+         * 所以它的对外面上没有对应的方法。若投递门这一刻的连接**声明了**其中任何一个 ⇒ 拒。
+         *
+         * 🔴 为什么这条判据非放在这里不可:调用方侧那一次检查与真正的下发之间隔着 `admitSession` 的一次
+         * SQL 往返 —— 设备可以在这个窗口里断开、以**更强**的能力连回来,于是检查看到的是旧连接、指令却
+         * 打到新连接上(TOCTOU)。而投递门是本进程里**唯一**同时持有「最终选中的连接」与「不可回退的
+         * commit」的地方,原子复核只能在这儿做。语义与世代重断言同族(A-2 移交义务①),放在同一段。
+         *
+         * 用途在 device lane 上是**保护型写原语**(`writeFileGuarded`/`writeFileExclusive`):它们的缺席被
+         * core 读成「后端没有这个原语」并降级成非原子写,所以「铸的时候没有、下发的时候有了」= 一次静默的
+         * 保护降级(#157)。本座本身与语义无关,只做集合判断。
+         */
+        refuseIfDeclared?: readonly DeviceInstructionKind[];
+        /**
+         * 车A-4(A-3 残余⑤):调用方的取消轴。
+         *
+         * 🔴 **为什么这个座必须在 hub 而不是调用方自己接**:`instructionId` 是在**投递门内部**铸的,
+         * `dispatch` 直到结算才 resolve —— 调用方结构上拿不到那个 id,所以它自己的 abort 监听只能做到
+         * 「放弃等待」,而设备上那条命令还在跑(§5.4 at-most-once 的反面:一次不可见的执行)。座放在这里,
+         * abort ⇒ 真发 `cancel` 帧,终局回执照常走 §5.3 的 10s 宽限。
+         * 投递门**之前** abort ⇒ `terminal_never_started`(设备结构上没见过它,安全)。
+         */
+        signal?: AbortSignal;
+    };
+}[DeviceInstructionKind];
+/**
+ * 下发结果的三态 —— 与 {@link DeviceInstructionState} 的两条路径 1:1。
+ *
+ *  • `settled`:过了投递门(`dispatch_committed`)并拿到终局。**含**失败结局(设备回的 error /
+ *    云侧兜底的 `outcome_unknown`)—— 它们都是「设备可能已经执行过」的世界。
+ *  • `never_started`:`terminal_never_started` —— 设备结构性不可能见过它(能力未声明)。可安全重试。
+ *  • `rejected`:准入/背压/失权,**在投递门之前**。同样安全(§5.3 投递边界)。
+ */
+export type DeviceDispatchResult = {
+    kind: "settled";
+    instructionId: string;
+    outcome: DeviceInstructionOutcome;
+} | {
+    kind: "never_started";
+    outcome: DeviceInstructionOutcome;
+} | {
+    kind: "rejected";
+    reject: DeviceRejection;
+};
+export interface DeviceWsHubLogger {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    info?(msg: string, fields?: Record<string, unknown>): void;
+}
+export interface DeviceWsHubOptions {
+    store: DeviceStore;
+    /** 准入链(§4.3.2)。WS 汇聚端**不自建判据**,一律经它。 */
+    enrollment: DeviceEnrollment;
+    /** 本副本 id(写进连接租约行,跨副本排障用)。 */
+    replicaId: string;
+    logger?: DeviceWsHubLogger;
+    metrics?: {
+        inc(name: string, labels?: Record<string, string>): void;
+    };
+    /** 下发给设备的心跳周期(helloAck 协商);丢 `heartbeatMisses` 拍判 STALE。 */
+    heartbeatIntervalMs?: number;
+    heartbeatMisses?: number;
+    /** 连接租约时长(整秒,自 DB now 起算)。 */
+    leaseSeconds?: number;
+    /** 服务端续租/失权侦测的拍距。缺省 = `heartbeatIntervalMs`(见文件头「诚实残余」)。 */
+    leaseRenewIntervalMs?: number;
+    /** per-device 在途上限(§11-O3 clay 已裁 = 4)。 */
+    maxInflightPerDevice?: number;
+    /** 等在途槽的上限;到期 = `device.busy`(§5.5,429 语义)。 */
+    dispatchTimeoutMs?: number;
+    /** 云侧执行超时兜底的宽限(§5.3:`timeoutMs + grace` ⇒ outcome_unknown)。 */
+    execGraceMs?: number;
+    /** cancel 终局回执宽限(§5.3)。 */
+    cancelGraceMs?: number;
+    /** 断连后在途不判丢的窗(§5.4 同 epoch 重连);窗尽 ⇒ outcome_unknown。 */
+    reconnectGraceMs?: number;
+    /** 上行流片缺口的等待上限;到期 = 指令失败(**不是**静默截断)。 */
+    chunkGapTimeoutMs?: number;
+    /** §5.2 顶替旋钮:`stale_only`(默认)= 只顶替已 STALE 的旧连;`deny` = 重连也须等旧连宽限尽。 */
+    supersede?: "stale_only" | "deny";
+    /** codex R1-F5:per-instruction 乱序缓冲的条目帽(超出 = 指令失败 + 审计)。 */
+    chunkBufferMaxEntries?: number;
+    /** codex R1-F5:per-instruction 乱序缓冲的**解码后**字节帽(§5.5 的 2MiB)。 */
+    chunkBufferMaxBytes?: number;
+    /** codex R1-F3:本副本**未鉴权**连接的并发帽(超额在 upgrade 阶段就 503 拒)。 */
+    maxPreAuthConnections?: number;
+    /** codex R1-F3:单来源地址的未鉴权连接并发帽。 */
+    maxPreAuthConnectionsPerRemote?: number;
+}
+export interface DeviceWsHub {
+    /** 把 `GET /v1/device/ws` 的 upgrade 处理器挂到裸 `http.Server` 上。 */
+    attach(server: http.Server): void;
+    dispatch(input: DeviceDispatchInput): Promise<DeviceDispatchResult>;
+    /** 幂等:重复 cancel 同一指令 = no-op(§5.3)。 */
+    cancel(instructionId: string): Promise<void>;
+    /** §8-R7:停发新指令 + 拒新 upgrade,但**保持既有 WS**,在途结果帧照收。 */
+    beginDrain(): void;
+    isDraining(): boolean;
+    connectedDeviceIds(): string[];
+    /**
+     * 车A-4:该设备**当前连接**在 hello 里声明的指令面(与本 server 的闭集取过交集之后的那一份)。
+     * 没有活连接 ⇒ `undefined`(**不是**空集:「不知道」与「明确什么都不支持」是两件事)。
+     *
+     * 🔴 用途只有一个,而且是 core 契约逼出来的:`writeFileExclusive`/`writeFileGuarded` 是
+     * **presence-typed** 可选面 —— core 的降级律逐字要求「后端没有该原语就把方法留 undefined,禁两步
+     * 仿真」,所以「在不在场」必须在**铸 env 的那一刻**答得出来,不能等到第一次调用再回 not_supported
+     * (那时调用方已经按「有原子面」走了)。
+     * 诚实残余:设备**在铸 env 之后**才连上时,这一问答的是 undefined ⇒ 该面缺席 ⇒ 写门如实降级成
+     * 「advisory adjudication」而不是宣称关闭了 TOCTOU —— 方向是安全的那一侧。
+     */
+    declaredSupports(deviceId: string): ReadonlySet<DeviceInstructionKind> | undefined;
+    close(): Promise<void>;
+}
+export declare function createDeviceWsHub(options: DeviceWsHubOptions): DeviceWsHub;
+//# sourceMappingURL=device-ws-hub.d.ts.map