@adep/types 0.1.0 → 0.1.2

package/dist/cloud-container.d.ts

@@ -2,7 +2,9 @@
  * `cloud` 挂载点契约（规范 §4.5 三件套的 Definition 层，任务单 CORE-006）。
  *
  * - **Provider（容器）**：FN-002 在 FunctionContext 上创建并暴露 `register()`，不感知任何具体能力；
- * - **Consumer（能力注册方）**：ST-001 注册 `storage`、DB-003 注册 `db`（M3 起 RT 域注册 `realtime`）；
+ * - **Consumer（能力注册方）**：ST-001 注册 `storage`、DB-003 注册 `db`、FN-020 注册 `realtime`
+ *   （M3 交付的是通道内核，函数内挂载点直到 FN-020 才落地——这段差集曾让「本地能跑、上线报
+ *   能力未注册」成为一处方向相反的本地/线上差异，见 CLI-007 归因）；
  * - 三方只依赖本文件类型，禁止互相 import 内部实现。
  *
  * 新增能力 = 在 `CapabilityRegistry` 加一行 + `Cloud` 上用户即可获得补全——这是能力名的唯一登记处。
@@ -10,12 +12,18 @@
  * 禁止返回 undefined（§4.5 硬规则 3）；类型侧不表达"未注册"，实现方负责。
  */
 import type { CloudDb } from './cloud-db';
+import type { CloudRealtime } from './cloud-realtime';
 import type { CloudStorage } from './cloud-storage';
 import type { CloudFetch } from './cloud-fetch';
