@adep/runtime 0.1.0

package/dist/shared/capability-keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 能力运输键常量（CORE-018 上移自 functions 域）：
+ * RPC 能力标记 + 链式命令通道标记 + 方法码。
+ *
+ * **纯常量文件，无类 / 无 parameter properties**——worker 侧用 strip-only 模式转译钟 import 本文件，
+ * 故绝不能在此引入 `ExecutorError`（见 `executor-runtime.ts` 头注释的边界）。
+ * 消费方（storage / database / realtime / mcp、functions 的 worker）经 `shared/` 依赖。
+ */
+/** 平坦式 RPC 能力标记：值含该属性的 capability 视为命令通道能力（ST-001 命令通道设计）。 */
+export declare const RPC_CAPABILITY_KEY: "__adepRpc";
+/** 链式能力的标记键（与 `RPC_CAPABILITY_KEY` 并列，CORE-006 能力运输的第二形态）。 */
+export declare const CHAIN_CAPABILITY_KEY: "__adepChain";
+/** 链式能力与其他能力的传输方法码（worker ↔ 宿主 db handler 共享）。 */
+export declare const DB_RPC: {
+    /** 直通方法（如 query）：`(method=query, args=[sql, params])`。 */
+    readonly query: "query";
+    /** 读取 owned 表变更流（DB-006）：`(method=changes, args=[table, query])`。 */
+    readonly changes: "changes";
+    /** 开启事务：`begin → txId`。 */
+    readonly begin: "begin";
+    /** 提交事务：`commit, args=[txId]`。 */
+    readonly commit: "commit";
+    /** 回滚事务：`rollback, args=[txId]`。 */
+    readonly rollback: "rollback";
+    /** 执行一条链：`chain, args=[ChainRequest]`。 */
+    readonly chain: "chain";
+};

package/dist/shared/executor-runtime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 执行器运行时契约（CORE-018 上移自 functions 域）：错误类型与限额错误码。
+ *
+ * 独立成文件的原因（承自 functions/runtime/rpc-key.ts 的教训）：worker 侧用 strip-only 模式
+ * 转译（不支持构造函数参数属性），任何被 worker 间接 import 的模块都不能带 `ExecutorError` 的
+ * parameter properties——故本文件与纯常量的 `capability-keys.ts` 分离，worker 只 import 后者。
+ *
+ * 消费方（functions / realtime / mcp）经 `shared/` 依赖，不再跨域 import functions 内部实现。
+ */
+/** 执行失败的统一形状（网关回 504/500 信封）。 */
+export declare class ExecutorError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** 超时错误码（FN-002 限额：超时 → 504 级执行失败）。 */
+export declare const TIMEOUT_CODE = "FN_EXEC_TIMEOUT";
+/** 内存耗尽错误码（FN-002 限额：OOM → 5xx 级执行失败）。 */
+export declare const OOM_CODE = "FN_EXEC_OOM";
+/** 执行超时缺省值（毫秒）。 */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** 内存上限缺省值（MB）。 */
+export declare const DEFAULT_MEMORY_LIMIT_MB = 128;
+/** 可作为函数错误状态的合法 HTTP 码区间（FN-011：业务可表达 4xx/5xx 语义）。 */
+export declare function isHttpStatus(status: unknown): status is number;
+/**
+ * 函数抛错携带的 status 归一化（FN-011 error status pass-through）。
+ * 合法 4xx/5xx 整数原样返回；缺失 / 非法一律折叠为默认 500（兼容旧形态——普通 Error 抛错仍 500）。
+ */
+export declare function normalizeHttpStatus(status: unknown): number;

