@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/runtime/guest/bridge.ts

@@ -0,0 +1,238 @@
+/**
+ * guest 与宿主之间的唯一通道（在 vm 上下文**里**执行）。
+ *
+ * 宿主只调用 guest 交出的三个函数，参数与返回值只有字符串和上下文自己的值：
+ * - `handle(json)`：父进程的 `reply` / `cancel`；
+ * - `poll()`：取走待发的消息（`call` / `result` / `failure`），同时触发到期的定时器，返回 JSON 字符串；
+ * - `start(json, factory)`：见 `index.ts`。
+ * 宿主不往上下文里放任何函数或对象（宿主值的 `constructor` 链能拿到宿主的 `Function`），也不 `await`
+ * 上下文里的 Promise。上下文里没有 `setTimeout`，`sleep` 由宿主按 `poll()` 回报的 `wake` 定时再调 `poll()` 实现。
+ *
+ * 用到的内置函数在本模块求值时取引用：guest 打包产物先于连接器代码执行，连接器之后改写全局不影响这里。
+ */
+import { ConnectorError } from '../../errors';
+import type { HostMethod } from '../protocol';
+
+const jsonParse = JSON.parse;
+const jsonStringify = JSON.stringify;
+const dateNow = Date.now;
+const reflectApply = Reflect.apply;
+const mathMin = Math.min;
+const MapCtor = Map;
+
+export { jsonParse, jsonStringify };
+
+/** 宿主调用失败：`code` 来自宿主（如 `EGRESS_RATE_LIMITED`），连接器按 `code` 判断。 */
+export class HostCallFailure extends ConnectorError {
+  readonly status: number | undefined;
+  readonly retryAfterMs: number | undefined;
+
+  constructor(code: string, message: string, status?: number, retryAfterMs?: number) {
+    super(code, message);
+    this.name = 'HostCallFailure';
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** 运行被取消。 */
+export class CanceledError extends ConnectorError {
+  constructor() {
+    super('CANCELED', 'run was canceled');
+    this.name = 'CanceledError';
+  }
+}
+
+interface PendingCall {
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+}
+
+interface Timer {
+  at: number;
+  resolve(): void;
+}
+
+let nextCallId = 1;
+const pending = new MapCtor<number, PendingCall>();
+let timers: Timer[] = [];
+let outbox: string[] = [];
+let finished = false;
+let aborted = false;
+/** 宿主经 `emit` 回复要求提前结束（预览达到条数上限）：与取消一样触发 `ctx.signal`，但作业正常结束。 */
+let stopped = false;
+const abortListeners: Array<() => void> = [];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 当前时间（毫秒）。 */
+export function now(): number {
+  return reflectApply(dateNow, Date, []) as number;
+}
+
+/** 把消息排进待发队列；不可序列化时同步抛错，由调用方按连接器异常处理。 */
+function enqueue(message: Record<string, unknown>): void {
+  const text = jsonStringify(message);
+  if (typeof text !== 'string') throw new TypeError('message is not serializable');
+  outbox[outbox.length] = text;
+}
+
+/** 置位后任何宿主调用都直接失败（连接器操作的 `simulate` 是纯函数，期间不允许调用宿主）。 */
+let hostCallsDenied = false;
+
+/** 从此以后拒绝宿主调用（本次运行内不可恢复）。 */
+export function denyHostCalls(): void {
+  hostCallsDenied = true;
+}
+
+/** 发一次宿主调用，等父进程的 `reply`。 */
+export function call(method: HostMethod, payload: unknown): Promise<unknown> {
+  if (hostCallsDenied) return Promise.reject(new ConnectorError('HOST_CALL_DENIED', `${method} is not available in simulate()`));
+  const id = nextCallId;
+  nextCallId += 1;
+  return new Promise<unknown>((resolve, reject) => {
+    try {
+      enqueue({ type: 'call', id, method, payload });
+    } catch (error) {
+      reject(new TypeError(`${method} payload is not serializable: ${error instanceof Error ? error.message : String(error)}`));
+      return;
+    }
+    pending.set(id, { resolve, reject });
+  });
+}
+
+/** 等待 `ms` 毫秒；运行被取消时提前结束（调用方随后检查 `isAborted()`）。 */
+export function sleep(ms: number): Promise<void> {
+  if (aborted || !(ms > 0)) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    timers[timers.length] = { at: now() + ms, resolve };
+  });
+}
+
+export function isAborted(): boolean {
+  return aborted;
+}
+
+/** 是否因宿主要求提前结束（而不是取消）而中止。 */
+export function isStopped(): boolean {
+  return stopped;
+}
+
+/** 宿主要求提前结束：触发 `ctx.signal`（`aborted` 置位、回调执行），拉取随后以 `stopped: true` 正常结束。 */
+export function requestStop(): void {
+  if (aborted) return;
+  stopped = true;
+  abort();
+}
+
+export function throwIfAborted(): void {
+  if (aborted) throw new CanceledError();
+}
+
+export function onAbort(listener: () => void): void {
+  if (aborted) {
+    void Promise.resolve().then(() => runListener(listener));
+    return;
+  }
+  abortListeners[abortListeners.length] = listener;
+}
+
+function runListener(listener: () => void): void {
+  try {
+    listener();
+  } catch {
+    // 连接器的取消回调出错不影响取消本身
+  }
+}
+
+function abort(): void {
+  if (aborted) return;
+  aborted = true;
+  // 正在等待的定时器立即结束，让重试与退避尽快看到取消。
+  const due = timers;
+  timers = [];
+  for (const timer of due) timer.resolve();
+  // 在途的宿主调用不再等回复：父进程随后会结束子进程。
+  for (const [id, entry] of pending) {
+    pending.delete(id);
+    entry.reject(new CanceledError());
+  }
+  const listeners = abortListeners.splice(0, abortListeners.length);
+  for (const listener of listeners) runListener(listener);
+}
+
+/** 发出最终结果（`result` / `failure`）；只生效一次。 */
+export function finish(message: Record<string, unknown>): void {
+  if (finished) return;
+  finished = true;
+  try {
+    enqueue(message);
+  } catch (error) {
+    outbox[outbox.length] = jsonStringify({
+      type: 'failure', code: 'FATAL_ERROR', logs: [],
+      message: `connector result is not serializable: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}
+
+export function isFinished(): boolean {
+  return finished;
+}
+
+/** 父进程消息（已由宿主侧 `parseParentMessage` 校验并重新序列化）。 */
+export function handle(json: string): void {
+  if (typeof json !== 'string') return;
+  let message: unknown;
+  try {
+    message = jsonParse(json);
+  } catch {
+    return;
+  }
+  if (!isRecord(message)) return;
+  if (message.type === 'cancel') {
+    abort();
+    return;
+  }
+  if (message.type !== 'reply' || typeof message.id !== 'number') return;
+  const entry = pending.get(message.id);
+  if (!entry) return;
+  pending.delete(message.id);
+  if (message.ok === true) {
+    entry.resolve(message.value);
+    return;
+  }
+  const error = isRecord(message.error) ? message.error : {};
+  entry.reject(new HostCallFailure(
+    typeof error.code === 'string' ? error.code : 'HOST_ERROR',
+    typeof error.message === 'string' ? error.message : 'host call failed',
+    typeof error.status === 'number' ? error.status : undefined,
+    typeof error.retryAfterMs === 'number' ? error.retryAfterMs : undefined,
+  ));
+}
+
+/**
+ * 触发到期的定时器并取走待发消息。返回 `{ out, wake, fired }`：`out` 是待发消息的 JSON 字符串，
+ * `wake` 是距下一个定时器的毫秒数（没有则为 -1），`fired` 表示本次触发了定时器（宿主应在微任务跑完后再 poll 一次）。
+ */
+export function poll(): string {
+  const current = now();
+  let fired = false;
+  if (timers.length > 0) {
+    const due: Timer[] = [];
+    const rest: Timer[] = [];
+    for (const timer of timers) {
+      if (timer.at <= current) due[due.length] = timer;
+      else rest[rest.length] = timer;
+    }
+    timers = rest;
+    for (const timer of due) timer.resolve();
+    fired = due.length > 0;
+  }
+  let wake = -1;
+  for (const timer of timers) wake = wake < 0 ? timer.at - current : mathMin(wake, timer.at - current);
+  const out = outbox;
+  outbox = [];
+  return `{"out":[${out.join(',')}],"wake":${wake < 0 ? -1 : wake},"fired":${fired ? 'true' : 'false'}}`;
+}

package/src/runtime/guest/cache.ts

@@ -0,0 +1,43 @@
+/** `ctx.cache`：按连接隔离、跨运行保留的小型键值缓存，存在宿主侧（加密存储）。 */
+import type { ConnectorCache } from '../../types';
+import type { CacheEntry } from '../protocol';
+import { call, now } from './bridge';
+
+function key(value: unknown): string {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError('cache key must be a non-empty string');
+  return value;
+}
+
+function ttl(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) throw new TypeError('cache ttlSeconds must be a positive integer');
+  return value;
+}
+
+async function get(name: string): Promise<string | undefined> {
+  const entry = await call('cache.get', { key: key(name) }) as CacheEntry | null;
+  if (entry === null || typeof entry !== 'object' || typeof entry.value !== 'string') return undefined;
+  const expiresAt = typeof entry.expiresAt === 'string' ? Date.parse(entry.expiresAt) : Number.NaN;
+  if (!Number.isNaN(expiresAt) && expiresAt <= now()) return undefined;
+  return entry.value;
+}
+
+async function set(name: string, value: string, ttlSeconds: number): Promise<void> {
+  if (typeof value !== 'string') throw new TypeError('cache value must be a string');
+  await call('cache.set', { key: key(name), value, ttlSeconds: ttl(ttlSeconds) });
+}
+
+export function createCache(): ConnectorCache {
+  return Object.freeze({
+    get: (name: string) => Promise.resolve().then(() => get(name)),
+    set: (name: string, value: string, ttlSeconds: number) => Promise.resolve().then(() => set(name, value, ttlSeconds)),
+    async getOrSet(name: string, ttlSeconds: number, fn: () => Promise<string>): Promise<string> {
+      ttl(ttlSeconds);
+      if (typeof fn !== 'function') throw new TypeError('cache.getOrSet expects a function');
+      const cached = await get(name);
+      if (cached !== undefined) return cached;
+      const value = await fn();
+      await set(name, value, ttlSeconds);
+      return value;
+    },
+  });
+}

package/src/runtime/guest/check.ts

@@ -0,0 +1,17 @@
+/** check 作业：只跑连接器的 `check`（描述里没有 `check` 时直接成功），结果 `{ kind: 'check', ok: true, logs }`。 */
+import type { GuestResult } from '../protocol';
+import { throwIfAborted } from './bridge';
+import { createCheckContext, type ContextOptions } from './ctx';
+import { failureFromError, type FailureMessage } from './failure';
+import type { LoadedConnector } from './loader';
+
+export async function runCheck(connector: LoadedConnector, options: ContextOptions): Promise<{ type: 'result'; result: GuestResult } | FailureMessage> {
+  const ctx = createCheckContext(options);
+  try {
+    if (connector.check) await Reflect.apply(connector.check, undefined, [ctx]);
+    throwIfAborted();
+  } catch (error) {
+    return failureFromError(error, options.logs.drain());
+  }
+  return { type: 'result', result: { kind: 'check', ok: true, logs: options.logs.drain() } };
+}

package/src/runtime/guest/crypto.ts

@@ -0,0 +1,166 @@
+/**
+ * `ctx.crypto`：`hmac` / `sign` / `hash` 走宿主（vm 上下文里没有 WebCrypto；`key` 可以是凭证句柄，由网关代算），
+ * `base64Encode` / `base64Decode` 在 guest 里纯 JS 实现（按 UTF-8）。
+ */
+import type { ConnectorCrypto, DigestEncoding, HashAlgorithm, HmacAlgorithm, SignAlgorithm } from '../../types';
+import type { CryptoRequest, CryptoResponse } from '../protocol';
+import { call } from './bridge';
+
+const HMAC_ALGORITHMS: readonly string[] = ['sha1', 'sha256', 'sha512'];
+const HASH_ALGORITHMS: readonly string[] = ['md5', 'sha1', 'sha256', 'sha512'];
+const ENCODINGS: readonly string[] = ['hex', 'base64'];
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function encoding(value: unknown): DigestEncoding {
+  if (value === undefined) return 'hex';
+  if (typeof value !== 'string' || !ENCODINGS.includes(value)) throw new TypeError("encoding must be 'hex' or 'base64'");
+  return value as DigestEncoding;
+}
+
+function text(value: unknown, what: string): string {
+  if (typeof value !== 'string') throw new TypeError(`${what} must be a string`);
+  return value;
+}
+
+async function digest(request: CryptoRequest): Promise<string> {
+  const response = await call('crypto', request) as CryptoResponse | null;
+  if (!response || typeof response.value !== 'string') throw new TypeError('crypto host call returned no value');
+  return response.value;
+}
+
+export function utf8Encode(input: string): number[] {
+  const bytes: number[] = [];
+  for (let i = 0; i < input.length; i += 1) {
+    let code = input.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < input.length) {
+      const low = input.charCodeAt(i + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        i += 1;
+      }
+    }
+    if (code >= 0xd800 && code <= 0xdfff) code = 0xfffd;
+    if (code < 0x80) bytes.push(code);
+    else if (code < 0x800) bytes.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+    else if (code < 0x10000) bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+    else bytes.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 63), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+  }
+  return bytes;
+}
+
+/** UTF-8 字节数，用于批次大小统计。 */
+export function utf8Length(input: string): number {
+  let length = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    const code = input.charCodeAt(i);
+    if (code < 0x80) length += 1;
+    else if (code < 0x800) length += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < input.length) {
+      const low = input.charCodeAt(i + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        length += 4;
+        i += 1;
+      } else {
+        length += 3;
+      }
+    } else length += 3;
+  }
+  return length;
+}
+
+function utf8Decode(bytes: readonly number[]): string {
+  let out = '';
+  let i = 0;
+  while (i < bytes.length) {
+    const b0 = bytes[i] ?? 0;
+    let code = 0xfffd;
+    let size = 1;
+    const cont = (offset: number) => {
+      const b = bytes[i + offset];
+      return b !== undefined && (b & 0xc0) === 0x80 ? b & 63 : -1;
+    };
+    if (b0 < 0x80) {
+      code = b0;
+    } else if (b0 >= 0xc2 && b0 < 0xe0) {
+      const b1 = cont(1);
+      if (b1 >= 0) { code = ((b0 & 31) << 6) | b1; size = 2; }
+    } else if (b0 >= 0xe0 && b0 < 0xf0) {
+      const b1 = cont(1);
+      const b2 = cont(2);
+      if (b1 >= 0 && b2 >= 0) {
+        const value = ((b0 & 15) << 12) | (b1 << 6) | b2;
+        if (value >= 0x800 && (value < 0xd800 || value > 0xdfff)) { code = value; size = 3; }
+      }
+    } else if (b0 >= 0xf0 && b0 < 0xf5) {
+      const b1 = cont(1);
+      const b2 = cont(2);
+      const b3 = cont(3);
+      if (b1 >= 0 && b2 >= 0 && b3 >= 0) {
+        const value = ((b0 & 7) << 18) | (b1 << 12) | (b2 << 6) | b3;
+        if (value >= 0x10000 && value <= 0x10ffff) { code = value; size = 4; }
+      }
+    }
+    out += String.fromCodePoint(code);
+    i += size;
+  }
+  return out;
+}
+
+export function bytesToBase64(bytes: readonly number[]): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1];
+    const b2 = bytes[i + 2];
+    const chunk = (b0 << 16) | ((b1 ?? 0) << 8) | (b2 ?? 0);
+    out += ALPHABET.charAt((chunk >> 18) & 63) + ALPHABET.charAt((chunk >> 12) & 63);
+    out += b1 === undefined ? '=' : ALPHABET.charAt((chunk >> 6) & 63);
+    out += b2 === undefined ? '=' : ALPHABET.charAt(chunk & 63);
+  }
+  return out;
+}
+
+export function base64ToBytes(input: string): number[] {
+  const clean = input.replace(/[\s=]/g, '').replace(/-/g, '+').replace(/_/g, '/');
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (let i = 0; i < clean.length; i += 1) {
+    const value = ALPHABET.indexOf(clean.charAt(i));
+    if (value < 0) throw new TypeError('invalid base64 text');
+    buffer = (buffer << 6) | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 0xff);
+    }
+  }
+  return bytes;
+}
+
+export function base64Encode(input: string): string {
+  return bytesToBase64(utf8Encode(text(input, 'base64Encode input')));
+}
+
+export function base64Decode(input: string): string {
+  return utf8Decode(base64ToBytes(text(input, 'base64Decode input')));
+}
+
+export function createCrypto(): ConnectorCrypto {
+  return Object.freeze({
+    hmac(algorithm: HmacAlgorithm, key: string, data: string, enc?: DigestEncoding): Promise<string> {
+      if (!HMAC_ALGORITHMS.includes(algorithm)) return Promise.reject(new TypeError(`unsupported hmac algorithm ${String(algorithm)}`));
+      return Promise.resolve().then(() => digest({ op: 'hmac', algorithm, key: text(key, 'hmac key'), data: text(data, 'hmac data'), encoding: encoding(enc) }));
+    },
+    sign(algorithm: SignAlgorithm, key: string, data: string, enc?: DigestEncoding): Promise<string> {
+      if (algorithm !== 'rsa-sha256') return Promise.reject(new TypeError(`unsupported sign algorithm ${String(algorithm)}`));
+      return Promise.resolve().then(() => digest({ op: 'sign', algorithm, key: text(key, 'sign key'), data: text(data, 'sign data'), encoding: encoding(enc) }));
+    },
+    hash(algorithm: HashAlgorithm, data: string, enc?: DigestEncoding): Promise<string> {
+      if (!HASH_ALGORITHMS.includes(algorithm)) return Promise.reject(new TypeError(`unsupported hash algorithm ${String(algorithm)}`));
+      return Promise.resolve().then(() => digest({ op: 'hash', algorithm, data: text(data, 'hash data'), encoding: encoding(enc) }));
+    },
+    base64Encode,
+    base64Decode,
+  });
+}

package/src/runtime/guest/ctx.ts

@@ -0,0 +1,157 @@
+/**
+ * 拉取、check 与建议列用的 `ctx`。所有成员都在上下文里定义（guest 自己的函数与对象），
+ * 宿主能力只经 `bridge.call` 的 JSON 消息取得。
+ */
+import { errors } from '../../errors';
+import type { ConnectorDescriptor } from '../../descriptor';
+import type { CheckContext, CheckpointItem, PullContext, RecordItem, RemoveItem } from '../../types';
+import type { JobRateLimit, SecretRevealResponse } from '../protocol';
+import { call } from './bridge';
+import { createCache } from './cache';
+import { createCrypto } from './crypto';
+import { createDb } from './db';
+import { createHttp } from './http';
+import { DEFAULT_CONCURRENCY } from './limits';
+import type { LogBuffer } from './log';
+import { createMap } from './map';
+import { createPaginate } from './paginate';
+import { createSignal } from './signal';
+import { createTime } from './time';
+
+/** 凭证句柄的前缀，与 shared 的 `SECRET_HANDLE_PREFIX` 同值。 */
+export const SECRET_HANDLE_PREFIX = 'ontos:secret:';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  for (const key of Object.keys(value)) deepFreeze((value as Record<string, unknown>)[key]);
+  return Object.freeze(value);
+}
+
+function isHttpUrl(text: string): boolean {
+  try {
+    const url = new URL(text);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 相对路径的缺省基址：按声明顺序第一个有值的 `url` 配置项（原样，可带路径）；没有时取 `hosts` 里第一个确定的主机（不含 `*`）；都没有为 null。
+ */
+export function defaultBaseUrl(descriptor: Pick<ConnectorDescriptor, 'config' | 'hosts'>, config: Record<string, unknown>): string | null {
+  for (const [name, field] of Object.entries(descriptor.config)) {
+    if (field.type !== 'url') continue;
+    const value = config[name];
+    if (typeof value === 'string' && isHttpUrl(value)) return value;
+  }
+  for (const host of descriptor.hosts) {
+    if (!host.includes('*')) return `https://${host}`;
+  }
+  return null;
+}
+
+/** 描述里的凭证配置项：名字与是否 `exposeToScript`。 */
+function secretFieldsOf(descriptor: Pick<ConnectorDescriptor, 'config'>): Map<string, boolean> {
+  const fields = new Map<string, boolean>();
+  for (const [name, field] of Object.entries(descriptor.config)) {
+    if (field.type === 'secret') fields.set(name, field.exposeToScript === true);
+  }
+  return fields;
+}
+
+/**
+ * `ctx.secrets`：每个已配置的凭证字段给句柄 `ontos:secret:<字段>`；`exposeToScript` 的字段经 `secret.reveal`
+ * 取明文。`ctx.secrets` 是同步读取的普通对象，所以这些字段在作业开始前各取一次，缓存到本次运行结束。
+ */
+export async function prepareSecrets(descriptor: Pick<ConnectorDescriptor, 'config'>, secretFields: readonly string[]): Promise<Readonly<Record<string, string>>> {
+  const declared = secretFieldsOf(descriptor);
+  const secrets: Record<string, string> = {};
+  for (const field of secretFields) {
+    const exposed = declared.get(field);
+    if (exposed === undefined) continue;
+    if (exposed) {
+      const response = await call('secret.reveal', { field }) as SecretRevealResponse | null;
+      if (!isRecord(response) || typeof response.value !== 'string') throw new TypeError(`secret.reveal returned no value for ${field}`);
+      secrets[field] = response.value;
+    } else {
+      secrets[field] = `${SECRET_HANDLE_PREFIX}${field}`;
+    }
+  }
+  return Object.freeze(secrets);
+}
+
+export interface ContextOptions {
+  config: Record<string, unknown>;
+  secrets: Readonly<Record<string, string>>;
+  descriptor: ConnectorDescriptor;
+  logs: LogBuffer;
+  /** 作业里宿主给出的生效限流（连接覆盖与描述取小）；没给时只按描述。 */
+  rateLimit?: JobRateLimit | undefined;
+}
+
+/**
+ * `ctx.map` 的并发上限：描述的 `rateLimit.concurrency`（缺省 4）与作业的生效并发取小。
+ * 网关按「描述与连接覆盖取小」限流，`ctx.map` 的上限要跟它一致，否则覆盖更小时会一直撞 429。
+ */
+function mapConcurrency(options: ContextOptions): number {
+  const declared = options.descriptor.rateLimit?.concurrency ?? DEFAULT_CONCURRENCY;
+  const effective = options.rateLimit?.concurrency;
+  return typeof effective === 'number' && Number.isFinite(effective) && effective >= 1 ? Math.min(declared, Math.floor(effective)) : declared;
+}
+
+function tableName(table: unknown): string {
+  if (typeof table !== 'string' || table.length === 0) throw new TypeError('table must be a non-empty string');
+  return table;
+}
+
+function plainObject(value: unknown, what: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new TypeError(`${what} must be an object`);
+  return value;
+}
+
+export function createCheckContext(options: ContextOptions): CheckContext {
+  const config = deepFreeze(options.config);
+  const http = createHttp(defaultBaseUrl(options.descriptor, config));
+  const ctx = {
+    config,
+    secrets: options.secrets,
+    http,
+    paginate: createPaginate(http),
+    db: createDb(),
+    map: createMap(mapConcurrency(options)),
+    cache: createCache(),
+    crypto: createCrypto(),
+    time: createTime(),
+    log: options.logs.logger(),
+    signal: createSignal(),
+  };
+  Object.defineProperty(ctx, 'files', {
+    get() {
+      throw new errors.NotAvailable('ctx.files');
+    },
+  });
+  return Object.freeze(ctx) as unknown as CheckContext;
+}
+
+/** 拉取的 `ctx`：`record` / `remove` / `checkpoint` 只产出标记，没有副作用；只有 `yield` 出来的标记算数。 */
+export function createPullContext(options: ContextOptions): PullContext {
+  const base = createCheckContext(options);
+  const ctx = Object.create(null) as Record<string, unknown>;
+  for (const key of Object.keys(base)) ctx[key] = (base as unknown as Record<string, unknown>)[key];
+  Object.defineProperty(ctx, 'files', {
+    get() {
+      throw new errors.NotAvailable('ctx.files');
+    },
+  });
+  ctx.record = (table: string, row: Record<string, unknown>): RecordItem =>
+    Object.freeze({ __ontos: 'record', table: tableName(table), row: plainObject(row, 'row') });
+  ctx.remove = (table: string, key: Record<string, unknown>): RemoveItem =>
+    Object.freeze({ __ontos: 'remove', table: tableName(table), key: plainObject(key, 'key') });
+  ctx.checkpoint = (state: unknown): CheckpointItem => Object.freeze({ __ontos: 'checkpoint', state });
+  return Object.freeze(ctx) as unknown as PullContext;
+}

package/src/runtime/guest/db.ts

@@ -0,0 +1,59 @@
+/**
+ * `ctx.db`：经宿主的数据库代理执行只读查询。`db.query` 回第一批行与游标，未完时逐批 `db.next`；
+ * 迭代中途退出（`break` / 抛错）时发 `db.close` 释放游标。参数在这里规整成 JSON 值（日期转 ISO 文本，bigint 转字符串）。
+ */
+import type { ConnectorDb } from '../../types';
+import type { DbNextResponse, DbQueryResponse } from '../protocol';
+import { call, isAborted, throwIfAborted } from './bridge';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function param(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  return value;
+}
+
+function rowsOf(value: unknown): Array<Record<string, unknown>> {
+  if (!isRecord(value) || !Array.isArray(value.rows) || typeof value.done !== 'boolean') throw new TypeError('db host call returned a malformed response');
+  return value.rows as Array<Record<string, unknown>>;
+}
+
+async function* run<R>(sql: string, params: unknown[]): AsyncGenerator<R> {
+  throwIfAborted();
+  const first = await call('db.query', { sql, params: params.map(param) }) as DbQueryResponse;
+  let rows = rowsOf(first);
+  let done = first.done;
+  const cursorId = typeof first.cursorId === 'string' ? first.cursorId : null;
+  if (!done && cursorId === null) throw new TypeError('db host call returned more rows without a cursor');
+  try {
+    for (;;) {
+      for (const row of rows) yield row as R;
+      if (done || cursorId === null) return;
+      throwIfAborted();
+      const next = await call('db.next', { cursorId }) as DbNextResponse;
+      rows = rowsOf(next);
+      done = next.done;
+    }
+  } finally {
+    if (!done && cursorId !== null) {
+      const closing = call('db.close', { cursorId });
+      // 取消之后父进程不再保证回复，不等它。
+      if (isAborted()) closing.catch(() => undefined);
+      else await closing;
+    }
+  }
+}
+
+export function createDb(): ConnectorDb {
+  return Object.freeze({
+    query<R = Record<string, unknown>>(sql: string, params: unknown[] = []): AsyncIterable<R> {
+      if (typeof sql !== 'string' || sql.trim().length === 0) throw new TypeError('ctx.db.query expects a SQL string');
+      if (!Array.isArray(params)) throw new TypeError('ctx.db.query params must be an array');
+      return run<R>(sql, [...params]);
+    },
+  });
+}