@tool-bridge/server 0.21.1 → 0.22.1

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+import { z } from 'zod';
 import * as http from 'node:http';
 import { Sql } from 'postgres';
+import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 
 /**
@@ -27,30 +29,6 @@ interface ListOptions {
 }
 /** "user:alice" | "agent:researcher" | "device:build-01"。 */
 type OwnerRef = string;
-interface CallContext {
-    /** 平台→Plugin envelope 专用:本次调用命中该 plugin 的哪个 export(v2 多 export 路由)。 */
-    exportId?: string;
-    /** 本次调用使用的 SK 的 id(非明文)。 */
-    keyId: string;
-    /** 平台→Plugin envelope 专用:挂载节点 config.providerConfig 透传(每挂载非敏感配置)。 */
-    mountConfig?: Record<string, unknown>;
-    /** 平台→Plugin envelope 专用:本次调用来自哪个挂载节点(同一 plugin 可多路径挂载)。 */
-    mountPath?: TreePath;
-    owner: OwnerRef;
-    /** 反向注册路径收紧规则;缺省按非保留根放行。 */
-    registerPaths?: TreePath[];
-    scopes: Scope[];
-    /** 全链路观测。 */
-    traceId: string;
-}
-type Action = 'read' | 'write' | 'call' | 'register' | 'admin';
-interface Scope {
-    actions: Action[];
-    /** 默认 allow;deny 优先于一切 allow。 */
-    effect?: 'allow' | 'deny';
-    /** 树路径 glob:"**" | "docs/**" | "device/build-01/**"。 */
-    pattern: string;
-}
 
 /**
  * StateStore:宿主注入的状态存储接口。
@@ -126,15 +104,26 @@ interface TBErrorBody {
     retryable: boolean;
 }
 
+/** Roots live in the host's protected bootstrap secret file, never in their own encrypted database. */
+interface EncryptionKeyring {
+    activeKeyId: string;
+    keys: Record<string, string>;
+}
+/** Separate signing roots; encryption-root rotation must not invalidate outstanding capabilities. */
+interface StoreTokenKeyring {
+    activeKeyId: string;
+    keys: Record<string, string>;
+}
+
 /**
  * SecretStore:上游凭证的"只进不出"加密保管。
  *
  * 值经 AES-256-GCM 加密后写入注入的 StateStore(key 布局 `secret:<name>`,store.ts)。
- * 主密钥 `TB_SECRET_ENCRYPTION_KEY` 是部署期 env-only 的 base64url(32 字节)——
- * 信任根不自举存储(spec-digest)。主密钥缺失/格式非法时能力禁用:Set 抛 unavailable。
+ * 版本化加密根由宿主受保护 bootstrap keyring 注入，密文保存 keyId 与 revision。
+ * 信任根不存入被其加密的数据库；缺失/格式非法时能力禁用。
  *
  * 纯逻辑,仅依赖 WebCrypto(core 无宿主依赖)。`crypto` / `TextEncoder` / `TextDecoder`
- * 在 Workers 与 Node 20+ 均为全局;类型经 webGlobals.ts 统一承接(不改 tsconfig、不污染全局)。
+ * 在支持的 JavaScript/Node 运行时均为全局;类型经 webGlobals.ts 统一承接(不改 tsconfig、不污染全局)。
  */
 
 /** system/secret list 的一行(名字与时间戳,永不含值);CLI/Dashboard 经 SDK 消费同一命名。 */