package/dist/shared/function-source.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 函数服务源码解析（CORE-018 上移自 functions/runtime/forward.ts）。
+ *
+ * 被网关转发链与 MCP 工具发布复用「读当前服务源码」这一行为：发布版本优先、无则草稿。
+ * **松耦合**：只依赖最小结构接口（functionFiles / functionVersions 的读取面），
+ * 不 import `PlatformDb` / functions 域内部——消费方（gateway / mcp）传入自己的 db 即结构兼容。
+ *
+ * 纯函数 + 结构接口，零运行时依赖（规范 §4，shared 纯性）。
+ */
+/** `resolveFunctionSource` 需要的最小 DB 读取面：只声明用到的两个仓库方法。结构兼容 `PlatformDb`。 */
+export interface FunctionSourceDb {
+    readonly functionFiles: {
+        /** 按路径升序返回草稿文件组；无草稿返回空数组。 */
+        listByFunction(functionId: string): Promise<ReadonlyArray<{
+            path: string;
+            content: string;
+        }>>;
+    };
+    readonly functionVersions: {
+        /** 按函数 + 版本号精确读取；不存在返回 null。 */
+        findByFunctionAndVersion(functionId: string, version: number): Promise<{
+            code: string;
+        } | null>;
+    };
+}
+/** `resolveFunctionSource` 需要的函数投影：id（读草稿）与服务版本号。 */
+export interface SourceFunction {
+    id: string;
+    /** 已发布版本号；`null` / 缺省 = 服务草稿（兼容 FunctionRecord 的 nullable 字段）。 */
+    publishedVersion?: number | null;
+}
+/**
+ * 解析函数当前服务源码（发布版本优先，无则草稿）。
+ * - 已发布（publishedVersion 非空）：读不可变发布版本；该版本丢失（已裁剪）则降级草稿。切换是「读时判定」，
+ *   天然原子——发布/回滚对在途请求不产生 5xx（验收「发布不中断」）。
+ * - 未发布：读草稿源码组，无草稿返回 null。
+ * @returns 文件映射；函数没有任何可执行源码时返回 null。
+ */
+export declare function resolveFunctionSource(db: FunctionSourceDb, fn: SourceFunction): Promise<Record<string, string> | null>;
+/**
+ * 把版本行 code 还原成 files 映射（网关转发给 worker）。
+ * 独立于此文件避免引入 functions 域（快照序列化/哈希在 functions/publish/snapshot）。
+ */
+export declare function parseSnapshot(code: string): Record<string, string>;

package/dist/storage/cloud.d.ts

@@ -0,0 +1,11 @@
+import type { CapabilityBundle } from '@adep/types';
+import type { StorageDriver, StoredFileMeta } from './driver';
+import type { DownloadSignerConfig } from './signature';
+import type { StorageUploadData, StoredFile } from '@adep/types';
+/** 把 CloudStorage 的上传数据类型收敛为 driver.put 需要的字节串（导出供 handler 与单测复用）。 */
+export declare function asBytes(data: StorageUploadData): Uint8Array;
+export declare function toStoredFile(meta: StoredFileMeta): StoredFile;
+/**
+ * 按项目产出一组 `cloud.storage` 能力。`projectId` 绑定在装配期，worker 内免传。
+ */
+export declare function createStorageCapability(driver: StorageDriver, signer: DownloadSignerConfig, projectId: string): CapabilityBundle;

package/dist/storage/driver/local.d.ts

@@ -0,0 +1,13 @@
+import type { StorageDriver } from '../driver';
+export interface LocalStorageOptions {
+    /** 数据根目录（config 的 STORAGE_DIR）。 */
+    dir: string;
+    /** 项目配额字节；缺省 1GiB（PRD §2.4）。测试可注入小值验证超限。 */
+    quotaBytes?: number;
+    /**
+     * BILL-005：项目级配额回调（billing 域注入）。传入项目净增字节（覆盖写按净增量计），
+     * 超限时**抛错**（billing 的 BILLING_QUOTA_EXCEEDED）。缺省走静态 `quotaBytes` 判定。
+     */
+    quotaCheck?: (projectId: string, projectedBytes: number) => Promise<void>;
+}
+export declare function createLocalStorageDriver(options: LocalStorageOptions): StorageDriver;

package/dist/storage/driver.d.ts