-/** 已注册能力名 → 实现契约的映射。M3 起追加 `realtime: CloudRealtime`（规范 §4.5）。 */
+/** 已注册能力名 → 实现契约的映射（能力名的唯一登记处，规范 §4.5）。 */
 export interface CapabilityRegistry {
     db: CloudDb;
     storage: CloudStorage;
+    /**
+     * 实时通道（FN-020）：项目装配了 realtime 域即注入；方法面与本地 sim 同源
+     * （契约见 `cloud-realtime.ts` 的轮询语义警示）。
+     */
+    realtime: CloudRealtime;
     /**
      * 沙箱受控网络（GAME-007）：未配置 `FUNCTIONS_FETCH_ALLOWLIST` 时不注入（无网络安全默认）。
      * 注入时仅可访问白名单主机，受超时与响应体上限约束。

package/dist/cloud-realtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `cloud.realtime` 挂载点契约（规范 §4.5 三件套的 Definition 层，任务单 FN-020）。
+ *
+ * 与 `cloud-db.ts` / `cloud-storage.ts` / `cloud-fetch.ts` 同族：**方法面以本地 sim 为基准**——
+ * CLI-007 已把 `cloud.realtime` 注入 `adep dev` 的模拟运行时，本文件把那份形状升成唯一真相源，
+ * 线上（`server/domains/realtime/cloud.ts`）与本地（`packages/cli/src/sim/realtime.ts`）都实现它。
+ *
+ * ⚠️ **`subscribe` / `receive` 是轮询取件，不是回调式订阅**：RPC 参数走结构化克隆，
+ * 回调函数传不过 worker。任一侧改成回调语义都必须同时改另一侧与 `sim/index.ts` 的边界表，
+ * 否则「本地能跑、上线报错」会以新的形态回来。
+ *
+ * 跨 realm 错误码与方法名表**不在本文件**：`@adep/types` 有「零值导出」硬门
+ * （`contract.test.ts` 钉住），常量一律住 `@adep/runtime/shared/capability-keys`
+ * （`REALTIME_CAPABILITY_CODES` / `REALTIME_CAPABILITY_METHODS`），本地与线上共用那一份。
+ */
+import type { RealtimeChannelMessage } from './realtime';
+/** `publish` 回执：`delivered` = 实际命中的订阅连接数（尽力投递，0 是合法结果）。 */
+export interface CloudRealtimeReceipt {
+    delivered: number;
+}
+/** `subscribe` 回执：`subscription` 是后续 `receive` / `unsubscribe` 的句柄（不透明字符串）。 */
+export interface CloudRealtimeSubscription {
+    subscription: string;
+    channel: string;
+}
+/** 退订回执（与本地 sim 同形：只报「已移除」，不报剩余缓冲量）。 */
+export interface CloudRealtimeUnsubscribeReceipt {
+    removed: true;
+}
+/** 函数内可用的实时通道能力（PRD §2.12 / §2.14.2）。 */
+export interface CloudRealtime {
+    /**
+     * 向 channel 投递一条消息（同步语义：不等订阅者确认，§2.12.3）。
+     * `except` 为「不回发给该连接」的连接标识——**线上支持、本地 fail loud**
+     * （单进程内存广播没有连接身份可比较，见 `sim/boundary.ts`）。
+     */
+    publish(channel: string, data: unknown, except?: string): Promise<CloudRealtimeReceipt>;
+    /** 订阅 channel，取得一个轮询句柄；命中本订阅的消息留在宿主缓冲。 */
+    subscribe(channel: string): Promise<CloudRealtimeSubscription>;
+    /** 取回并清空该句柄的缓冲（非阻塞；无消息返回空数组）。 */
+    receive(subscription: string): Promise<RealtimeChannelMessage[]>;
+    /** 退订并丢弃缓冲。 */
+    unsubscribe(subscription: string): Promise<CloudRealtimeUnsubscribeReceipt>;
+}

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export type ApiErrorCodePrefix = 'AUTH' | 'FN' | 'MCP' | 'STORAGE' | 'BILLING' |
 export type ApiErrorCode = `${ApiErrorCodePrefix}_${string}` | 'INTERNAL' | 'VALIDATION_FAILED' | 'NOT_FOUND';
 export type { CapabilityRegistry, Cloud, CloudContainer } from './cloud-container';
 export type { ChangeOp, ChangeQuery, ChangeRecord, CloudDb, CloudDbTable, Row, SqlOperator, SqlValue, } from './cloud-db';
+export type { CloudRealtime, CloudRealtimeReceipt, CloudRealtimeSubscription, CloudRealtimeUnsubscribeReceipt, } from './cloud-realtime';
 export type { ChainRequest, ChainSpec, ChainStep } from './cloud-chain';
 export type { CapabilityBundle, CapabilityRpcHandler, ExecuteInput, ExecuteResult, ExecutorCapability, ExecutorFunction, ExecutorProject, ExecutorRequest, ExecutorUser, FunctionExecutor, } from './function-executor';
 export type { CloudStorage, FileVisibility, FunctionFile, StoredFile, StorageUploadData, } from './cloud-storage';

package/dist/web-container.d.ts

@@ -7,7 +7,8 @@
  * `NpmRelayFetchRequest` / `NpmRelayFetchResponse`。
  *
  * 能力分层（task FN-012 / tech-stack §2.5：虚拟运行时 / 包管理器适配 / 终端协议均为接口）：
- * - 浏览器内 WASM 虚拟 Linux（QuickJS 或等效引擎，可替换）；
+ * - 浏览器内运行时（现实现为零 WASM 的 Web Worker 沙箱 + 内存 VFS；解释器可替换，
+ *   ADR-0022 裁定的下一个自然选项是 QuickJS-WASM——所以本层是接口不是绑定）；
  * - npm 经平台 `/npm-relay/*` 中继取真实 registry（浏览器跨域限制）。
  */
 /** 虚拟文件系统条目类型。 */

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adep/types",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
   "description": "AgentDeploy 用户 SDK 类型契约（纯类型包，零运行时代码，见任务单 CORE-006）",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
@@ -14,14 +14,10 @@
     "test": "vitest run",
     "build": "bun run ../../scripts/build-package.ts types"
   },
-  "publishConfig": {
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   }
-}
+}