@@ -150,19 +139,13 @@ interface SecretEntrySummary {
  */
 declare class SecretStoreImpl {
     private readonly store;
-    /** 32 字节主密钥;undefined 表示 unavailable 态。 */
-    private readonly keyBytes;
-    /** 惰性导入的 CryptoKey(仅可用时);首次加解密时创建并缓存。 */
-    private importedKey;
-    /**
-     * @param masterKey base64url 编码的 32 字节(TB_SECRET_ENCRYPTION_KEY);
-     *   undefined / 解码失败 / 长度非 32 → 实例处于 unavailable 态。
-     */
-    constructor(store: StateStore, masterKey: string | undefined);
-    private static decodeMasterKey;
-    /** secret 能力是否可用(主密钥有效)。 */
+    private readonly keyring;
+    private readonly importedKeys;
+    constructor(store: StateStore, keys: EncryptionKeyring | string | undefined);
     get available(): boolean;
     private key;
+    private encrypt;
+    private decrypt;
     /**
      * 写入 / 替换 secret;明文仅在此请求中出现。
      * unavailable 态 → 抛 unavailable(retryable:false):主密钥缺失时 Set 不可用。
@@ -186,6 +169,14 @@ declare class SecretStoreImpl {
      * 各 Provider(remote/mcp/http/pluginClient)均按此实现。
      */
     resolve(name: string): Promise<string | undefined>;
+    /** Bounded, resumable re-encryption. Concurrent credential replacement wins over stale ciphertext. */
+    reencryptPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        changed: number;
+        cursor?: string;
+    }>;
 }
 
 /**
@@ -374,9 +365,9 @@ type BuiltinCatalog = Record<string, BuiltinCatalogEntry>;
 /**
  * ObjectStore:对象存储抽象。
  *
- * r2(R2 binding)、s3(aws4fetch)与单测内存实现共用此接口;ContextProvider 的
+ * Node S3、设备本地目录与单测内存实现共用此接口;ContextProvider 的
  * 四动词语义全部落在 objectProvider.ts,后端只做本接口适配。core 无 DOM lib:
- * 流与 body 用最小结构类型声明,与 Workers / Node 的全局 ReadableStream 结构兼容。
+ * 流与 body 用最小结构类型声明,与标准 ReadableStream 结构兼容。
  */
 /** 最小读流(结构兼容全局 ReadableStream<Uint8Array>)。 */
 interface ObjectBodyStream {
@@ -421,7 +412,7 @@ interface ObjectListOptions {
 }
 interface ObjectListResult {
     cursor?: string;
-    /** 文件与折叠前缀按字典序混排(与 R2/S3 行为一致)。 */
+    /** 文件与折叠前缀按字典序混排(与 S3/S3 行为一致)。 */
     items: Array<ObjectMeta | {
         prefix: string;
     }>;
@@ -445,11 +436,6 @@ interface ObjectPresignPutExactOptions extends ObjectPresignPutOptions {
     contentLength: number;
 }
 interface ObjectStore {
-    /**
-     * 可选宿主钩子：清理 prefix 下早于 olderThan 的未落位 staging 临时文件。
-     * staging 不进入 list，且命名/mtime 属于 driver 私有实现；返回实际删除数量。
-     */
-    cleanupStaging?(prefix: string, olderThan: string): Promise<number>;
     /** 幂等:不存在静默。 */
     delete(key: string): Promise<void>;
     get(key: string): Promise<{
@@ -467,6 +453,475 @@ interface ObjectStore {
     put(key: string, body: ObjectBody, opts?: ObjectPutOptions): Promise<ObjectMeta>;
 }
 
+declare const DEFAULT_STORE_NAME: "default";
+type StoreObjectStatus = 'pending' | 'ready' | 'failed' | 'abandoned' | 'deleted';
+type UploadSessionStatus = 'created' | 'completed' | 'aborted' | 'expired' | 'failed';
+type StoreUploadTransport = 'relay' | 'presigned-put';
+type CallUploadCapabilityStatus = 'active' | 'exhausted' | 'revoked' | 'expired';
+type ShareGrantStatus = 'active' | 'revoked' | 'expired';
+interface StoreChecksum {
+    algorithm: 'sha256';
+    value: string;
+}
+/** StoreRepository 内的权威对象记录；driverKey 绝不进入公开 descriptor。 */
+interface StoreObject {
+    backendId: string;
+    /** terminal object 的 driver 字节已完成幂等删除；cleanup 以此避免每轮重复 DELETE。 */
+    bytesDeletedAt?: Timestamp;
+    checksum?: StoreChecksum;
+    contentType: string;
+    createdAt: Timestamp;
+    driverKey: string;
+    etag?: string;
+    expectedChecksum?: StoreChecksum;
+    expectedSize?: number;
+    expiresAt?: Timestamp;
+    filename?: string;
+    id: string;
+    originCallId?: string;
+    owner: OwnerRef;
+    producer?: OwnerRef;
+    readyAt?: Timestamp;
+    revision: number;
+    size?: number;
+    status: StoreObjectStatus;
+    store: typeof DEFAULT_STORE_NAME;
+    updatedAt: Timestamp;
+    uploadId: string;
+}
+/** 每个上传会话都有独立 bearer；StoreRepository 只保存其 sha256。 */
+interface UploadSession {
+    backendId: string;
+    capabilityHash: string;
+    completedAt?: Timestamp;
+    contentType: string;
+    createdAt: Timestamp;
+    expectedChecksum?: StoreChecksum;
+    expectedSize?: number;
+    expiresAt: Timestamp;
+    id: string;
+    maxBytes: number;
+    objectId: string;
+    revision: number;
+    revokedAt?: Timestamp;
+    signingKeyId: string;
+    status: UploadSessionStatus;
+    /** 进入 completed/aborted/expired/failed 的时间，作为幂等保留窗口起点。 */
+    terminalAt?: Timestamp;
+    transport: StoreUploadTransport;
+}
+/** 远程设备调用的窄上传权限；owner 与 producer 都是稳定 OwnerRef，而不是 SK keyId。 */
+interface CallUploadCapability {
+    allowedContentTypes: string[];
+    callId: string;
+    createdAt: Timestamp;
+    expiresAt: Timestamp;
+    id: string;
+    maxBytes: number;
+    maxObjectBytes: number;
+    maxObjects: number;
+    owner: OwnerRef;
+    producer: OwnerRef;
+    reservations: Array<{
+        maxBytes: number;
+        objectId: string;
+    }>;
+    reservedBytes: number;
+    revision: number;
+    signingKeyId: string;
+    status: CallUploadCapabilityStatus;
+    /** 进入 revoked/expired 的时间；exhausted 仍须保留到 expiresAt 供幂等 replay。 */
+    terminalAt?: Timestamp;
+    tokenHash: string;
+}
+/** 首期 share 是匿名、短期、可撤销的 read capability。 */
+interface ShareGrant {
+    createdAt: Timestamp;
+    createdBy: OwnerRef;
+    expiresAt: Timestamp;
+    id: string;
+    objectId: string;
+    revision: number;
+    signingKeyId: string;
+    status: ShareGrantStatus;
+    /** 进入 revoked/expired 的时间，作为撤销传播后的安全保留窗口起点。 */
+    terminalAt?: Timestamp;
+    tokenHash: string;
+}
+
+interface StoreIdempotencyBinding {
+    createdAt: string;
+    domain: 'call' | 'owner';
+    expiresAt: string;
+    fingerprint: string;
+    objectId: string;
+    originCallId?: string;
+    owner: string;
+    producer: string;
+    revision: number;
+    uploadId: string;
+}
+/** Typed entity access; multi-record transitions belong to the domain operations below. */
+interface StoreRecords<T extends {
+    revision: number;
+}> {
+    compare(id: string, revision: number | null, next: T | null): Promise<boolean>;
+    get(id: string): Promise<T | null>;
+    list(opts: {
+        cursor?: string;
+        limit: number;
+    }): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: T;
+        }>;
+    }>;
+}
+interface BeginStoreUpload {
+    binding?: {
+        id: string;
+        record: StoreIdempotencyBinding;
+    };
+    capability?: {
+        id: string;
+        tokenHash: string;
+    };
+    now: string;
+    object: StoreObject;
+    session: UploadSession;
+}
+interface StoreRepository {
+    /** Atomically binds identity, checks/reserves cumulative quota and creates both records. */
+    beginUpload(input: BeginStoreUpload): Promise<{
+        object: StoreObject;
+        session: UploadSession;
+    } | 'backend_changed'>;
+    callCapabilities: StoreRecords<CallUploadCapability>;
+    /** Object readiness and session completion commit together; reservations remain consumed. */
+    finishUpload(object: StoreObject, session: UploadSession): Promise<StoreObject | null>;
+    idempotencyBindings: StoreRecords<StoreIdempotencyBinding>;
+    listReadyObjects(owner: string, opts: {
+        cursor?: string;
+        limit: number;
+    }): Promise<{
+        cursor?: string;
+        items: StoreObject[];
+    }>;
+    objects: StoreRecords<StoreObject>;
+    shares: StoreRecords<ShareGrant>;
+    /** Aborting/expiring/failing cannot race a ready object into an inconsistent session. */
+    terminateUpload(object: StoreObject, session: UploadSession): Promise<boolean>;
+    uploads: StoreRecords<UploadSession>;
+}
+interface StoreBackendResolver {
+    defaultBackend(): Promise<{
+        id: string;
+        objects: ObjectStore;
+    }>;
+    resolveBackend(id: string): Promise<ObjectStore>;
+}
+
+type KeyTarget = 'encryption' | 'signing';
+interface KeyRotateInput {
+    expectedRevision: number;
+    revokeExisting?: boolean;
+    target: KeyTarget;
+}
+interface KeyRetireInput {
+    expectedRevision: number;
+    keyId: string;
+    target: KeyTarget;
+}
+interface KeyResumeInput {
+    jobId: string;
+}
+interface ManagedKeyView {
+    active: boolean;
+    keyId: string;
+    references: number;
+    retireAfter?: string;
+}
+interface KeyRingStatus {
+    activeKeyId: string;
+    keys: ManagedKeyView[];
+}
+interface KeyJobView {
+    changed: number;
+    error?: string;
+    id: string;
+    phase: 'secrets' | 'mailbox' | 'verify';
+    status: 'running' | 'failed' | 'completed';
+    targetKeyId: string;
+}
+interface KeyStatus {
+    encryption: KeyRingStatus;
+    instanceId: string;
+    jobId?: string;
+    jobs: KeyJobView[];
+    revision: number;
+    signing: KeyRingStatus;
+}
+/** Explicit secret export. Never put this result into generic command history or logs. */
+interface KeyBackup {
+    exportedAt: string;
+    instanceId: string;
+    keyring: EncryptionKeyring;
+    oauthKey: string;
+    signingRetireAfter?: Record<string, string>;
+    storeTokenKeyring: StoreTokenKeyring;
+    version: 1;
+}
+interface KeyManagement {
+    backup(): Promise<KeyBackup>;
+    resume(input: KeyResumeInput): Promise<KeyStatus>;
+    retire(input: KeyRetireInput): Promise<KeyStatus>;
+    rotate(input: KeyRotateInput): Promise<KeyStatus>;
+    status(): Promise<KeyStatus>;
+}
+
+interface DeploymentSettings {
+    bindAddress: '127.0.0.1' | '0.0.0.0';
+    hostPort: number;
+    image: string;
+    stateDirectory?: string;
+    uiDirectory?: string;
+}
+interface DeploymentJobView {
+    createdAt: string;
+    error?: string;
+    id: string;
+    revision: number;
+    state: 'queued' | 'claimed' | 'succeeded' | 'failed';
+}
+interface DeploymentStatus {
+    agentConnected: boolean;
+    appliedRevision: number;
+    desired: DeploymentSettings | null;
+    effective: DeploymentSettings | null;
+    instanceId: string;
+    job?: DeploymentJobView;
+    revision: number;
+    state: 'unmanaged' | 'disconnected' | 'applied' | 'pending' | 'applying' | 'failed' | 'drifted';
+}
+interface DeploymentClaim {
+    desired: DeploymentSettings;
+    instanceId: string;
+    jobId: string;
+    leaseExpiresAt: string;
+    leaseToken: string;
+    previous: DeploymentSettings;
+    revision: number;
+}
+interface DeploymentManagement {
+    claim(input: {
+        agentId: string;
+        instanceId: string;
+        observed: DeploymentSettings;
+    }): Promise<{
+        job: DeploymentClaim | null;
+    }>;
+    complete(input: {
+        error?: 'preflight_failed' | 'apply_failed' | 'health_failed' | 'rollback_failed';
+        jobId: string;
+        leaseToken: string;
+        ok: boolean;
+    }): Promise<DeploymentStatus>;
+    get(): Promise<DeploymentStatus>;
+    update(input: {
+        expectedRevision: number;
+        settings: DeploymentSettings;
+    }): Promise<DeploymentStatus>;
+}
+
+declare const databaseMigrationSchema: z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    expectedInstanceId: z.ZodString;
+    databaseUrl: z.ZodString;
+}, z.core.$strict>;
+declare const databaseCredentialRotationSchema: z.ZodObject<{
+    databaseAdminUrl: z.ZodOptional<z.ZodString>;
+    expectedRevision: z.ZodNumber;
+    expectedInstanceId: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strict>;
+declare const redisMaintenanceSchema: z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    redisUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+interface MaintenanceJournal {
+    lastError?: string;
+    operation: 'database' | 'database_credentials' | 'redis';
+    phase: 'running' | 'failed' | 'complete';
+    startedAt: string;
+    step: string;
+}
+interface MaintenanceStatus {
+    database: {
+        host: string;
+        name: string;
+        port: number;
+        user: string;
+    };
+    journal?: MaintenanceJournal;
+    redisConfigured: boolean;
+    revision: number;
+}
+interface MaintenanceManagement {
+    database(input: z.infer<typeof databaseMigrationSchema>): Promise<MaintenanceStatus>;
+    redis(input: z.infer<typeof redisMaintenanceSchema>): Promise<MaintenanceStatus>;
+    rotate_database_credentials(input: z.infer<typeof databaseCredentialRotationSchema>): Promise<MaintenanceStatus>;
+    status(): Promise<MaintenanceStatus>;
+}
+
+/** Plain public output types; schema conformance is checked below without leaking Zod into SDK declarations. */
+type RuntimeConfig = {
+    canonicalOrigin: string;
+    deviceReclaimSec: number;
+    maxHops: number;
+    refThresholdBytes: number;
+    refTtlSec: number;
+    remoteAllowlist: string[];
+    searchConcurrency: number;
+    searchDeadlineMs: number;
+    searchMaxResponseBytes: number;
+    searchMaxSources: number;
+    searchMinChildWorkMs: number;
+    searchReturnReserveMs: number;
+    searchSessionTtlSec: number;
+    shutdownDrainSec: number;
+    storeCallAllowedContentTypes: string[];
+    storeCallMaxBytes: number;
+    storeCallMaxObjectBytes: number;
+    storeCallMaxObjects: number;
+    storeCleanupIntervalSec: number;
+    storeMaxObjectBytes: number;
+    storeReadTtlSec: number;
+    storeRelayMaxBytes: number;
+    storeShareTtlSec: number;
+    storeUploadTtlSec: number;
+    toolCacheTtlSec: number;
+    uploadGrantTtlSec: number;
+};
+type SetupInput = {
+    databaseUrl?: string;
+    redisUrl?: string;
+    settings: RuntimeConfig;
+    storage?: {
+        accessKeyId: string;
+        bucket: string;
+        endpoint: string;
+        region: string;
+        secretAccessKey: string;
+    };
+};
+declare const configUpdateSchema: z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+    settings: z.ZodObject<{
+        canonicalOrigin: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodURL]>>;
+        remoteAllowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxHops: z.ZodDefault<z.ZodNumber>;
+        deviceReclaimSec: z.ZodDefault<z.ZodNumber>;
+        toolCacheTtlSec: z.ZodDefault<z.ZodNumber>;
+        refThresholdBytes: z.ZodDefault<z.ZodNumber>;
+        refTtlSec: z.ZodDefault<z.ZodNumber>;
+        uploadGrantTtlSec: z.ZodDefault<z.ZodNumber>;
+        storeMaxObjectBytes: z.ZodDefault<z.ZodNumber>;
+        storeRelayMaxBytes: z.ZodDefault<z.ZodNumber>;
+        storeCallMaxBytes: z.ZodDefault<z.ZodNumber>;
+        storeCallMaxObjectBytes: z.ZodDefault<z.ZodNumber>;
+        storeCallMaxObjects: z.ZodDefault<z.ZodNumber>;
+        storeCallAllowedContentTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        storeUploadTtlSec: z.ZodDefault<z.ZodNumber>;
+        storeShareTtlSec: z.ZodDefault<z.ZodNumber>;
+        storeReadTtlSec: z.ZodDefault<z.ZodNumber>;
+        storeCleanupIntervalSec: z.ZodDefault<z.ZodNumber>;
+        searchConcurrency: z.ZodDefault<z.ZodNumber>;
+        searchDeadlineMs: z.ZodDefault<z.ZodNumber>;
+        searchMaxResponseBytes: z.ZodDefault<z.ZodNumber>;
+        searchMaxSources: z.ZodDefault<z.ZodNumber>;
+        searchMinChildWorkMs: z.ZodDefault<z.ZodNumber>;
+        searchReturnReserveMs: z.ZodDefault<z.ZodNumber>;
+        searchSessionTtlSec: z.ZodDefault<z.ZodNumber>;
+        shutdownDrainSec: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const revisionSchema: z.ZodObject<{
+    expectedRevision: z.ZodNumber;
+}, z.core.$strict>;
+declare const storageWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    connection: z.ZodObject<{
+        endpoint: z.ZodURL;
+        bucket: z.ZodString;
+        region: z.ZodDefault<z.ZodString>;
+        accessKeyId: z.ZodString;
+        secretAccessKey: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const storageIdSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+declare const storageRevisionSchema: z.ZodObject<{
+    id: z.ZodString;
+    expectedRevision: z.ZodNumber;
+}, z.core.$strict>;
+declare const storageActivateSchema: z.ZodObject<{
+    id: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    expectedActiveRevision: z.ZodNumber;
+}, z.core.$strict>;
+declare const storageRotateSchema: z.ZodObject<{
+    id: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    accessKeyId: z.ZodString;
+    secretAccessKey: z.ZodString;
+}, z.core.$strict>;
+interface ConfigStatus {
+    appliedRevision: number;
+    desired: RuntimeConfig;
+    effective: RuntimeConfig;
+    lastError?: string;
+    revision: number;
+    state: 'applied' | 'pending' | 'applying' | 'failed';
+}
+interface StorageBackendView {
+    active: boolean;
+    activeRevision: number;
+    bucket: string;
+    credentialConfigured: boolean;
+    credentialGeneration: number;
+    endpoint: string;
+    id: string;
+    name: string;
+    region: string;
+    revision: number;
+    validated: boolean;
+    validation?: {
+        at: string;
+        checks: Record<string, boolean>;
+        cleanupSucceeded: boolean;
+    };
+}
+interface ConfigManagement {
+    apply(input: z.infer<typeof revisionSchema>): Promise<ConfigStatus>;
+    get(): Promise<ConfigStatus>;
+    update(input: z.infer<typeof configUpdateSchema>): Promise<ConfigStatus>;
+}
+interface StorageManagement {
+    activate(input: z.infer<typeof storageActivateSchema>): Promise<StorageBackendView>;
+    delete(input: z.infer<typeof storageRevisionSchema>): Promise<{
+        ok: true;
+    }>;
+    get(input: z.infer<typeof storageIdSchema>): Promise<StorageBackendView>;
+    list(): Promise<{
+        items: StorageBackendView[];
+    }>;
+    test(input: z.infer<typeof storageRevisionSchema>): Promise<StorageBackendView>;
+    update(input: z.infer<typeof storageRotateSchema>): Promise<StorageBackendView>;
+    write(input: z.infer<typeof storageWriteSchema>): Promise<StorageBackendView>;
+}
+
 /**
  * Context Layer 类型(原样转写;方法签名异步化以兼容对象存储后端)。
  *
@@ -611,6 +1066,231 @@ interface DeviceCallContext {
     };
 }
 
+interface MailboxQuery {
+    /** Select only queued/expired-lease candidates for this device credential. */
+    claimableBy?: string;
+    cursor?: string;
+    deviceId?: string;
+    limit: number;
+    now?: string;
+    states?: DeviceOperationState[];
+}
+interface MailboxRepository {
+    claimNext(record: DeviceOperationRecord, expectedRevision: number, now: string): Promise<boolean>;
+    compare(operationId: string, revision: number, next: DeviceOperationRecord | null): Promise<boolean>;
+    complete(record: DeviceOperationRecord, expectedRevision: number, now: string): Promise<boolean>;
+    enqueue(record: DeviceOperationRecord, maxPendingPerDevice: number, now: string): Promise<DeviceOperationRecord>;
+    get(operationId: string): Promise<DeviceOperationRecord | null>;
+    list(query: MailboxQuery): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: DeviceOperationRecord;
+        }>;
+    }>;
+    renew(record: DeviceOperationRecord, expectedRevision: number, now: string): Promise<boolean>;
+}
+
+/**
+ * Durable device mailbox authority.
+ *
+ * A domain repository atomically owns quota, candidate claims and valid-lease completion. Arguments and terminal data are
+ * encrypted with a mailbox-specific HKDF child key; the deployment root is
+ * never persisted and this is deliberately at-rest rather than E2E encryption.
+ */
+
+declare const DEVICE_OPERATION_STATES: readonly ["queued", "claimed", "succeeded", "rejected", "failed", "result_unknown", "cancelled", "expired"];
+type DeviceOperationState = typeof DEVICE_OPERATION_STATES[number];
+interface DeviceOperationCaller {
+    keyId: string;
+    owner: OwnerRef;
+}
+interface DeviceOperationSummary {
+    attempt: number;
+    caller: DeviceOperationCaller;
+    cancelRequestedAt?: Timestamp;
+    createdAt: Timestamp;
+    deviceId: string;
+    executionMayHaveOccurred: boolean;
+    expiresAt: Timestamp;
+    leaseUntil?: Timestamp;
+    mountPath: TreePath;
+    operationId: string;
+    state: DeviceOperationState;
+    targetPath: TreePath;
+    terminalAt?: Timestamp;
+    traceId: string;
+    updatedAt: Timestamp;
+}
+interface DeviceOperationDetail extends DeviceOperationSummary {
+    error?: TBErrorBody;
+    result?: unknown;
+}
+interface DeviceOperationClaim {
+    arguments: Record<string, unknown>;
+    attempt: number;
+    caller: DeviceOperationCaller;
+    cancelRequestedAt?: Timestamp;
+    createdAt: Timestamp;
+    expiresAt: Timestamp;
+    leaseId: string;
+    leaseUntil: Timestamp;
+    operationId: string;
+    path: string;
+    targetPath: TreePath;
+    traceId: string;
+}
+type DeviceOperationCompletion = {
+    outcome: 'succeeded';
+    result: unknown;
+} | {
+    error: TBErrorBody;
+    outcome: 'rejected' | 'failed';
+} | {
+    error?: TBErrorBody;
+    outcome: 'result_unknown';
+};
+interface DeviceOperationEnqueueInput {
+    arguments: Record<string, unknown>;
+    caller: DeviceOperationCaller;
+    deviceId: string;
+    deviceKeyId: string;
+    idempotencyKey?: string;
+    mountPath: TreePath;
+    path: string;
+    targetPath: TreePath;
+    traceId: string;
+    ttlSeconds?: number;
+}
+interface DeviceOperationListInput {
+    cursor?: string;
+    deviceId: string;
+    limit?: number;
+    states?: readonly DeviceOperationState[];
+}
+interface DeviceOperationClaimInput {
+    authorize?: (target: DeviceOperationAuthorizationTarget) => Promise<void> | void;
+    cursor?: string;
+    deviceId: string;
+    deviceKeyId: string;
+    limit?: number;
+}
+interface DeviceOperationLeaseInput {
+    authorize?: (target: DeviceOperationAuthorizationTarget) => Promise<void> | void;
+    deviceId: string;
+    deviceKeyId: string;
+    leaseId: string;
+    operationId: string;
+}
+interface DeviceOperationAuthorizationTarget {
+    deviceId: string;
+    deviceKeyId: string;
+    mountPath: TreePath;
+    targetPath: TreePath;
+}
+interface DeviceMailboxPage<T> {
+    cursor?: string;
+    items: T[];
+}
+interface DeviceOperationClaimPage {
+    cursor?: string;
+    operation?: DeviceOperationClaim;
+    serverNow: Timestamp;
+}
+interface DeviceOperationRenewResult {
+    cancelRequestedAt?: Timestamp;
+    leaseUntil: Timestamp;
+    serverNow: Timestamp;
+}
+interface DeviceMailboxCleanupResult {
+    cursor?: string;
+    deleted: number;
+    expired: number;
+    scanned: number;
+}
+interface DeviceMailboxServiceOptions {
+    defaultTtlSeconds?: number;
+    leaseSeconds?: number;
+    /** 分别约束入队 arguments 与终态 result/error 的 canonical JSON 明文字节数。 */
+    maxPayloadBytes?: number;
+    maxPendingPerDevice?: number;
+    maxTtlSeconds?: number;
+    now?: () => number;
+    randomBytes?: (length: number) => Uint8Array;
+    terminalRetentionSeconds?: number;
+}
+interface EncryptedMailboxValue {
+    ciphertext: string;
+    iv: string;
+    keyId: string;
+    v: 1;
+}
+interface DeviceOperationRecord {
+    attempt: number;
+    callerKeyId: string;
+    callerOwner: OwnerRef;
+    cancelRequestedAt?: Timestamp;
+    completedLeaseId?: string;
+    createdAt: Timestamp;
+    deviceId: string;
+    deviceKeyId: string;
+    executionMayHaveOccurred: boolean;
+    expiresAt: Timestamp;
+    idempotencyFingerprint?: string;
+    leaseId?: string;
+    leaseUntil?: Timestamp;
+    mountPath: TreePath;
+    operationId: string;
+    path: string;
+    payload: EncryptedMailboxValue;
+    revision: number;
+    state: DeviceOperationState;
+    targetPath: TreePath;
+    terminalAt?: Timestamp;
+    terminalData?: EncryptedMailboxValue;
+    traceId: string;
+    updatedAt: Timestamp;
+    v: 1;
+}
+declare class DeviceMailboxService {
+    private readonly cipher;
+    private readonly defaultTtlSeconds;
+    private readonly leaseSeconds;
+    private readonly maxPayloadBytes;
+    private readonly maxPendingPerDevice;
+    private readonly maxTtlSeconds;
+    private readonly now;
+    private readonly randomBytes;
+    private readonly terminalRetentionSeconds;
+    private readonly repository;
+    constructor(repository: MailboxRepository, encryptionRoot: EncryptionKeyring | string | undefined, opts?: DeviceMailboxServiceOptions);
+    private nowIso;
+    private read;
+    private summary;
+    private detail;
+    private expireRecord;
+    enqueue(input: DeviceOperationEnqueueInput): Promise<DeviceOperationDetail>;
+    get(deviceId: string, operationId: string): Promise<DeviceOperationDetail>;
+    list(input: DeviceOperationListInput): Promise<DeviceMailboxPage<DeviceOperationSummary>>;
+    claim(input: DeviceOperationClaimInput): Promise<DeviceOperationClaimPage>;
+    private activeLease;
+    renew(input: DeviceOperationLeaseInput): Promise<DeviceOperationRenewResult>;
+    complete(input: DeviceOperationLeaseInput, completionInput: DeviceOperationCompletion): Promise<DeviceOperationDetail>;
+    cancel(deviceId: string, operationId: string): Promise<DeviceOperationDetail>;
+    /** Re-encrypt only unchanged ledger revisions; concurrent lease/terminal transitions retain authority. */
+    reencryptPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        changed: number;
+        cursor?: string;
+    }>;
+    cleanup(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<DeviceMailboxCleanupResult>;
+}
+
 /**
  * 网关侧设备会话状态机(纯逻辑,I/O 与时间注入,DO 只做胶水)。
  *
@@ -695,13 +1375,6 @@ interface ToolSearchOptions {
     mode?: 'keyword';
     pathPrefix?: TreePath;
 }
-/** 会改变候选集合或分页档位的规范化约束；cursor 必须绑定其完整指纹。 */
-interface NormalizedToolSearchOptions {
-    effects?: ToolSearchEffect[];
-    matching: ToolSearchMatching;
-    minCoverage?: number;
-    pathPrefix?: TreePath;
-}
 /** 宿主提供的全局工具索引；权限和虚拟化仍由 gateway 处理。 */
 interface SearchIndex {
     readonly capabilities: readonly SearchCapability[];
@@ -737,93 +1410,25 @@ interface MutableSearchIndex extends SearchIndex {
     }): Promise<void>;
 }
 
