@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/runtime/guest/failure.ts

@@ -0,0 +1,69 @@
+/** 把连接器抛出的值归成失败回报。错误类别只按 `code` 字段判断（连接器可能抛任意值）。 */
+import type { GuestFailureCode, GuestLog } from '../protocol';
+import { isAborted } from './bridge';
+import { CONNECTOR_FILENAME } from './limits';
+
+export interface ErrorInfo {
+  code: string | null;
+  message: string;
+  stack: string | undefined;
+}
+
+/** 只取 code / message / stack 三个原始值；读属性抛错或类型不对时按普通异常处理。 */
+export function errorInfo(error: unknown): ErrorInfo {
+  let code: string | null = null;
+  let message = 'connector threw a non-error value';
+  let stack: string | undefined;
+  if (error !== null && (typeof error === 'object' || typeof error === 'function')) {
+    const value = error as { code?: unknown; message?: unknown; stack?: unknown };
+    try { if (typeof value.code === 'string') code = value.code; } catch { code = null; }
+    try { if (typeof value.message === 'string') message = value.message; } catch { /* 保留缺省文案 */ }
+    try { if (typeof value.stack === 'string') stack = value.stack; } catch { stack = undefined; }
+  } else if (typeof error === 'string') {
+    message = error;
+  }
+  return { code, message, stack };
+}
+
+/**
+ * 调用栈只留第一行（错误文案）与连接器代码自己的帧：宿主帧带 runner 的本地路径，guest 运行时的帧对作者没有意义。
+ * 连接器代码以 `connector.js` 为文件名加载、包装函数与第一行同行，行号直接对应打包产物。
+ */
+export function connectorStack(stack: string | undefined): string | undefined {
+  if (stack === undefined) return undefined;
+  const lines = stack.split('\n');
+  const frames = lines.slice(1).filter((line) => line.includes(`${CONNECTOR_FILENAME}:`));
+  if (frames.length === 0) return undefined;
+  return [lines[0] ?? '', ...frames].join('\n');
+}
+
+const CODE_MAP: Readonly<Record<string, GuestFailureCode>> = Object.freeze({
+  AUTH_ERROR: 'AUTH_ERROR',
+  TRANSIENT_ERROR: 'TRANSIENT_ERROR',
+  RATE_LIMITED: 'TRANSIENT_ERROR',
+  SCHEMA_ERROR: 'SCHEMA_ERROR',
+  FATAL_ERROR: 'FATAL_ERROR',
+  CANCELED: 'CANCELED',
+});
+
+export interface FailureMessage {
+  type: 'failure';
+  code: GuestFailureCode;
+  message: string;
+  stack?: string;
+  logs: GuestLog[];
+}
+
+export function failure(code: GuestFailureCode, message: string, logs: GuestLog[], stack?: string): FailureMessage {
+  return { type: 'failure', code, message, ...(stack !== undefined ? { stack } : {}), logs };
+}
+
+/** 连接器异常 → 失败回报：认得的 code 原样映射，其余（含宿主调用的错误码）按 FATAL_ERROR，文案带上原 code；运行已取消时一律 CANCELED。 */
+export function failureFromError(error: unknown, logs: GuestLog[]): FailureMessage {
+  const info = errorInfo(error);
+  const stack = connectorStack(info.stack);
+  if (isAborted()) return failure('CANCELED', 'run was canceled', logs, stack);
+  const mapped = info.code !== null && Object.hasOwn(CODE_MAP, info.code) ? CODE_MAP[info.code] : undefined;
+  if (mapped) return failure(mapped, info.message, logs, stack);
+  return failure('FATAL_ERROR', info.code === null ? info.message : `${info.code}: ${info.message}`, logs, stack);
+}

package/src/runtime/guest/http.ts