@@ -0,0 +1,66 @@
+/**
+ * StorageDriver 接口（ST-001 Definition 层）：对象存储的能力缝。
+ *
+ * 「能力缝」意味实现可替换：M1 用本地磁盘（driver/local.ts），S3 驱动后续接入（tech-stack §2.6），
+ * 平台路由与 cloud SDK 只依赖本接口，不感知底层。
+ *
+ * **契约集合（对齐 `@adep/types` 的 `CloudStorage`，并补 M1 平台需要的元数据与配额）**：
+ * - 路径一律是**项目桶内相对路径**（如 `avatars/avatar.png`），禁止绝对路径 / `../` 穿越，
+ *   非法路径抛 `STORAGE_INVALID_PATH`（验收 Scenario 4）；
+ * - 文件级 `visibility`：public 直连、private 签名 URL（15 分钟，验收 Scenario 1/2）；
+ * - 项目配额：超限抛 `STORAGE_QUOTA_EXCEEDED`。
+ * 统一异常形状 `StorageError`（status + code + message），路由层据此回规范 §5 错误信封。
+ */
+/** 项目公桶配额（PRD §2.4：1GB/项目；local 实现按目录递归求 total size 判定）。 */
+export declare const PROJECT_QUOTA_BYTES: number;
+export type FileVisibility = 'public' | 'private';
+/** 存储对象的元数据（下载 / 列表 / 签名用；不含内容体）。 */
+export interface StoredFileMeta {
+    /** 桶内相对路径。 */
+    readonly path: string;
+    readonly size: number;
+    readonly contentType?: string;
+    readonly visibility: FileVisibility;
+    /** ISO 8601。 */
+    readonly updatedAt: string;
+}
+/** 写入选项。 */
+export interface PutOptions {
+    visibility: FileVisibility;
+    contentType?: string;
+}
+/** 读取结果：内容 + 元数据（签名验证 / Content-Type 回复要用 meta）。 */
+export interface GetResult {
+    data: Uint8Array;
+    meta: StoredFileMeta;
+}
+export interface StorageDriver {
+    /** 上传 / 覆盖文件；非法路径抛 `STORAGE_INVALID_PATH`，超配额抛 `STORAGE_QUOTA_EXCEEDED`。 */
+    put(projectId: string, path: string, data: Uint8Array, options: PutOptions): Promise<StoredFileMeta>;
+    /** 读取文件；不存在抛 `STORAGE_NOT_FOUND`。 */
+    get(projectId: string, path: string): Promise<GetResult>;
+    /** 读取元数据（不读内容；签名校验先查 visibility）。 */
+    getMeta(projectId: string, path: string): Promise<StoredFileMeta>;
+    /** 删除文件；不存在抛 `STORAGE_NOT_FOUND`。 */
+    remove(projectId: string, path: string): Promise<void>;
+    /** 按前缀列举（缺省全桶）；排除平台元数据文件。 */
+    list(projectId: string, prefix?: string): Promise<StoredFileMeta[]>;
+    /** 当前项目已用字节数（配额判定的依据）。 */
+    usage(projectId: string): Promise<number>;
+}
+/** ST-001 统一存储异常。 */
+export declare class StorageError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare const STORAGE_CODES: {
+    readonly invalidPath: "STORAGE_INVALID_PATH";
+    readonly notFound: "STORAGE_NOT_FOUND";
+    readonly quotaExceeded: "STORAGE_QUOTA_EXCEEDED";
+};
+/**
+ * 路径穿越防护（验收 Scenario 4）：拒绝绝对路径、`..` 段、空路径、Windows 盘符、控制字符。
+ * 合法路径为单层或多层相对段（如 `a`、`a/b.png`），每段不能是 `.`/`..`、空或含路径分隔符。
+ */
+export declare function assertSafeStoragePath(path: string): string;

package/dist/storage/signature.d.ts

@@ -0,0 +1,23 @@
+export interface DownloadSignerConfig {
+    /** 平台配置的签名密钥（config.ts 复用 AUTH_SECRET 即可；不入库、不输出）。 */
+    secret: string;
+    /** 生成完整外链的基址（config.ts 的 AUTH_URL / PLATFORM_DOMAIN）。 */
+    baseUrl: string;
+}
+/** M1 签名有效期（PRD §2.4 / ST-001 任务单：15 分钟）。 */
+export declare const DEFAULT_SIGN_TTL_SECONDS: number;
+export declare const SIGN_EXPIRES_KEY = "x-expires";
+export declare const SIGN_SIGNATURE_KEY = "x-signature";
+/** 生成私有文件的外链（含签名查询参数）。 */
+export declare function signDownloadUrl(config: DownloadSignerConfig, projectId: string, path: string, ttlSeconds?: number): string;
+export type SignatureVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'missing' | 'malformed' | 'expired' | 'invalid';
+};
+/** 校验签名 URL；`nowSeconds` 可注入（单测模拟过期）。 */
+export declare function verifyDownloadSignature(config: DownloadSignerConfig, projectId: string, path: string, query: {
+    expires?: unknown;
+    signature?: unknown;
+}, nowSeconds?: number): SignatureVerification;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@adep/runtime",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "AgentDeploy 运行时内核：云函数执行器 + 本地模拟运行时 + cloud.db/cloud.storage 能力装配，零平台重栈依赖（无 elysia/drizzle/better-auth/nuxt/bun:sqlite/postgres/ioredis），供 server / CLI(adep dev) / 浏览器离线工作区三方复用。",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "bun run ../../scripts/build-package.ts runtime"
+  },
+  "dependencies": {
+    "@adep/types": "workspace:*"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./*": {
+        "types": "./dist/*.d.ts",
+        "default": "./dist/*.js"
+      }
+    }
+  }
+}