-/**
- * SQL SearchIndex 的共享实现——D1、better-sqlite3 与 PostgreSQL 三个 adapter
- * 的编排与候选检索唯一真源。
- *
- * 此前两边各持一份逐行相同的 schema DDL、查询 SQL、material-change 判定与
- * cursor/分页逻辑(共 ~780 行,重合度 >85%),任何一侧改动都得靠人工纪律同步到另
- * 一侧。这里把**所有**与具体驱动无关的部分收进 `SqlSearchIndex`,宿主差异压缩成
- * `SqlSearchDriver` 的五个
- * 方法:
- *
- * - D1 全异步、写入走 `db.batch()`,且单请求有 50 查询预算 —— 故记录插入必须
- *   攒成 JSON1 块(`insertRecords` 返回少量语句)并声明 `assertInsertBudget`;
- * - better-sqlite3 全同步、写入走 `db.transaction()`,无查询预算 —— 逐条插入即可。
- *
- * core 是宿主中立层:这里只产出 SQL 文本与参数数组,不认识 D1Database 也不认识
- * better-sqlite3。
- */
+/** PostgreSQL search SQL: schema, bounded bulk writes and coverage-ranked candidate queries. */
 
-/** 一条待执行语句:SQL 文本 + 按序绑定的参数,不含任何驱动对象。 */
+/** SQL text and ordered PostgreSQL parameters; no runtime driver dependencies. */
 interface SqlSearchStatement {
     readonly params: readonly unknown[];
     readonly sql: string;
 }