@@ -0,0 +1,194 @@
+/**
+ * `ctx.http`：经宿主调用 `http` 出站，网关只做一次尝试，重试在这里做：
+ * - 网关限流 `EGRESS_RATE_LIMITED`（带 `retryAfterMs`）与上游 429（按 `Retry-After`）：等待后重发，最多 5 次，仍不行抛 `RateLimited`；
+ * - 上游 502 / 503 / 504 与网关超时 `EGRESS_TIMEOUT`：指数退避（200 ms 起，×2）重试 3 次，仍不行抛 `TransientError`。
+ *   请求可能已被上游处理，所以缺省只对幂等方法（RFC 9110 §9.2.2：GET / HEAD / PUT / DELETE）重试，
+ *   POST / PATCH 直接抛 `TransientError`，除非请求传了 `retry: true`；`retry: false` 时一律不重试；
+ * - 上游 401 抛 `AuthError`，其他 4xx / 5xx 抛 `FatalError`；`raw: true` 时不按状态码处理。
+ */
+import { errors } from '../../errors';
+import type { HttpClient, HttpMethod, HttpOptions, HttpResponse } from '../../types';
+import type { EgressHttpRequest, EgressHttpResponse } from '../protocol';
+import { HostCallFailure, call, jsonParse, jsonStringify, now, sleep, throwIfAborted } from './bridge';
+import { bytesToBase64 } from './crypto';
+import { MAX_RETRY_WAIT_MS, RATE_LIMIT_BACKOFF_MS, RATE_LIMIT_RETRIES, TRANSIENT_BACKOFF_MS, TRANSIENT_RETRIES } from './limits';
+
+const METHODS: readonly string[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'];
+const ABSOLUTE_URL = /^https?:\/\//i;
+const TRANSIENT_STATUS: readonly number[] = [502, 503, 504];
+/** RFC 9110 §9.2.2 的幂等方法（`METHODS` 里没有 OPTIONS / TRACE）。 */
+const IDEMPOTENT_METHODS: readonly string[] = ['GET', 'HEAD', 'PUT', 'DELETE'];
+const JSON_CONTENT_TYPE = /(?:^|[/+])json\s*(?:;|$)/i;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'object' && value !== null) return jsonStringify(value) as string;
+  return String(value);
+}
+
+/** 相对路径拼在 `auth.baseUrl` 上；没有时拼在缺省基址（连接器 `hosts` 里第一个确定的主机）上。 */
+export function resolveUrl(url: string, baseUrl: string | null): string {
+  if (ABSOLUTE_URL.test(url)) return url;
+  if (!baseUrl) throw new TypeError(`relative URL ${url} needs auth.baseUrl or a fixed host in the connector's hosts`);
+  const base = baseUrl.replace(/\/+$/, '');
+  return `${base}${url.startsWith('/') ? '' : '/'}${url}`;
+}
+
+function buildHeaders(options: HttpOptions): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const source of [options.auth?.headers, options.headers]) {
+    if (source === undefined) continue;
+    if (!isRecord(source)) throw new TypeError('headers must be an object');
+    for (const [name, value] of Object.entries(source)) {
+      if (value === undefined || value === null) continue;
+      headers[name.toLowerCase()] = stringify(value);
+    }
+  }
+  return headers;
+}
+
+function buildQuery(query: HttpOptions['query']): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  if (query === undefined) return out;
+  if (!isRecord(query)) throw new TypeError('query must be an object');
+  for (const [name, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    out[name] = Array.isArray(value) ? value.filter((item) => item !== undefined && item !== null).map(stringify) : stringify(value);
+  }
+  return out;
+}
+
+function buildBody(body: unknown, headers: Record<string, string>): Pick<EgressHttpRequest, 'body' | 'bodyEncoding'> {
+  if (body === undefined || body === null) return { body: null, bodyEncoding: 'utf8' };
+  if (typeof body === 'string') return { body, bodyEncoding: 'utf8' };
+  if (body instanceof Uint8Array) return { body: bytesToBase64(Array.from(body)), bodyEncoding: 'base64' };
+  if (body instanceof ArrayBuffer) return { body: bytesToBase64(Array.from(new Uint8Array(body))), bodyEncoding: 'base64' };
+  const text = jsonStringify(body);
+  if (typeof text !== 'string') throw new TypeError('request body is not serializable');
+  if (headers['content-type'] === undefined) headers['content-type'] = 'application/json';
+  return { body: text, bodyEncoding: 'utf8' };
+}
+
+function buildRequest(method: string, url: string, options: HttpOptions, defaultBaseUrl: string | null): EgressHttpRequest {
+  const upper = typeof method === 'string' ? method.toUpperCase() : '';
+  if (!METHODS.includes(upper)) throw new TypeError(`unsupported HTTP method ${String(method)}`);
+  if (typeof url !== 'string' || url.length === 0) throw new TypeError('url must be a non-empty string');
+  if (!isRecord(options as unknown)) throw new TypeError('options must be an object');
+  const baseUrl = options.auth?.baseUrl ?? defaultBaseUrl;
+  const headers = buildHeaders(options);
+  const request: EgressHttpRequest = {
+    method: upper as EgressHttpRequest['method'],
+    url: resolveUrl(url, typeof baseUrl === 'string' ? baseUrl : null),
+    headers,
+    query: buildQuery(options.query),
+    ...buildBody(options.body, headers),
+  };
+  if (options.retry !== undefined && typeof options.retry !== 'boolean') throw new TypeError('retry must be a boolean');
+  if (options.timeoutMs !== undefined) {
+    if (typeof options.timeoutMs !== 'number' || !(options.timeoutMs > 0)) throw new TypeError('timeoutMs must be a positive number');
+    request.timeoutMs = options.timeoutMs;
+  }
+  return request;
+}
+
+function toResponse(value: unknown, parseJson: boolean): HttpResponse {
+  if (!isRecord(value) || typeof value.status !== 'number' || typeof value.body !== 'string') throw new TypeError('http host call returned a malformed response');
+  const raw = value as unknown as EgressHttpResponse;
+  const headers: Record<string, string> = {};
+  if (isRecord(raw.headers)) {
+    for (const [name, item] of Object.entries(raw.headers)) if (typeof item === 'string') headers[name.toLowerCase()] = item;
+  }
+  // 二进制响应的 text 是 base64 原文；只有 utf8 文本才按 JSON 解析。
+  const text = raw.body;
+  const url = typeof raw.url === 'string' ? raw.url : '';
+  let data: unknown = text;
+  if (parseJson && raw.bodyEncoding !== 'base64' && JSON_CONTENT_TYPE.test(headers['content-type'] ?? '') && text.length > 0) {
+    try {
+      data = jsonParse(text);
+    } catch {
+      throw new errors.FatalError(`response from ${url} is not valid JSON`);
+    }
+  }
+  return { status: raw.status, url, headers, data, text };
+}
+
+/** `Retry-After`：秒数或 HTTP 日期；取不到返回 undefined。 */
+function retryAfterMs(headers: Record<string, string>): number | undefined {
+  const value = headers['retry-after'];
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed) * 1000;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now());
+}
+
+function clampWait(ms: number): number {
+  return Math.min(Math.max(0, ms), MAX_RETRY_WAIT_MS);
+}
+
+export function createHttp(defaultBaseUrl: string | null): HttpClient {
+  async function request<T = unknown>(method: HttpMethod, url: string, options: HttpOptions = {}): Promise<HttpResponse<T>> {
+    const req = buildRequest(method, url, options, defaultBaseUrl);
+    const raw = options.raw === true;
+    const label = `${req.method} ${req.url}`;
+    const retryTransient = options.retry ?? IDEMPOTENT_METHODS.includes(req.method);
+    const transientLimit = retryTransient ? TRANSIENT_RETRIES : 0;
+    let rateRetries = 0;
+    let transientRetries = 0;
+    for (;;) {
+      throwIfAborted();
+      let value: unknown;
+      try {
+        value = await call('http', req);
+      } catch (error) {
+        if (error instanceof HostCallFailure && error.code === 'EGRESS_RATE_LIMITED') {
+          const wait = error.retryAfterMs ?? RATE_LIMIT_BACKOFF_MS * 2 ** rateRetries;
+          if (rateRetries >= RATE_LIMIT_RETRIES) throw new errors.RateLimited(wait, `${label} is still rate limited after ${RATE_LIMIT_RETRIES} retries`);
+          rateRetries += 1;
+          await sleep(clampWait(wait));
+          continue;
+        }
+        if (error instanceof HostCallFailure && error.code === 'EGRESS_TIMEOUT') {
+          if (transientRetries >= transientLimit) throw new errors.TransientError(`${label} timed out after ${transientRetries} retries`);
+          await sleep(TRANSIENT_BACKOFF_MS * 2 ** transientRetries);
+          transientRetries += 1;
+          continue;
+        }
+        throw error;
+      }
+      const response = toResponse(value, !raw);
+      if (raw) return response as HttpResponse<T>;
+      const status = response.status;
+      if (status === 429) {
+        const wait = retryAfterMs(response.headers) ?? RATE_LIMIT_BACKOFF_MS * 2 ** rateRetries;
+        if (rateRetries >= RATE_LIMIT_RETRIES) throw new errors.RateLimited(wait, `${label} returned 429 after ${RATE_LIMIT_RETRIES} retries`);
+        rateRetries += 1;
+        await sleep(clampWait(wait));
+        continue;
+      }
+      if (TRANSIENT_STATUS.includes(status)) {
+        if (transientRetries >= transientLimit) throw new errors.TransientError(`${label} returned ${status} after ${transientRetries} retries`);
+        await sleep(TRANSIENT_BACKOFF_MS * 2 ** transientRetries);
+        transientRetries += 1;
+        continue;
+      }
+      if (status === 401) throw new errors.AuthError(`${label} returned 401`);
+      if (status >= 400) throw new errors.FatalError(`${label} returned ${status}`);
+      return response as HttpResponse<T>;
+    }
+  }
+  const verb = (method: HttpMethod) => <T = unknown>(url: string, options?: HttpOptions) => request<T>(method, url, options);
+  return Object.freeze({
+    get: verb('GET'),
+    post: verb('POST'),
+    put: verb('PUT'),
+    patch: verb('PATCH'),
+    delete: verb('DELETE'),
+    request,
+  });
+}

package/src/runtime/guest/index.ts

@@ -0,0 +1,102 @@
+/**
+ * guest 运行时入口（在 vm 上下文**里**执行）。runner 用 `bundleTrustedEntry(GUEST_ENTRY_PATH)` 把本文件打成 CJS 字符串，
+ * 宿主会话在新上下文里先执行它、调用 `bootGuest()`，之后才编译并加载连接器代码。
+ *
+ * 交给宿主的只有 `start(json, factory)`、`handle(json)`、`poll()` 三个上下文自己的函数，参数是字符串
+ * 与上下文里编译出的连接器工厂函数；SDK 的公开 API（`defineStream` / `errors` …）由 guest 自己提供给连接器的
+ * `require`，不从宿主传对象。
+ *
+ * 作业开始前先加载产物、核对描述与实现（见 `loader.ts`）；不一致时任何作业都以 `CONNECTOR_LOAD_FAILED` 失败。
+ */
+import { validateConfig } from '../../validate';
+import type { GuestJob } from '../protocol';
+import { finish, handle, jsonParse, poll } from './bridge';
+import { runCheck } from './check';
+import { prepareSecrets } from './ctx';
+import { connectorStack, errorInfo, failure, failureFromError, type FailureMessage } from './failure';
+import { loadConnector, type LoadedConnector } from './loader';
+import { createLogBuffer } from './log';
+import { runOperation } from './operation';
+import { runPull } from './pull';
+import { runPush } from './push';
+import { runSuggest } from './suggest';
+
+export interface GuestApi {
+  /** 只生效一次：`json` 为 `{ expect, job }`，`factory` 为上下文里编译出的 `(function (module, exports, require) {…})`。 */
+  start(json: string, factory: unknown): void;
+  handle(json: string): void;
+  poll(): string;
+}
+
+type Outcome = { type: 'result'; result: unknown } | FailureMessage;
+
+/**
+ * Bun 1.3 实测，新上下文里这三项要在连接器代码运行前拿掉：
+ * - WebAssembly：Bun 的 node:vm 不执行 `codeGeneration.wasm = false`，`new WebAssembly.Module` 仍可编译；
+ * - ShadowRealm：`evaluate(字符串)` 绕过 `codeGeneration.strings`，且会让 Bun 段错误；
+ * - console：直接写子进程 stdout，连接器只能经 `ctx.log` 记日志。
+ */
+const STRIPPED_GLOBALS = ['WebAssembly', 'ShadowRealm', 'console'];
+
+function issuesText(issues: ReadonlyArray<{ path: string; message: string }>): string {
+  return issues.map((issue) => `${issue.path || '(root)'}: ${issue.message}`).join('; ');
+}
+
+async function run(connector: LoadedConnector, job: GuestJob): Promise<Outcome> {
+  if (job.kind === 'push') return runPush(connector, job);
+  if (job.kind === 'operation') return runOperation(connector, job);
+  if (job.kind === 'pull' && !Object.hasOwn(connector.streams, job.stream)) {
+    return failure('CONNECTOR_LOAD_FAILED', `connector has no stream named ${job.stream}`, []);
+  }
+  const logs = createLogBuffer();
+  const issues = validateConfig(connector.descriptor.config, job.config);
+  if (issues.length > 0) return failure('CONFIG_INVALID', `invalid connection config: ${issuesText(issues)}`, logs.drain());
+  let secrets: Readonly<Record<string, string>>;
+  try {
+    secrets = await prepareSecrets(connector.descriptor, job.secretFields);
+  } catch (error) {
+    return failureFromError(error, logs.drain());
+  }
+  const options = { config: job.config, secrets, descriptor: connector.descriptor, logs, rateLimit: job.rateLimit };
+  if (job.kind === 'check') return runCheck(connector, options);
+  if (job.kind === 'suggest') return runSuggest(connector, job, options);
+  return runPull(connector, job, options);
+}
+
+async function execute(json: string, factory: unknown): Promise<Outcome> {
+  const { expect, job } = jsonParse(json) as { expect: { name: string; version: string }; job: GuestJob };
+  const loaded = loadConnector(factory, expect);
+  if (!loaded.ok) return failure(loaded.code, loaded.message, [], connectorStack(loaded.stack));
+  return run(loaded.connector, job);
+}
+
+let started = false;
+
+function start(json: string, factory: unknown): void {
+  if (started || typeof json !== 'string') return;
+  started = true;
+  let pending: Promise<Outcome>;
+  try {
+    pending = execute(json, factory);
+  } catch (error) {
+    finish(failure('FATAL_ERROR', errorInfo(error).message, []) as unknown as Record<string, unknown>);
+    return;
+  }
+  pending.then(
+    (outcome) => finish(outcome as unknown as Record<string, unknown>),
+    (error: unknown) => finish(failure('FATAL_ERROR', `connector runtime failed: ${errorInfo(error).message}`, []) as unknown as Record<string, unknown>),
+  );
+}
+
+export function bootGuest(): GuestApi {
+  for (const name of STRIPPED_GLOBALS) Reflect.deleteProperty(globalThis, name);
+  return Object.freeze({ start, handle, poll });
+}
+
+/**
+ * 进程内执行（`./testing` 的 `createInProcessExecutor`，给 vitest 用）：每次执行都重新求值一份 guest 运行时，
+ * 这里的全局对象是宿主进程自己的，所以不拿掉任何全局；其余与 `bootGuest` 相同。
+ */
+export function bootLocalGuest(): GuestApi {
+  return Object.freeze({ start, handle, poll });
+}