-/**
- * 固定形态语句:参数个数与语义在 core 编排里写死,方言只提供 SQL 文本。
- * 占位符语法(`?` / `$n`)与字符串函数由各方言自行决定。
- */
-interface SqlSearchStatements {
-    readonly bumpRevision: string;
-    readonly completeRebuild: string;
-    readonly deleteAllSnapshots: string;
-    readonly deleteAllTools: string;
-    readonly deleteSnapshot: string;
-    readonly deleteSnapshotPrefix: string;
-    readonly deleteTools: string;
-    readonly deleteToolsPrefix: string;
-    /** 单 path 的 path→digest 快照插入(replace 内联使用)。 */
-    readonly insertSnapshot: string;
-    /** 读 meta 单例(revision/seeded/cursor_secret)。 */
-    readonly meta: string;
-    /** replace 前置探测:本 path 的 digest、是否残留 source 行、已用节点数。 */
-    readonly pathState: string;
-    /** 单 path 是否存在 source 行。 */
-    readonly present: string;
-    /** path 或其子树是否存在 source 行。 */
-    readonly presentPrefix: string;
-    /** 全量快照 digest,按 path 升序。 */
-    readonly snapshotDigests: string;
-}
-/**
- * SQL 方言:把与具体引擎绑定的 SQL 文本从数据库无关的编排里分出来。
- *
- * `SqlSearchIndex` 只认识本接口——候选查询 + 一组固定语句 + 建表 DDL。
- * D1 与 better-sqlite3 同为 SQLite,共用 {@link sqliteSearchDialect};其它引擎
- * (如 Postgres)实现自己的方言,替换占位符与大小写折叠语法。方言只管 SQL 文本,
- * 具体驱动的同步/异步、批量预算、结果整形仍由 {@link SqlSearchDriver} 吸收。
- */
-interface SqlSearchDialect {
-    /**
-     * 把已 normalize 的 query 变成候选查询语句(含排序与分页)。三后端共用查询单元
-     * 展开和评分形态，方言只选择占位符语法与 LIKE/ILIKE。
-     */
-    candidateStatement(query: string, limit: number, offset: number, constraints?: NormalizedToolSearchOptions): SqlSearchStatement;
-    /** 建表(幂等),元素不带尾分号。 */
-    readonly schemaStatements: readonly string[];
-    /** 编排直接下发的固定语句。 */
-    readonly statements: SqlSearchStatements;
-}
-/**
- * 宿主驱动:把 `SqlSearchStatement` 落到具体数据库上。
- *
- * `write` 必须原子(D1 `batch` / SQLite `transaction`)——revision bump 与数据变更
- * 分裂会让 cursor 指向不存在的 offset。
- */
+
+/** PostgreSQL SearchIndex orchestration: atomic mutations, snapshot revisions and sealed cursors. */
+
+/** PostgreSQL I/O boundary. All mutations execute in one transaction under the search write lock. */
 interface SqlSearchDriver {
     /** 多行只读查询。 */
     all: <T>(statement: SqlSearchStatement) => Promise<T[]>;
-    /**
-     * 记录插入语句数上限(可选);只有查询预算受限的宿主(D1 50/请求)需要实现。
-     * `count` 是本次 mutation 的记录 + 快照插入语句总数,不含固定的删除/bump。
-     */
-    assertInsertBudget?: (count: number) => void;
-    /** 建表(幂等);构造时已建好的宿主实现成 no-op。 */
+    /** 建表(幂等)，初始化状态由 PG 驱动维护。 */
     ensureSchema: () => Promise<void>;
     /** 单行只读查询;无行返回 null。 */
     first: <T>(statement: SqlSearchStatement) => Promise<T | null>;
-    /** 把记录变成插入语句(JSON1 攒块 or 逐条绑定)。 */
+    /** 把记录分成有界的 PostgreSQL 多行 VALUES 插入语句。 */
     insertRecords: (records: readonly SerializedToolSearchRecord[]) => SqlSearchStatement[];
     /** 把 path→digest 快照变成插入语句。 */
     insertSnapshots: (digests: ReadonlyMap<TreePath, string>) => SqlSearchStatement[];
@@ -832,10 +1437,9 @@ interface SqlSearchDriver {
 }
 declare class SqlSearchIndex implements MutableSearchIndex {
     readonly capabilities: readonly SearchCapability[];
-    protected readonly dialect: SqlSearchDialect;
     protected readonly driver: SqlSearchDriver;
-    constructor(driver: SqlSearchDriver, dialect?: SqlSearchDialect);
-    /** 容量 trigger 的 ABORT 在各驱动里错误形状不同,统一按标记串归一。 */
+    constructor(driver: SqlSearchDriver);
+    /** PG 容量触发器的失败按固定标记归一。 */
     private writeOrCapacity;
     private meta;
     private snapshotDigests;
@@ -851,6 +1455,54 @@ declare class SqlSearchIndex implements MutableSearchIndex {
     cursorFor(query: string, candidate: ToolSearchCandidate, mode?: 'keyword'): Promise<string>;
 }
 
+declare const stateSchema: z.ZodObject<{
+    instanceId: z.ZodUUID;
+    revision: z.ZodNumber;
+    phase: z.ZodEnum<{
+        setup: "setup";
+        installing: "installing";
+        initialized: "initialized";
+    }>;
+    databaseUrl: z.ZodOptional<z.ZodString>;
+    redisUrl: z.ZodOptional<z.ZodString>;
+    internalS3Origin: z.ZodOptional<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+type BootstrapState = z.infer<typeof stateSchema>;
+interface BootstrapSecrets {
+    adminSk: string;
+    keyring: EncryptionKeyring;
+    oauthKey: string;
+    signingRetireAfter?: Record<string, string>;
+    storeTokenKeyring: StoreTokenKeyring;
+}
+interface Pairing {
+    expiresAt: number;
+    instanceId: string;
+    mode: 'setup' | 'recovery';
+    tokenHash: string;
+}
+declare class BootstrapStateStore {
+    readonly directory: string;
+    constructor(directory: string);
+    path(name: string): string;
+    exclusive<T>(run: () => Promise<T>, retries?: number): Promise<T>;
+    read<T>(name: string): Promise<T | undefined>;
+    write(name: string, value: unknown): Promise<void>;
+    state(): Promise<BootstrapState | undefined>;
+    initialize(): Promise<BootstrapState>;
+    private pair;
+    createLocalPairing(mode: Pairing['mode']): Promise<string>;
+    private hash;
+    authorize(token: string | undefined, mode: Pairing['mode']): Promise<BootstrapState>;
+    finish(state: BootstrapState): Promise<void>;
+    defaults(): Promise<(SetupInput & {
+        databaseAdminUrl?: string;
+    }) | undefined>;
+    secureDirectory(): Promise<void>;
+}
+
 /**
  * Plugin 传输客户端:探活、契约抓取、envelope 调用。
  *
@@ -932,6 +1584,14 @@ interface FederatedSearchSettings {
  * 装配在 tbApp.ts。
  */
 
+/** Node S3 adapter configuration; this data type has no host dependencies. */
+interface S3StoreConfig {
+    accessKeyId: string;
+    bucket: string;
+    endpoint: string;
+    region?: string;
+    secretAccessKey: string;
+}
 /** 帧协议 call 转发的入参(id 由调用点生成,幂等键)。 */
 interface DeviceInvokeRequest {
     arguments: Record<string, unknown>;
@@ -941,7 +1601,7 @@ interface DeviceInvokeRequest {
     /** 相对 mountPath 且含命令叶子段,如 "shell/exec"、"fs/get"。 */
     path: string;
 }
-/** 设备通道宿主(CF = DeviceSession DO / Docker = ws)。 */
+/** 宿主提供的设备通道，标准 Node 服务使用 WebSocket。 */
 interface DeviceChannel {
     /** HTTP→WS 调用转发，并显式报告是否已 dispatch，供安全 Mailbox fallback 判定。 */
     invoke(deviceId: string, req: DeviceInvokeRequest): Promise<DeviceCallAttempt>;
@@ -969,30 +1629,49 @@ interface ReadinessReport {
 }
 /**
  * tb app 的宿主注入面(数据/设备五注入点 + 安全出站通道 + 解析后的部署配置)。
- * 核心业务逻辑零分叉:Workers 适配层(app.ts)与 SDK(packages/sdk)都注入此形状。
+ * Node 服务与嵌入式 SDK 共用此形状，业务规则由 app 层统一执行。
  */
 interface TbAppDeps {
+    adminAudit?: (event: {
+        action: string;
+        actor: string;
+        id: string;
+        outcome: 'started' | 'succeeded' | 'failed';
+    }) => Promise<void>;
     /** 放行 http:// 上游(仅本地开发)。 */
     allowInsecureHttp: boolean;
-    /** Dashboard 静态资源(Workers Static Assets);缺省 → /ui 404。 */
+    /** Dashboard 静态资源处理器；缺省 → /ui 404。 */
     assets?: (request: Request) => Promise<Response>;
     /**
      * 规范网关 origin(如 `https://tool-bridge.example.com`)。配置后,OAuth 的
      * redirect_uri 钉在此规范值上,而非每请求动态取 origin——防止实例经多域名
-     * (自定义域 + *.workers.dev 等)访问时,授权 code 在不同域名间被互换。
+     * (例如公开域名与内网域名)访问时，授权 code 在不同域名间被互换。
      * 缺省 → 回退到请求期 origin(单域名部署行为不变)。
      */
     canonicalOrigin?: string;
+    configManagement?: ConfigManagement;
+    /** Snapshot the active backend for binding a newly mounted platform Context. */
+    defaultObjectBackend?: () => Promise<{
+        id: string;
+        objects: ObjectStore;
+    }>;
+    deploymentManagement?: DeploymentManagement;
     /** 设备通道;缺省 → device 能力禁用。 */
     device?: DeviceChannel;
     /** $ref 中转 token 签名密钥(TB_SECRET_ENCRYPTION_KEY);缺省 → /~ref 404、大对象走 presign 或 unavailable。 */
     encryptionKey?: string;
+    encryptionKeyring?: EncryptionKeyring;
     /** 认证前的实例就绪钩子(引导/延迟注册 flush);每请求调用,幂等由宿主保证。 */
     ensureReady?: () => Promise<void>;
+    keyManagement?: KeyManagement;
     /** SDK 进程内 Provider 表(缺省无)。 */
     locals?: LocalProviderHooks;
-    /** context 平台对象存储('r2' provider 的落点);缺省 → 该 provider unavailable。 */
+    mailboxRepository?: MailboxRepository;
+    maintenanceManagement?: MaintenanceManagement;
+    /** context 平台对象存储('storage' provider 的落点);缺省 → 该 provider unavailable。 */
     objects?: () => Promise<ObjectStore> | ObjectStore;
+    /** Resolve an immutable backend identity; never substitute the active backend. */
+    objectStoreForBackend?: (backendId: string) => Promise<ObjectStore> | ObjectStore;
     /**
      * 进程内插件装配表(binding 名 → fetch handler)。manifest.endpoint 为
      * `binding:<name>` 的插件经此直调,零网络跳;未装配的 binding 注册/调用报 unavailable。
@@ -1001,7 +1680,7 @@ interface TbAppDeps {
     /**
      * 内置插件目录(descriptor)。**编译期常量**,由 `@tool-bridge/plugins` 的
      * `catalog.generated.ts` 求值生成 —— 内置插件的目录项与它的代码是同一份构建产物,
-     * 故不会陈旧、也不落库(见 `llmdoc/architecture/plugin-runtime.md`)。
+     * 故不会陈旧、也不落库(见 `llmdoc/plugins/plugin-runtime.mdx`)。
      *
      * 与 {@link pluginBindings} **是一对**:catalog 说"声明了什么"(挂载校验、选 export、
      * 列凭证字段),bindings 说"代码在哪"(实际调用)。装配了 binding 却没给 catalog,
@@ -1016,8 +1695,8 @@ interface TbAppDeps {
     providerOAuthFetch?: typeof fetch;
     /**
      * 后端连通性探测(GET /readyz;k8s readiness)。宿主注入闭包,自行探测其长连接
-     * 后端(PG 池 / Redis)并叠加 draining 状态。缺省 → /readyz 恒 200:请求期绑定
-     * 宿主(Workers 的 KV/D1/R2)无"断连"态,嵌入宿主自理。
+     * 后端(PG 池 / Redis)并叠加 draining 状态。标准服务必须注入；嵌入式宿主
+     * 自行承担后端就绪检查，缺省未注入时 /readyz 返回 200。
      */
     readiness?: () => Promise<ReadinessReport>;
     /** context Get 的 $ref 内联阈值(字节,缺省 1 MiB)。 */
@@ -1028,10 +1707,14 @@ interface TbAppDeps {
     remote: RemoteSettings;
     /** 追加保留根路径(在内置保留根之外额外声明)。 */
     reservedRoots?: string[];
+    /** Host-owned S3 implementation. No signing or Node transport enters app. */
+    s3Objects?: (config: S3StoreConfig) => Promise<ObjectStore> | ObjectStore;
     /** 全局工具搜索索引；缺省或未声明 search capability 时 /~search 不存在。 */
     search?: SearchIndex;
     secrets: SecretStoreImpl;
     state: StateStore;
+    storageManagement?: StorageManagement;
+    storeBackends?: StoreBackendResolver;
     /** call capability 允许的 MIME pattern；缺省 `*\/*`。 */
     storeCallAllowedContentTypes?: string[];
     /** 单次 device call 的聚合上传字节预算。 */
@@ -1046,8 +1729,10 @@ interface TbAppDeps {
     storeReadTtlSec?: number;
     /** relay transport 的有效 request-body 上限；direct 不受此值收紧。 */
     storeRelayMaxBytes?: number;
+    storeRepository?: StoreRepository;
     /** 短期 share 的缺省有效期秒。 */
     storeShareTtlSec?: number;
+    storeTokenKeyring?: StoreTokenKeyring;
     /** Store capability HMAC secret；缺省由 StateStore 原子生成并持久化。 */
     storeTokenSecret?: string;
     /** Store upload session 有效期秒。 */
@@ -1059,127 +1744,38 @@ interface TbAppDeps {
     /** healthz 与 system/status 回显的版本号(单一真源:宿主 package.json)。 */
     version: string;
 }
-/** 请求期变量:认证中间件写入,handler 只读。 */
-type Vars = {
-    ctx: CallContext;
-    store: StateStore;
-};
-
-/**
- * 构造 tool-bridge 的 Hono app(宿主中立;Workers 适配见 app.ts,SDK 装配见 packages/sdk)。
- */
-declare function createTbApp(deps: TbAppDeps): Hono<{
-    Variables: Vars;
-}>;
 
-/**
- * Node 宿主的 env 配置面。变量名与语义对齐 CF 宿主(gateway/src/app.ts 的 Env),
- * 仅新增宿主形态相关的 TB_PORT / TB_HOST / TB_DATA_DIR / TB_UI_DIR / TB_DATABASE_URL。
- * 端口额外兜底平台注入的 PORT(PaaS 通行约定)。
- * Node/Workers 共用字段由 core runtimeEnv Zod schema 解析，本文件只保留 Node 宿主字段。
- */
-
-interface ServerConfig {
-    /** 首次引导的 Admin SK 明文(须经 TB_BOOTSTRAP_ADMIN_SK 预置;缺省且未开 insecure bootstrap 则 fail closed)。 */
+/** Explicit embedding API. The executable loads managed bootstrap + PG configuration. */
+interface ServerConfig extends Partial<RuntimeConfig> {
+    adminAudit?: TbAppDeps['adminAudit'];
     adminSk?: string;
-    /**
-     * 逃生阀:显式放行"缺 Admin SK 时随机生成并打印明文"的旧行为(仅本地/一次性开发)。
-     * 默认 false → 生产/Docker 缺 TB_BOOTSTRAP_ADMIN_SK 时拒绝启动,不把最高权限凭证写日志。
-     */
-    allowInsecureBootstrap: boolean;
     allowInsecureHttp: boolean;
-    /**
-     * 规范网关 origin(TB_CANONICAL_ORIGIN):多域名访问时钉死 OAuth redirect_uri。
-     * 与 Workers 宿主同一解析真源(core normalizeCanonicalOrigin);配置了但非法 →
-     * configFromEnv 抛错,进程拒绝启动(fail closed,不静默回退到请求期 origin)。
-     */
-    canonicalOrigin?: string;
-    /**
-     * Postgres 连接串(TB_DATABASE_URL)。给出则 StateStore 与 SearchIndex 都走 PG
-     * (ILIKE 子串检索,无扩展依赖);缺省回退到 dataDir 下的 SQLite。
-     */
-    databaseUrl?: string;
-    /** SQLite 库与 fs 对象根所在目录(state.sqlite3 + objects/)。 */
+    databaseUrl: string;
     dataDir: string;
-    /** 设备断线后未重连的回收秒数(缺省 24h)。 */
     deviceReclaimSec: number;
-    /** SecretStore 主密钥 + $ref 中转 token 签名密钥(base64url 32B)。 */
-    encryptionKey?: string;
+    encryptionKey: string;
+    encryptionKeyring?: EncryptionKeyring;
     host: string;
-    /**
-     * 平台对象存储(default Store + context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
-     * 缺省回退 dataDir 下的本地 FS。配 S3 后容器可无状态横向扩容 —— FS 落点
-     * 在多副本间互不可见、容器重建即丢。
-     */
-    objectStore?: {
-        accessKeyId: string;
-        bucket: string;
-        endpoint: string;
-        region?: string;
-        secretAccessKey: string;
-    };
-    /**
-     * 进程内插件装配表(binding 名 → fetch handler)。缺省时 bin 入口装配**全量内置目录**
-     * (见 `main.ts`);程序化嵌入方可给自己的表来覆盖或裁剪。
-     */
+    instanceId?: string;
+    internalS3Origin?: string;
+    keyManagement?: TbAppDeps['keyManagement'];
+    maintenanceManagement?: TbAppDeps['maintenanceManagement'];
+    managedSettings?: RuntimeConfig;
+    oauthKey?: string;
+    objectStore?: S3StoreConfig;
     pluginBindings?: PluginBindings;
-    /**
-     * 内置插件目录的 descriptor。与 {@link pluginBindings} 同源装配 —— 只给 bindings
-     * 的话插件调得动但解析不出 export(挂载校验会报"未知 provider")。
-     */
     pluginCatalog?: BuiltinCatalog;
     port: number;
-    /**
-     * 多副本设备通道路由的 Redis 连接串(TB_REDIS_URL)。
-     *
-     * 设备的 WebSocket 是活 socket、只存在于接受它的进程里,故多副本时打给"连在别的
-     * 副本上的设备"的调用必须跨副本转发。配上即启用路由表 + pub/sub 转发;
-     * 单副本部署不需要配(本地直连恒命中)。
-     */
     redisUrl?: string;
-    refThresholdBytes?: number;
-    refTtlSec?: number;
     remote: RuntimeRemoteSettings;
-    /**
-     * 本副本标识(TB_REPLICA_ID),路由表的 value。缺省用 hostname —— 容器平台上
-     * 每个副本的 hostname 天然唯一;同机多进程需显式区分。
-     */
     replicaId?: string;
-    /**
-     * SIGTERM 后先置 draining(/readyz 转 503)再关停的等待秒数(TB_SHUTDOWN_DRAIN_SEC,
-     * 缺省 0)。k8s 滚动更新时 endpoint 摘除有传播延迟,不等一拍就关会把仍被路由过来的
-     * 请求吃闭门羹;单机/本地开发保持 0,关停立即进行。
-     */
-    shutdownDrainSec?: number;
-    /** 设备调用允许上传的 MIME pattern；缺省由应用使用安全默认值。 */
-    storeCallAllowedContentTypes?: string[];
-    /** 设备调用所签发 Store capability 的总字节上限。 */
-    storeCallMaxBytes?: number;
-    /** 设备调用单个 Store 对象的字节上限。 */
-    storeCallMaxObjectBytes?: number;
-    /** 设备调用最多可创建的 Store 对象数。 */
-    storeCallMaxObjects?: number;
-    /** Store 孤儿字节、过期 session/share/call capability 的周期清理间隔。 */
     storeCleanupIntervalSec: number;
-    /** Store 对象统一上限；direct upload 可使用完整值。 */
-    storeMaxObjectBytes?: number;
-    /** Store owner read ref 的有效期。 */
-    storeReadTtlSec?: number;
-    /** relay upload 的宿主有效上限；缺省等于对象统一上限。 */
-    storeRelayMaxBytes?: number;
-    /** Store 匿名可撤销 share 的有效期。 */
-    storeShareTtlSec?: number;
-    /** 显式 Store token 根密钥；缺省由应用在 StateStore 原子生成并持久化。 */
+    storeTokenKeyring?: StoreTokenKeyring;
     storeTokenSecret?: string;
-    /** Store upload session 的有效期。 */
-    storeUploadTtlSec?: number;
-    toolCacheTtlSec?: number;
-    /** Dashboard 静态资源目录覆盖(缺省经 @tool-bridge/dashboard 包解析)。 */
     uiDir?: string;
-    /** create_upload 写入 grant 有效期秒；缺省 min(refTtlSec, 900)。 */
-    uploadGrantTtlSec?: number;
 }
-declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
+/** A request receives one immutable settings snapshot; old grants retain their own limits. */
+declare function runtimeAppSettings(settings: RuntimeConfig, instanceId?: string): Partial<TbAppDeps>;
 
 /**
  * DeviceRouter:多副本部署下的设备调用路由。
@@ -1197,8 +1793,7 @@ declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
  * 本副本自己持有连接时**完全不经这里**(DeviceHub 先查本地 Map),故单副本部署零额外
  * 开销、也不需要配 Redis。
  *
- * 与 CF 宿主的对照:那边用 Durable Object,天然"每设备一个单点",不存在这个问题。
- * 本模块是 Node 多副本的等价物。
+ * 本模块为多副本 Node 服务提供统一的连接所有权与跨进程转发。
  */
 
 /** 路由条目 TTL;续期周期取其 1/3,保证正常情况下不会因抖动过期。 */
@@ -1288,9 +1883,11 @@ declare class DeviceRouter {
 type DeviceLocalCall = (deviceId: string, req: DeviceInvokeRequest) => Promise<DeviceCallAttempt>;
 declare const DEVICE_WS_PATH = "/system/device/ws";
 declare class DeviceHub {
+    private attachedServer;
+    private readonly upgradeHandler;
     private readonly store;
     private readonly search;
-    private readonly reclaimSec;
+    private reclaimSec;
     private readonly wss;
     private readonly activeByDevice;
     private readonly connections;
@@ -1306,6 +1903,7 @@ declare class DeviceHub {
         search?: MutableSearchIndex;
         store: StateStore;
     });
+    setReclaimSec(value: number): Promise<void>;
     /**
      * 启动多副本路由(订阅本副本频道 + 路由续期)。单副本时是 no-op。
      * 必须在开始服务前完成:订阅没建好时转发进来的调用会丢。
@@ -1349,28 +1947,156 @@ declare class DeviceHub {
     private pingConnections;
 }
 
-/**
- * createDataObjectStore:平台对象存储('r2' provider 落点)的 Node 实现。
- *
- * core FsObjectStore 是多根语义(key 首段必须等于某 root 的 basename),而平台
- * 对象存储的 key 是平坦任意前缀(默认 ctx/<nodePath>/...)——本模块做薄前缀适配:
- * 出入口统一加/剥内部根段 'objects/',穿越防护复用 FsObjectStore 的两层防护
- * (normalizeEntryPath + realpath-in-root),不重写。cursor 是内部形态原样透传
- * (消费方视 cursor 为不透明串)。无 presign → $ref 走 /~ref 网关中转(现有降级)。
- */
+interface KeyManagementSnapshot {
+    databaseUrl: string;
+    instanceId: string;
+    replicaId: string;
+    revision: number;
+}
+interface KeyManagementHooks {
+    exclusive<T>(run: () => Promise<T>): Promise<T>;
+    quiesce(): Promise<{
+        resume(): Promise<void>;
+    }>;
+    readKeys(): Promise<BootstrapSecrets>;
+    readSnapshot(): Promise<KeyManagementSnapshot>;
+    /** Reload the stopped local runtime from the persisted bootstrap keys. */
+    reload(): Promise<void>;
+    /** Atomically persist the key file and advance bootstrap revision. */
+    writeKeys(keys: BootstrapSecrets): Promise<number>;
+}
+interface KeyManagerOptions {
+    /** Injection is only for isolated local-PG integration schemas. */
+    connect?: (databaseUrl: string) => Sql;
+    now?: () => Date;
+}
+/** Admin-only key lifecycle. The business pool may be closed during every mutation. */
+declare class KeyManager implements KeyManagement {
+    private readonly hooks;
+    private readonly now;
+    private readonly connect;
+    constructor(hooks: KeyManagementHooks, options?: KeyManagerOptions);
+    private ensure;
+    private rotation;
+    status(): Promise<KeyStatus>;
+    private statusUnderLock;
+    private mutate;
+    rotate(input: Parameters<KeyManagement['rotate']>[0]): Promise<KeyStatus>;
+    resume(input: Parameters<KeyManagement['resume']>[0]): Promise<KeyStatus>;
+    retire(input: Parameters<KeyManagement['retire']>[0]): Promise<KeyStatus>;
+    private revokeSigning;
+    backup(): Promise<KeyBackup>;
+}
+
+interface MaintenanceSnapshot {
+    databaseUrl: string;
+    instanceId: string;
+    redisUrl?: string;
+    replicaId: string;
+    revision: number;
+}
+interface MaintenanceHooks {
+    commit(next: {
+        databaseUrl?: string;
+        expectedRevision: number;
+        redisUrl?: string | null;
+    }): Promise<{
+        revision: number;
+    }>;
+    exclusive<T>(run: () => Promise<T>): Promise<T>;
+    quiesce(): Promise<{
+        resume(): Promise<void>;
+    }>;
+    readDatabaseAdminUrl?(): Promise<string | undefined>;
+    readJournal(): Promise<MaintenanceJournal | undefined>;
+    readSnapshot(): Promise<MaintenanceSnapshot>;
+    writeJournal(journal: MaintenanceJournal): Promise<void>;
+}
+interface PgCommandOptions {
+    /** Explicit executable paths; command strings are never evaluated by a shell. */
+    pgDump?: string;
+    pgRestore?: string;
+    /** Local container integration tests may inject the same official binaries via docker exec. */
+    runCommand?: (program: 'pg_dump' | 'pg_restore', args: string[], env: NodeJS.ProcessEnv) => Promise<void>;
+}
+declare class MaintenanceManager implements MaintenanceManagement {
+    private readonly hooks;
+    private readonly commands;
+    constructor(hooks: MaintenanceHooks, commands?: PgCommandOptions);
+    status(): Promise<MaintenanceStatus>;
+    private execute;
+    private command;
+    database(input: Parameters<MaintenanceManagement['database']>[0]): Promise<MaintenanceStatus>;
+    redis(input: Parameters<MaintenanceManagement['redis']>[0]): Promise<MaintenanceStatus>;
+    rotate_database_credentials(input: Parameters<MaintenanceManagement['rotate_database_credentials']>[0]): Promise<MaintenanceStatus>;
+}
 
-declare function createDataObjectStore(dataDir: string): ObjectStore;
+interface ManagedServerOptions {
+    directory: string;
+    host?: string;
+    port?: number;
+    uiDir?: string;
+}
+/** A limited bootstrap listener exists independently from the database and business app. */
+declare function createManagedServer(options: ManagedServerOptions): Promise<{
+    app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    store: BootstrapStateStore;
+    start(): Promise<{
+        port: number;
+    }>;
+    startDraining: () => void;
+    close: () => Promise<void>;
+    shutdown(): Promise<void>;
+}>;
 
-/**
- * PgSearchIndex:postgres.js 驱动的 SearchIndex(ILIKE 子串检索)。
- *
- * 方言(SQL 文本、$n 占位符、ILIKE 检索)在 core 的 pgSearchDialect;
- * 本文件只吸收 postgres.js 的驱动差异:全异步、写入走 sql.begin() 事务、多行 VALUES
- * 批量插入(PG 无 D1 的 50 查询预算,故不实现 assertInsertBudget)。
- *
- * 不需要任何 PG 扩展:检索是纯 ILIKE,cursor_secret 用内置 gen_random_uuid()。
- * 因此连接角色无需建扩展权限(受限托管环境常不给),只要能建表。
- */
+interface KeyRotationJob {
+    changed: number;
+    cursor: string | null;
+    error: string | null;
+    id: string;
+    phase: 'secrets' | 'mailbox' | 'verify';
+    status: 'running' | 'failed' | 'completed';
+    targetKeyId: string;
+}
+/** Database holds progress only. Keyring material is injected from the protected host secret file. */
+declare class PgKeyRotation {
+    private readonly sql;
+    private readonly secrets;
+    private readonly mailbox;
+    private readonly activeKeyId;
+    constructor(sql: Sql, secrets: SecretStoreImpl, mailbox: DeviceMailboxService, activeKeyId: string);
+    ensureSchema(): Promise<void>;
+    start(targetKeyId?: string): Promise<KeyRotationJob>;
+    get(id: string): Promise<KeyRotationJob>;
+    runBatch(id: string, limit?: number): Promise<KeyRotationJob>;
+    encryptionReferences(keyId: string): Promise<number>;
+    signingReferences(keyId: string, now: string): Promise<number>;
+    countOtherEncryptionReferences(targetKeyId: string): Promise<number>;
+}
+
+/** Indexed operation ledger;
+encrypted payload/result stay opaque to persistence. */
+declare class PgMailboxRepository implements MailboxRepository {
+    private readonly sql;
+    constructor(sql: Sql);
+    ensureSchema(): Promise<void>;
+    get(id: string): Promise<DeviceOperationRecord | null>;
+    list(query: MailboxQuery): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: DeviceOperationRecord;
+        }>;
+    }>;
+    compare(id: string, revision: number, next: DeviceOperationRecord | null): Promise<boolean>;
+    enqueue(record: DeviceOperationRecord, maxPending: number, now: string): Promise<DeviceOperationRecord>;
+    claimNext(record: DeviceOperationRecord, revision: number, now: string): Promise<boolean>;
+    renew(record: DeviceOperationRecord, revision: number, now: string): Promise<boolean>;
+    complete(record: DeviceOperationRecord, revision: number, now: string): Promise<boolean>;
+    private writeUnderLease;
+}
+
+/** PostgreSQL driver: transactions and bounded VALUES batches; search SQL is owned by core/pgSearchSql. */
 
 /** Node 自托管宿主的 postgres.js SearchIndex。 */
 declare class PgSearchIndex extends SqlSearchIndex {
@@ -1380,22 +2106,24 @@ declare class PgSearchIndex extends SqlSearchIndex {
 /**
  * PgStateStore:postgres.js 实现的 StateStore(自托管 Node 宿主的 PG 后端)。
  *
- * 与 SqliteStateStore 同形:单表 kv(key text primary key, value jsonb),值以
+ * 通用状态以单表 kv(key text primary key, value jsonb)保存,值以
  * JSON 存取,强一致。list 用 key 范围扫描(>= prefix AND < successor(prefix)),
  * 不用 LIKE——key 里的路径段可含 '_'/'%',通配符转义是坑。
  *
  * 关键差异——排序 collation:PG 默认按 libc locale 排序,`<` 与 `ORDER BY` 的
- * 顺序会和 JS(UTF-16 code unit)/SQLite(UTF-8 字节)不一致,直接让前缀范围扫描和
+ * 顺序会和 JS(UTF-16 code unit)不一致,直接让前缀范围扫描和
  * cursor 分页错行漏行。故 key 列显式 `COLLATE "C"`(纯字节序),与 core
- * MemoryStateStore / SqliteStateStore 的 cursor 语义对齐。防御性地对返回行再做
+ * MemoryStateStore 的 cursor 语义对齐。防御性地对返回行再做
  * startsWith 过滤。
  */
 
 declare class PgStateStore implements StateStore {
     private readonly sql;
+    private contextRefsEnabled;
     constructor(sql: Sql);
     /** 建表(幂等)。key COLLATE "C" 是字节序正确性的前提,不能省。 */
     ensureSchema(): Promise<void>;
+    ensureContextReferencesSchema(): Promise<void>;
     get(key: string): Promise<unknown | null>;
     getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
     put(key: string, value: unknown): Promise<void>;
@@ -1414,6 +2142,31 @@ declare class PgStateStore implements StateStore {
     }>;
 }
 
+/** PG-only metadata authority. No operation accepts callbacks or performs object/network I/O. */
+declare class PgStoreRepository implements StoreRepository {
+    private readonly sql;
+    readonly objects: StoreRecords<StoreObject>;
+    readonly uploads: StoreRecords<UploadSession>;
+    readonly shares: StoreRecords<ShareGrant>;
+    readonly callCapabilities: StoreRecords<CallUploadCapability>;
+    readonly idempotencyBindings: StoreRecords<StoreIdempotencyBinding>;
+    constructor(sql: Sql);
+    ensureSchema(): Promise<void>;
+    beginUpload(candidate: BeginStoreUpload): Promise<{
+        object: StoreObject;
+        session: UploadSession;
+    } | 'backend_changed'>;
+    finishUpload(object: StoreObject, session: UploadSession): Promise<StoreObject | null>;
+    terminateUpload(object: StoreObject, session: UploadSession): Promise<boolean>;
+    listReadyObjects(owner: string, opts: {
+        cursor?: string;
+        limit: number;
+    }): Promise<{
+        cursor?: string;
+        items: StoreObject[];
+    }>;
+}
+
 /**
  * DeviceRouterBackend 的 Redis(ioredis)实现。
  *
@@ -1441,81 +2194,128 @@ declare class RedisDeviceRouterBackend implements DeviceRouterBackend {
     close(): Promise<void>;
 }
 
-/**
- * createTbServer:Node 宿主装配(对位 gateway/src/app.ts 的 depsFromEnv)。
- *
- * StateStore/SearchIndex 后端二选一:给 TB_DATABASE_URL 走 Postgres,
- * 否则走 dataDir 下的 SQLite。ObjectStore 始终是 fs。HTTP 用 @hono/node-server;
- * 引导在 start() 时直调宿主中立 runBootstrap(Node 有真实启动点,不需要 Workers 的
- * per-request once,故不注入 deps.ensureReady)。设备通道(DeviceHub)与 /ui 静态托管
- * 由后续装配点注入(deps.device / deps.assets)。
- */
+interface S3NetworkOptions {
+    /** Deployment-owned exact origin. Never derive this exception from a user endpoint. */
+    internalOrigin?: string;
+}
+
+interface S3ObjectStoreOptions extends S3NetworkOptions {
+    maxObjectBytes?: number;
+    requestTimeoutMs?: number;
+}
+interface S3ObjectStore extends ObjectStore {
+    close(): void;
+}
+declare function createS3ObjectStore(config: S3StoreConfig, options?: S3ObjectStoreOptions): S3ObjectStore;
+
+interface S3ProbeResult {
+    checks: Record<string, boolean>;
+    cleanupSucceeded: boolean;
+}
+/** Destructive only inside a fresh, unguessable probe namespace in the selected bucket. */
+declare function probeS3ObjectStore(config: S3StoreConfig, options?: S3ObjectStoreOptions): Promise<S3ProbeResult>;
+
+/** The location is immutable. Only the verified credential generation may be replaced. */
+declare class StorageManager implements StorageManagement, StoreBackendResolver {
+    private readonly sql;
+    private readonly secrets;
+    private readonly options;
+    private readonly drivers;
+    constructor(sql: Sql, secrets: SecretStoreImpl, options?: S3ObjectStoreOptions);
+    private record;
+    private view;
+    get({ id }: {
+        id: string;
+    }): Promise<StorageBackendView>;
+    list(): Promise<{
+        items: StorageBackendView[];
+    }>;
+    private connection;
+    resolveBackend(id: string): Promise<ObjectStore>;
+    defaultBackend(): Promise<{
+        id: string;
+        objects: ObjectStore;
+    }>;
+    write(input: Parameters<StorageManagement['write']>[0]): Promise<StorageBackendView>;
+    private assertRevision;
+    test(input: Parameters<StorageManagement['test']>[0]): Promise<StorageBackendView>;
+    activate(input: Parameters<StorageManagement['activate']>[0]): Promise<StorageBackendView>;
+    update(input: Parameters<StorageManagement['update']>[0]): Promise<StorageBackendView>;
+    delete(input: Parameters<StorageManagement['delete']>[0]): Promise<{
+        ok: true;
+    }>;
+    close(): void;
+}
+
+/** PG holds the requested/applied snapshots. A replica reports only successful local application. */
+declare class ConfigManager implements ConfigManagement {
+    private readonly sql;
+    private readonly onApply;
+    private localRevision;
+    private localEffective;
+    private localError;
+    private serial;
+    constructor(sql: Sql, onApply: (settings: RuntimeConfig) => Promise<void>);
+    ensureSchema(defaults?: {
+        canonicalOrigin: string;
+        remoteAllowlist: string[];
+        maxHops: number;
+        deviceReclaimSec: number;
+        toolCacheTtlSec: number;
+        refThresholdBytes: number;
+        refTtlSec: number;
+        uploadGrantTtlSec: number;
+        storeMaxObjectBytes: number;
+        storeRelayMaxBytes: number;
+        storeCallMaxBytes: number;
+        storeCallMaxObjectBytes: number;
+        storeCallMaxObjects: number;
+        storeCallAllowedContentTypes: string[];
+        storeUploadTtlSec: number;
+        storeShareTtlSec: number;
+        storeReadTtlSec: number;
+        storeCleanupIntervalSec: number;
+        searchConcurrency: number;
+        searchDeadlineMs: number;
+        searchMaxResponseBytes: number;
+        searchMaxSources: number;
+        searchMinChildWorkMs: number;
+        searchReturnReserveMs: number;
+        searchSessionTtlSec: number;
+        shutdownDrainSec: number;
+    }): Promise<void>;
+    private row;
+    private exclusive;
+    private install;
+    sync(): Promise<void>;
+    get(): Promise<ConfigStatus>;
+    update(input: Parameters<ConfigManagement['update']>[0]): Promise<ConfigStatus>;
+    apply(input: Parameters<ConfigManagement['apply']>[0]): Promise<ConfigStatus>;
+}
 
 interface TbServer {
-    app: ReturnType<typeof createTbApp>;
-    close(): Promise<void>;
+    app: Hono;
+    close(options?: {
+        excludeCurrentRequest?: boolean;
+    }): Promise<void>;
     deviceHub: DeviceHub;
+    prepare(): Promise<void>;
     search: MutableSearchIndex;
+    settings: ConfigManager;
+    readonly shutdownDrainSec: number;
     /** 引导(幂等)+ 孤儿设备回收排程 + 监听;返回实际端口(config.port=0 时由系统分配)。 */
     start(): Promise<{
         port: number;
     }>;
     /**
      * 进入 draining:/readyz 立即转 503(编排器摘流量),但继续服务既有与新到请求。
-     * SIGTERM 处理器先调它、等一拍(TB_SHUTDOWN_DRAIN_SEC)再 close(),避免 k8s
+     * SIGTERM 处理器先调它、等已应用的 shutdownDrainSec 再 close(),避免 k8s
      * endpoint 摘除传播期间仍被路由过来的请求吃闭门羹。幂等。
      */
     startDraining(): void;
     state: StateStore;
+    storage: StorageManager;
 }
 declare function createTbServer(config: ServerConfig): TbServer;
 
-/** Node 宿主的 better-sqlite3 纯 LIKE SearchIndex。 */
-declare class SqliteSearchIndex extends SqlSearchIndex {
-    private readonly db;
-    constructor(dbPath: string);
-    close(): void;
-}
-
-/**
- * SqliteStateStore:better-sqlite3 实现的 StateStore(Docker/Node 宿主)。
- *
- * 单表 kv(key TEXT PRIMARY KEY, value TEXT)——StateStore 本身就是 kv 语义,
- * 拆表只会复制 key 布局知识。值 JSON 序列化存取(与 KvStateStore 同形)。
- * 强一致:吊销/写入即时可见,无 KV 的最终一致窗口(kvStateStore.ts 的跳 null
- * 与逐 key get 负担在此宿主不存在)。
- *
- * list 用 key 范围扫描(>= prefix AND < successor(prefix)),不用 LIKE/GLOB——
- * key 里的路径段可含 '_'/'%'/'[',通配符转义是坑。cursor/排序语义与
- * core MemoryStateStore 对拍(cursor = 上页末 key,仅在还有更多时返回)。
- * 注意:SQLite TEXT 按 UTF-8 字节序比较,JS 按 UTF-16 code unit 比较,
- * 二者在 ASCII 与 BMP 码点上一致;key 由本项目生成(ASCII 前缀 + 树路径),
- * 防御性地对返回行再做 startsWith 过滤。
- */
-
-declare class SqliteStateStore implements StateStore {
-    private readonly db;
-    private readonly stmtGet;
-    private readonly stmtPut;
-    private readonly stmtDelete;
-    constructor(dbPath: string);
-    get(key: string): Promise<unknown | null>;
-    getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
-    put(key: string, value: unknown): Promise<void>;
-    compareAndSwap(key: string, expectedRevision: number | null, value: unknown | null): Promise<boolean>;
-    putIfAbsent(key: string, value: unknown): Promise<boolean>;
-    delete(key: string): Promise<void>;
-    list(prefix: string, opts?: {
-        cursor?: string;
-        limit?: number;
-    }): Promise<{
-        cursor?: string;
-        items: Array<{
-            key: string;
-            value: unknown;
-        }>;
-    }>;
-    close(): void;
-}
-
-export { DEVICE_FORWARD_TIMEOUT_MS, DEVICE_ROUTE_TTL_SEC, DEVICE_WS_PATH, DeviceHub, type DeviceLocalCall, DeviceRouter, type DeviceRouterBackend, PgSearchIndex, PgStateStore, RedisDeviceRouterBackend, type ServerConfig, SqliteSearchIndex, SqliteStateStore, type TbServer, configFromEnv, createDataObjectStore, createTbServer };
+export { BootstrapStateStore, DEVICE_FORWARD_TIMEOUT_MS, DEVICE_ROUTE_TTL_SEC, DEVICE_WS_PATH, DeviceHub, type DeviceLocalCall, DeviceRouter, type DeviceRouterBackend, type KeyManagementHooks, KeyManager, type MaintenanceHooks, MaintenanceManager, type ManagedServerOptions, PgKeyRotation, PgMailboxRepository, PgSearchIndex, PgStateStore, PgStoreRepository, RedisDeviceRouterBackend, type S3ObjectStore, type S3ObjectStoreOptions, type S3ProbeResult, type ServerConfig, StorageManager, type TbServer, createManagedServer, createS3ObjectStore, createTbServer, probeS3ObjectStore, runtimeAppSettings };