package/{runtime/guest/limits.d.ts → src/runtime/guest/limits.ts}

@@ -1,20 +1,20 @@
 /** guest 侧限额；与 shared 的 connector-limits 同值（SDK 不依赖 shared）。 */
-export declare const PULL_BATCH_MAX_RECORDS = 1000;
-export declare const PULL_BATCH_MAX_BYTES: number;
+export const PULL_BATCH_MAX_RECORDS = 1000;
+export const PULL_BATCH_MAX_BYTES = 4 * 1024 * 1024;
 /** 一次拉取运行里被拒收的记录超过这个数时运行失败（与 shared 的 `PULL_REJECT_THRESHOLD` 同值）。 */
-export declare const PULL_REJECT_THRESHOLD = 1000;
-export declare const MAX_LOGS = 1000;
-export declare const MAX_LOG_MESSAGE = 4096;
+export const PULL_REJECT_THRESHOLD = 1000;
+export const MAX_LOGS = 1000;
+export const MAX_LOG_MESSAGE = 4096;
 /** 连接器与连接都没声明限流时网关用的并发（`EGRESS_DEFAULT_RATE.concurrency`）。 */
-export declare const DEFAULT_CONCURRENCY = 4;
+export const DEFAULT_CONCURRENCY = 4;
 /** 429 / 网关限流的最多重试次数。 */
-export declare const RATE_LIMIT_RETRIES = 5;
+export const RATE_LIMIT_RETRIES = 5;
 /** 上游 502 / 503 / 504 与网关超时的最多重试次数，退避从 200 ms 起、每次翻倍。 */
-export declare const TRANSIENT_RETRIES = 3;
-export declare const TRANSIENT_BACKOFF_MS = 200;
+export const TRANSIENT_RETRIES = 3;
+export const TRANSIENT_BACKOFF_MS = 200;
 /** 429 没给 `Retry-After` 时的等待起点（每次翻倍）。 */
-export declare const RATE_LIMIT_BACKOFF_MS = 1000;
+export const RATE_LIMIT_BACKOFF_MS = 1000;
 /** 单次等待上限，避免来源给出离谱的 `Retry-After`。 */
-export declare const MAX_RETRY_WAIT_MS = 600000;
+export const MAX_RETRY_WAIT_MS = 600_000;
 /** 连接器代码在 vm 里的文件名；失败回报的调用栈只保留这个文件的帧。 */
-export declare const CONNECTOR_FILENAME = "connector.js";
+export const CONNECTOR_FILENAME = 'connector.js';

package/src/runtime/guest/loader.ts

@@ -0,0 +1,210 @@
+/**
+ * 加载连接器打包产物。宿主把产物编译成 `(function (module, exports, require) {…})` 交进来（编译在上下文里完成，
+ * 函数属于上下文）；这里给它一个只认 `@deepexi/datasense-connector` 的 `require`，返回 guest 自己的那份 SDK。
+ *
+ * 产物按虚拟入口契约导出 `{ descriptor, implementations }`：`descriptor` 是平台校验过的连接器描述（JSON），
+ * `implementations` 是各能力目录的默认导出。加载时核对：
+ * - 描述的名字与版本等于宿主期望的；
+ * - 实现与描述一一对应（数据流、推送、操作、建议列、`check`），缺失与多余的一并列出；
+ * - 每个实现是对应的 `define*()` 结果，且名字与所在目录一致；
+ * - `idempotency: unsupported` 的操作实现了 `lookup`（否则 `CONNECTOR_LOOKUP_REQUIRED`）。
+ */
+import type { ConnectorDescriptor } from '../../descriptor';
+import type { SuggestColumnsFunction } from '../../define';
+import { ConnectorError } from '../../errors';
+import * as sdk from '../../index';
+import type { CheckContext, OperationHandlers, PushHandler, StreamFunction } from '../../types';
+import type { GuestFailureCode } from '../protocol';
+import { errorInfo } from './failure';
+
+export const SDK_SPECIFIER = '@deepexi/datasense-connector';
+
+const sdkModule = Object.freeze({ ...sdk, __esModule: true });
+
+function connectorRequire(specifier: unknown): unknown {
+  if (specifier === SDK_SPECIFIER) return sdkModule;
+  throw new ConnectorError('CONNECTOR_LOAD_FAILED', `cannot require ${String(specifier)}: connectors can only import ${SDK_SPECIFIER} and relative files`);
+}
+
+/** 加载并核对过的连接器：描述加各能力的实现函数。 */
+export interface LoadedConnector {
+  descriptor: ConnectorDescriptor;
+  check: ((ctx: CheckContext) => void | Promise<void>) | null;
+  streams: Record<string, StreamFunction>;
+  suggestColumns: Record<string, SuggestColumnsFunction>;
+  pushes: Record<string, PushHandler>;
+  operations: Record<string, OperationHandlers>;
+}
+
+export type LoadOutcome =
+  | { ok: true; connector: LoadedConnector }
+  | { ok: false; code: Extract<GuestFailureCode, 'CONNECTOR_LOAD_FAILED' | 'CONNECTOR_LOOKUP_REQUIRED'>; message: string; stack: string | undefined };
+
+type Factory = (module: { exports: unknown }, exports: unknown, require: (specifier: string) => unknown) => void;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+/** 描述的结构检查（平台打包前已完整校验过，这里只防结构不对时 guest 崩溃）；返回问题列表。 */
+function descriptorProblems(value: unknown): string[] {
+  if (!isRecord(value)) return ['descriptor must be an object'];
+  const problems: string[] = [];
+  if (typeof value.name !== 'string' || typeof value.version !== 'string') problems.push('descriptor needs a name and a version');
+  if (!isRecord(value.config)) problems.push('descriptor.config must be an object');
+  if (!isStringArray(value.hosts)) problems.push('descriptor.hosts must be a list of host names');
+  if (value.rateLimit !== null && !(isRecord(value.rateLimit) && typeof value.rateLimit.concurrency === 'number')) problems.push('descriptor.rateLimit must be null or { perSecond, concurrency }');
+  if (typeof value.check !== 'boolean') problems.push('descriptor.check must be a boolean');
+  for (const key of ['streams', 'pushes', 'operations'] as const) {
+    const group = value[key];
+    if (!isRecord(group)) {
+      problems.push(`descriptor.${key} must be an object`);
+      continue;
+    }
+    for (const [name, item] of Object.entries(group)) {
+      if (!isRecord(item)) problems.push(`descriptor.${key}.${name} must be an object`);
+      else if (key !== 'operations' && !isRecord(item.tables)) problems.push(`descriptor.${key}.${name}.tables must be an object`);
+      else if (key === 'operations' && (!isRecord(item.input) || !isRecord(item.output))) problems.push(`descriptor.operations.${name} needs input and output`);
+    }
+  }
+  return problems;
+}
+
+/** 模块命名空间（`{ default }`）取默认导出；已经是实现对象时原样返回。 */
+function implementationOf(value: unknown): unknown {
+  if (isRecord(value) && value.__ontos === undefined && Object.hasOwn(value, 'default')) return value.default;
+  return value;
+}
+
+function brandOf(value: unknown, kind: string, name: string | null): Record<string, unknown> | null {
+  if (!isRecord(value) || value.__ontos !== kind) return null;
+  if (name !== null && value.name !== name) return null;
+  return value;
+}
+
+/** 按描述核对实现，返回规整后的连接器或问题。 */
+function matchImplementations(descriptor: ConnectorDescriptor, value: unknown): { connector: LoadedConnector | null; mismatch: string[]; invalid: string[]; lookupMissing: string[] } {
+  const implementations = isRecord(value) ? value : {};
+  const missing: string[] = [];
+  const extra: string[] = [];
+  const invalid: string[] = [];
+  const lookupMissing: string[] = [];
+  const connector: LoadedConnector = { descriptor, check: null, streams: {}, suggestColumns: {}, pushes: {}, operations: {} };
+
+  const group = (key: string): Record<string, unknown> => {
+    const items = implementations[key];
+    return isRecord(items) ? items : {};
+  };
+  /** 一组实现与描述里的名字逐一对照；`label` 是报告里的前缀，`suffix` 是同一目录下的第二种实现（如 suggest-columns）。 */
+  const compare = (key: string, expected: readonly string[], label: string, kind: string, file: string, fn: string, accept: (name: string, impl: Record<string, unknown>) => void): void => {
+    const items = group(key);
+    for (const name of expected) {
+      if (!Object.hasOwn(items, name)) {
+        missing.push(`${label}/${name}${file === 'index.ts' ? '' : `/${file.replace(/\.ts$/, '')}`}`);
+        continue;
+      }
+      const impl = brandOf(implementationOf(items[name]), kind, name);
+      if (!impl) {
+        invalid.push(`${label}/${name}/${file} must export default ${fn}('${name}', …)`);
+        continue;
+      }
+      accept(name, impl);
+    }
+    for (const name of Object.keys(items)) {
+      if (!expected.includes(name)) extra.push(`${label}/${name}${file === 'index.ts' ? '' : `/${file.replace(/\.ts$/, '')}`}`);
+    }
+  };
+
+  compare('streams', Object.keys(descriptor.streams), 'streams', 'stream', 'index.ts', 'defineStream', (name, impl) => {
+    if (typeof impl.run === 'function') connector.streams[name] = impl.run as StreamFunction;
+    else invalid.push(`streams/${name}/index.ts must export default defineStream('${name}', …)`);
+  });
+  const suggestStreams = Object.entries(descriptor.streams).filter(([, stream]) => stream.suggestColumns === true).map(([name]) => name);
+  compare('suggestColumns', suggestStreams, 'streams', 'suggest', 'suggest-columns.ts', 'defineSuggestColumns', (name, impl) => {
+    if (typeof impl.run === 'function') connector.suggestColumns[name] = impl.run as SuggestColumnsFunction;
+    else invalid.push(`streams/${name}/suggest-columns.ts must export default defineSuggestColumns('${name}', …)`);
+  });
+  compare('pushes', Object.keys(descriptor.pushes), 'pushes', 'push', 'index.ts', 'definePush', (name, impl) => {
+    const handler = impl.handler;
+    if (isRecord(handler) && typeof handler.map === 'function') connector.pushes[name] = handler as unknown as PushHandler;
+    else invalid.push(`pushes/${name}/index.ts must export default definePush('${name}', { map })`);
+  });
+  compare('operations', Object.keys(descriptor.operations), 'operations', 'operation', 'index.ts', 'defineOperation', (name, impl) => {
+    const handlers = impl.handlers;
+    if (!isRecord(handlers) || typeof handlers.run !== 'function') {
+      invalid.push(`operations/${name}/index.ts must export default defineOperation('${name}', { run })`);
+      return;
+    }
+    connector.operations[name] = handlers as unknown as OperationHandlers;
+    if (descriptor.operations[name]?.idempotency === 'unsupported' && typeof handlers.lookup !== 'function') lookupMissing.push(name);
+  });
+
+  const check = implementationOf(implementations.check);
+  if (descriptor.check) {
+    if (check === undefined || check === null) missing.push('check');
+    else {
+      const impl = brandOf(check, 'check', null);
+      if (impl && typeof impl.run === 'function') connector.check = impl.run as LoadedConnector['check'];
+      else invalid.push('check.ts must export default defineCheck(…)');
+    }
+  } else if (check !== undefined && check !== null) {
+    extra.push('check');
+  }
+
+  const mismatch = [...missing.map((item) => `missing ${item}`), ...extra.map((item) => `extra ${item}`)];
+  return { connector: mismatch.length === 0 && invalid.length === 0 && lookupMissing.length === 0 ? connector : null, mismatch, invalid, lookupMissing };
+}
+
+/** 执行连接器代码、取 `{ descriptor, implementations }`，核对期望的名字与版本、实现与描述是否一致。 */
+export function loadConnector(factory: unknown, expect: { name: string; version: string }): LoadOutcome {
+  if (typeof factory !== 'function') return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: 'connector code did not compile to a module', stack: undefined };
+  let exported: unknown;
+  try {
+    const module = { exports: {} as unknown };
+    Reflect.apply(factory as Factory, undefined, [module, module.exports, connectorRequire]);
+    exported = module.exports;
+  } catch (error) {
+    const info = errorInfo(error);
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector code failed to load: ${info.message}`, stack: info.stack };
+  }
+  if (!isRecord(exported) && typeof exported !== 'function') {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: 'connector bundle must export { descriptor, implementations }', stack: undefined };
+  }
+  let descriptor: unknown;
+  let implementations: unknown;
+  try {
+    descriptor = (exported as { descriptor?: unknown }).descriptor;
+    implementations = (exported as { implementations?: unknown }).implementations;
+  } catch (error) {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector code failed to load: ${errorInfo(error).message}`, stack: undefined };
+  }
+  const problems = descriptorProblems(descriptor);
+  if (problems.length > 0) return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `invalid connector descriptor: ${problems.join('; ')}`, stack: undefined };
+  const loaded = descriptor as ConnectorDescriptor;
+  if (loaded.name !== expect.name || loaded.version !== expect.version) {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector bundle is ${loaded.name}@${loaded.version}, expected ${expect.name}@${expect.version}`, stack: undefined };
+  }
+  if (!isRecord(implementations)) {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: 'connector bundle must export implementations', stack: undefined };
+  }
+  const matched = matchImplementations(loaded, implementations);
+  if (matched.mismatch.length > 0 || matched.invalid.length > 0) {
+    const parts = [];
+    if (matched.mismatch.length > 0) parts.push(`implementations do not match the connector descriptor: ${matched.mismatch.join('; ')}`);
+    if (matched.invalid.length > 0) parts.push(matched.invalid.join('; '));
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: parts.join('; '), stack: undefined };
+  }
+  if (matched.lookupMissing.length > 0) {
+    return {
+      ok: false,
+      code: 'CONNECTOR_LOOKUP_REQUIRED',
+      message: `operations with idempotency 'unsupported' must implement lookup(ctx, { idempotencyKey, params }) so the platform can confirm uncertain results: ${matched.lookupMissing.join(', ')}`,
+      stack: undefined,
+    };
+  }
+  return { ok: true, connector: matched.connector as LoadedConnector };
+}

package/src/runtime/guest/log.ts

@@ -0,0 +1,47 @@
+/** `ctx.log`：一次运行最多保留 1000 条，单条超过 4096 字符截断；拉取作业每批 `emit` 带走已有的日志。 */
+import type { ConnectorLog } from '../../types';
+import type { GuestLog } from '../protocol';
+import { jsonStringify } from './bridge';
+import { MAX_LOG_MESSAGE, MAX_LOGS } from './limits';
+import { isoNow } from './time';
+
+export interface LogBuffer {
+  /** 取走尚未上报的日志。 */
+  drain(): GuestLog[];
+  /** `isOpen` 返回 false 时丢弃（推送请求结束后再写日志无效）。 */
+  logger(requestId?: string, isOpen?: () => boolean): ConnectorLog;
+}
+
+function render(message: unknown, data: unknown): string {
+  let text = typeof message === 'string' ? message : 'non-string log message';
+  if (data !== undefined) {
+    try {
+      const extra = jsonStringify(data);
+      if (typeof extra === 'string') text = `${text} ${extra}`;
+    } catch {
+      // 附加数据不可序列化时只记文案
+    }
+  }
+  return text.length > MAX_LOG_MESSAGE ? text.slice(0, MAX_LOG_MESSAGE) : text;
+}
+
+export function createLogBuffer(): LogBuffer {
+  let entries: GuestLog[] = [];
+  let total = 0;
+  const write = (level: GuestLog['level'], requestId: string | undefined, isOpen: (() => boolean) | undefined) =>
+    (message: string, data?: Record<string, unknown>): void => {
+      if (total >= MAX_LOGS || (isOpen && !isOpen())) return;
+      total += 1;
+      entries[entries.length] = { at: isoNow(), level, message: render(message, data), ...(requestId !== undefined ? { requestId } : {}) };
+    };
+  return {
+    drain() {
+      const out = entries;
+      entries = [];
+      return out;
+    },
+    logger(requestId, isOpen) {
+      return Object.freeze({ info: write('info', requestId, isOpen), warn: write('warn', requestId, isOpen), error: write('error', requestId, isOpen) });
+    },
+  };
+}