@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/testing/source-loader.ts

@@ -0,0 +1,374 @@
+/**
+ * 本地加载连接器：读 `.ontos/descriptor.json`（codegen 生成），按虚拟入口契约把源码目录转译成一个 CommonJS 打包串
+ * （给 `createVmExecutor`，与 runner 同一个 guest 会话执行），并收集能力目录下的测试用例文件。
+ *
+ * - 只用调用方传入的 TypeScript 编译器 API 做语法转译（`transpileModule`：CommonJS、ES2022、单独产 sourcemap），
+ *   不执行任何构建期插件，不依赖打包器，也不依赖 shared；
+ * - 入口由描述生成（与平台的虚拟入口同一结构）：导出 `descriptor` 与 `implementations`，后者按目录约定引用
+ *   `check.ts`、`streams/<名>/index.ts`、`streams/<名>/suggest-columns.ts`、`pushes/<名>/index.ts`、`operations/<名>/index.ts`
+ *   的默认导出；文件不存在时不放进 `implementations`，由 guest 加载时报出缺失；
+ * - 从这些文件起按 `require` 关系收集模块，每个模块先过 `import-guard.ts` 的检查（与服务端打包同一套规则）：
+ *   只允许相对路径与 `@deepexi/datasense-connector`；
+ * - 打包串是一张模块表加一个按预先解析好的相对路径查表的 `require`；SDK 说明符留给 guest 的 `require`（vm 里由 guest 提供）；
+ * - sourcemap 是按模块分段的索引映射（`sections`），行号与打包串一一对应（guest 把打包串包进函数时与第一行同行）。
+ *
+ * 收集源码时跳过 `node_modules`、`.git`、`dist`、`.ontos`、`.datasense` 与能力目录下的 `tests/`（与 CLI 上传一致）；
+ * 遇到符号链接直接拒绝（`SYMLINK`），源码总量超过 2 MiB 或文件数超过 200 拒绝（`TOO_LARGE`）。
+ */
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type * as TS from 'typescript';
+import type { ConnectorDescriptor } from '../descriptor';
+import { OPERATION_NAME_PATTERN, SDK_NAME_PATTERN } from '../validate';
+import { readFixtureDir, type ConnectorFixtureFile } from './fixtures';
+import {
+  asTypeScript, classifySpecifier, collectRequires, collectSourceSpecifiers, CONNECTOR_SDK_SPECIFIER, findForbiddenSourceSyntax, type TypeScriptApi,
+} from './import-guard';
+import { SourceLoadError } from './types';
+
+/** 本地加载好的连接器。 */
+export interface LocalConnector {
+  /** 源码根目录（绝对路径）。 */
+  dir: string;
+  name: string;
+  version: string;
+  /** `.ontos/descriptor.json` 的内容。 */
+  descriptor: ConnectorDescriptor;
+  /** CommonJS 打包串，交给 guest 会话的 `execute.code`；导出 `{ descriptor, implementations }`。 */
+  code: string;
+  /** 索引映射形式的 sourcemap（JSON 文本），`sources` 为相对源码根目录的路径。 */
+  sourcemap: string;
+  /** 源码文件（相对路径 → 文本，不含 `tests/` 与 `.ontos/`）。 */
+  files: Record<string, string>;
+  /** 能力目录下 `tests/` 里的全部文件（路径相对源码根目录，按路径排序）。 */
+  testFiles: ConnectorFixtureFile[];
+  /** `dependencies` 里 SDK 的写法（版本范围或 `file:` 路径），由调用方按共享规则校验。 */
+  sdkRange: string;
+}
+
+/** 与 shared `connector-limits.ts` 同值。 */
+export const LOCAL_SOURCE_MAX_BYTES = 2 * 1024 * 1024;
+export const LOCAL_SOURCE_MAX_FILES = 200;
+
+export const DESCRIPTOR_FILE = '.ontos/descriptor.json';
+/** codegen 生成的类型与已绑定类型的编写函数；源码可以 `import` 它，加载时并入模块表（不算源码文件，不上传）。 */
+export const GENERATED_TYPES_FILE = '.ontos/types.ts';
+
+const EXCLUDED_DIRECTORIES: ReadonlySet<string> = new Set(['node_modules', '.git', 'dist', '.ontos', '.datasense']);
+const CAPABILITY_GROUPS: ReadonlySet<string> = new Set(['streams', 'pushes', 'operations']);
+const TESTS_DIRECTORY = 'tests';
+const CODE_FILE = /\.[cm]?[jt]sx?$/;
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+const ENTRY_ID = '.ontos/entry.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** `<streams|pushes|operations>/<名>/tests` 目录（测试用例，不算源码）。 */
+function isTestsDirectory(relative: string): boolean {
+  const parts = relative.split('/');
+  return parts.length === 3 && CAPABILITY_GROUPS.has(parts[0] ?? '') && parts[2] === TESTS_DIRECTORY;
+}
+
+async function collectFiles(root: string): Promise<Record<string, string>> {
+  const files: Record<string, string> = {};
+  let count = 0;
+  let bytes = 0;
+  const visit = async (absolute: string, relative: string): Promise<void> => {
+    const entries = await readdir(absolute, { withFileTypes: true });
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      // 排除目录先判：`node_modules` 等本身是符号链接（pnpm、monorepo 链接）时也直接跳过，不报 SYMLINK。
+      const excluded = EXCLUDED_DIRECTORIES.has(entry.name) || isTestsDirectory(childRelative);
+      if (excluded && (entry.isDirectory() || entry.isSymbolicLink())) continue;
+      if (entry.isSymbolicLink()) {
+        throw new SourceLoadError('SYMLINK', `symbolic links are not supported in connector source: ${childRelative}`, childRelative);
+      }
+      if (entry.isDirectory()) {
+        await visit(path.join(absolute, entry.name), childRelative);
+      } else if (entry.isFile()) {
+        count += 1;
+        if (count > LOCAL_SOURCE_MAX_FILES) {
+          throw new SourceLoadError('TOO_LARGE', `connector source has more than ${LOCAL_SOURCE_MAX_FILES} files`);
+        }
+        const text = await readFile(path.join(absolute, entry.name), 'utf8');
+        bytes += Buffer.byteLength(text, 'utf8');
+        if (bytes > LOCAL_SOURCE_MAX_BYTES) {
+          throw new SourceLoadError('TOO_LARGE', `connector source exceeds ${LOCAL_SOURCE_MAX_BYTES} bytes`);
+        }
+        files[childRelative] = text;
+      }
+    }
+  };
+  await visit(root, '');
+  return files;
+}
+
+/** `package.json` 只读 SDK 依赖（其余字段的规则由平台校验）。 */
+function readSdkRange(files: Record<string, string>): string {
+  const text = files['package.json'];
+  if (text === undefined) throw new SourceLoadError('MANIFEST_INVALID', 'package.json is missing', 'package.json');
+  let pkg: unknown;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    throw new SourceLoadError('MANIFEST_INVALID', 'package.json is not valid JSON', 'package.json');
+  }
+  if (!isRecord(pkg)) throw new SourceLoadError('MANIFEST_INVALID', 'package.json must be a JSON object', 'package.json');
+  const invalid = (message: string) => new SourceLoadError('MANIFEST_INVALID', message, 'package.json');
+  const dependencies = pkg.dependencies;
+  if (!isRecord(dependencies)) throw invalid(`dependencies must list ${CONNECTOR_SDK_SPECIFIER}`);
+  for (const dependency of Object.keys(dependencies)) {
+    if (dependency !== CONNECTOR_SDK_SPECIFIER) throw invalid(`connectors can only depend on ${CONNECTOR_SDK_SPECIFIER}, found ${dependency}`);
+  }
+  const sdkRange = dependencies[CONNECTOR_SDK_SPECIFIER];
+  if (typeof sdkRange !== 'string' || sdkRange.length === 0) throw invalid(`dependencies must list ${CONNECTOR_SDK_SPECIFIER}`);
+  return sdkRange;
+}
+
+/** 读 `.ontos/types.ts`（没有时为 null；符号链接或非普通文件拒绝）。 */
+async function readGeneratedTypes(root: string): Promise<string | null> {
+  const file = path.join(root, GENERATED_TYPES_FILE);
+  const stat = await lstat(file).catch(() => null);
+  if (!stat) return null;
+  if (stat.isSymbolicLink()) throw new SourceLoadError('SYMLINK', `symbolic links are not supported in connector source: ${GENERATED_TYPES_FILE}`, GENERATED_TYPES_FILE);
+  if (!stat.isFile()) throw new SourceLoadError('DESCRIPTOR_INVALID', `${GENERATED_TYPES_FILE} must be a regular file; ${REGENERATE_HINT}`, GENERATED_TYPES_FILE);
+  return readFile(file, 'utf8');
+}
+
+const REGENERATE_HINT = 'run `ontos admin connector codegen` to regenerate it';
+
+/** 读 `.ontos/descriptor.json`：名字会拼进模块路径，所以先按名字规则检查。 */
+async function readDescriptor(root: string): Promise<ConnectorDescriptor> {
+  const file = path.join(root, DESCRIPTOR_FILE);
+  const stat = await lstat(file).catch(() => null);
+  if (!stat) {
+    throw new SourceLoadError('DESCRIPTOR_NOT_GENERATED', `${DESCRIPTOR_FILE} not found; run \`ontos admin connector codegen\` first`, DESCRIPTOR_FILE);
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new SourceLoadError('DESCRIPTOR_INVALID', `${DESCRIPTOR_FILE} must be a regular file; ${REGENERATE_HINT}`, DESCRIPTOR_FILE);
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    throw new SourceLoadError('DESCRIPTOR_INVALID', `${DESCRIPTOR_FILE} is not valid JSON; ${REGENERATE_HINT}`, DESCRIPTOR_FILE);
+  }
+  const invalid = (message: string) => new SourceLoadError('DESCRIPTOR_INVALID', `${DESCRIPTOR_FILE}: ${message}; ${REGENERATE_HINT}`, DESCRIPTOR_FILE);
+  if (!isRecord(value) || typeof value.name !== 'string' || typeof value.version !== 'string') throw invalid('name and version are required');
+  for (const key of ['config', 'streams', 'pushes', 'operations'] as const) {
+    if (!isRecord(value[key])) throw invalid(`${key} must be an object`);
+  }
+  for (const key of ['streams', 'pushes'] as const) {
+    for (const name of Object.keys(value[key] as Record<string, unknown>)) {
+      if (!SDK_NAME_PATTERN.test(name)) throw invalid(`${key} name ${JSON.stringify(name)} must match ${SDK_NAME_PATTERN.source}`);
+    }
+  }
+  for (const name of Object.keys(value.operations as Record<string, unknown>)) {
+    if (!OPERATION_NAME_PATTERN.test(name)) throw invalid(`operation name ${JSON.stringify(name)} must match ${OPERATION_NAME_PATTERN.source}`);
+  }
+  return value as unknown as ConnectorDescriptor;
+}
+
+function resolveModule(files: Record<string, string>, target: string): string | null {
+  const base = target === '.' ? 'index' : target;
+  const candidates = [base, ...RESOLVE_EXTENSIONS.map((ext) => `${base}${ext}`), ...RESOLVE_EXTENSIONS.map((ext) => `${base}/index${ext}`)];
+  for (const candidate of candidates) {
+    if (Object.hasOwn(files, candidate) && (CODE_FILE.test(candidate) || candidate.endsWith('.json'))) return candidate;
+  }
+  return null;
+}
+
+interface Module {
+  id: string;
+  /** 模块函数体（已转译的 CommonJS 代码）。 */
+  body: string;
+  /** 该模块的 sourcemap（v3 对象），JSON 模块没有。 */
+  map: Record<string, unknown> | null;
+  /** 说明符 → 模块 id；SDK 为 null（交给 guest 的 require）。 */
+  requires: Record<string, string | null>;
+}
+
+const SOURCE_MAP_COMMENT = /\n?\/\/# sourceMappingURL=[^\n]*\s*$/;
+
+function transpile(ts: TypeScriptApi, id: string, content: string): { code: string; map: Record<string, unknown> } {
+  const output = ts.transpileModule(content, {
+    fileName: id,
+    reportDiagnostics: false,
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2022,
+      esModuleInterop: true,
+      sourceMap: true,
+      inlineSourceMap: false,
+      inlineSources: true,
+      jsx: ts.JsxEmit.React,
+    } satisfies TS.CompilerOptions,
+  });
+  const code = output.outputText.replace(SOURCE_MAP_COMMENT, '');
+  let map: Record<string, unknown> = { version: 3, sources: [id], names: [], mappings: '' };
+  if (output.sourceMapText) {
+    const parsed = JSON.parse(output.sourceMapText) as Record<string, unknown>;
+    map = { ...parsed, sources: [id], sourceRoot: '' };
+    delete map.file;
+  }
+  return { code, map };
+}
+
+function loadModule(ts: TypeScriptApi, files: Record<string, string>, id: string): Module {
+  const content = files[id] ?? '';
+  if (id.endsWith('.json')) {
+    try {
+      JSON.parse(content);
+    } catch (error) {
+      throw new SourceLoadError('SYNTAX_ERROR', `${id} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, id);
+    }
+    // 走 JSON.parse 而不是内联成对象字面量：字面量里的 `"__proto__"` 键会改原型，JSON 语义下它只是普通键。
+    return { id, body: `module.exports = JSON.parse(${JSON.stringify(content)});`, map: null, requires: {} };
+  }
+  const problems = findForbiddenSourceSyntax(ts, id, content);
+  const syntax = problems.find((problem) => problem.kind === 'syntax');
+  if (syntax) throw new SourceLoadError('SYNTAX_ERROR', `${id}:${syntax.line}:${syntax.column + 1} ${syntax.message}`, id);
+  const forbidden = problems[0];
+  if (forbidden) throw new SourceLoadError('IMPORT_FORBIDDEN', `${id}:${forbidden.line}:${forbidden.column + 1} ${forbidden.message}`, id);
+  // 源码层：写了但没用到的导入在转译时会被删掉，这里先按源码归类一遍。
+  for (const entry of collectSourceSpecifiers(ts, id, content)) {
+    const kind = classifySpecifier(entry.specifier, id);
+    if (kind.kind === 'escape') throw new SourceLoadError('PATH_ESCAPE', `${id}:${entry.line} import '${entry.specifier}' escapes the connector source root`, id);
+    if (kind.kind === 'forbidden') throw new SourceLoadError('IMPORT_FORBIDDEN', `${id}:${entry.line} ${kind.message}`, id);
+  }
+
+  const { code, map } = transpile(ts, id, content);
+  const requires: Record<string, string | null> = {};
+  for (const entry of collectRequires(ts, id, code)) {
+    if (entry.specifier === null) {
+      throw new SourceLoadError('IMPORT_FORBIDDEN', `${id}: imports must use a literal path (computed require / import() is not allowed)`, id);
+    }
+    const specifier = entry.specifier;
+    if (Object.hasOwn(requires, specifier)) continue;
+    const kind = classifySpecifier(specifier, id);
+    switch (kind.kind) {
+      case 'sdk':
+        requires[specifier] = null;
+        break;
+      case 'escape':
+        throw new SourceLoadError('PATH_ESCAPE', `${id}: import '${specifier}' escapes the connector source root`, id);
+      case 'forbidden':
+        throw new SourceLoadError('IMPORT_FORBIDDEN', `${id}: ${kind.message}`, id);
+      case 'relative': {
+        const resolved = resolveModule(files, kind.target);
+        if (resolved === null) throw new SourceLoadError('IMPORT_FORBIDDEN', `${id}: cannot resolve import '${specifier}'`, id);
+        requires[specifier] = resolved;
+        break;
+      }
+    }
+  }
+  return { id, body: code, map, requires };
+}
+
+function countLines(text: string): number {
+  let lines = 0;
+  for (let i = 0; i < text.length; i += 1) if (text.charCodeAt(i) === 10) lines += 1;
+  return lines;
+}
+
+/** 按虚拟入口契约生成入口模块：描述以 JSON 文本嵌入，实现按目录约定引用（只用校验过的名字拼路径）。 */
+function entryModule(descriptor: ConnectorDescriptor, files: Record<string, string>): Module {
+  const requires: Record<string, string | null> = {};
+  const ref = (file: string): string | null => {
+    if (!Object.hasOwn(files, file)) return null;
+    const specifier = `./${file}`;
+    requires[specifier] = file;
+    return `__ontosDefault(require(${JSON.stringify(specifier)}))`;
+  };
+  const group = (entries: Array<[string, string | null]>): string =>
+    `{ ${entries.filter((entry): entry is [string, string] => entry[1] !== null).map(([name, expression]) => `${JSON.stringify(name)}: ${expression}`).join(', ')} }`;
+  const streams = Object.keys(descriptor.streams);
+  const check = descriptor.check ? ref('check.ts') : null;
+  const lines = [
+    'var __ontosDefault = function (m) { return m !== null && typeof m === "object" && Object.prototype.hasOwnProperty.call(m, "default") ? m.default : m; };',
+    `var descriptor = JSON.parse(${JSON.stringify(JSON.stringify(descriptor))});`,
+    'module.exports = { descriptor: descriptor, implementations: {',
+    ...(check !== null ? [`  check: ${check},`] : []),
+    `  streams: ${group(streams.map((name) => [name, ref(`streams/${name}/index.ts`)]))},`,
+    `  suggestColumns: ${group(streams.filter((name) => descriptor.streams[name]?.suggestColumns === true).map((name) => [name, ref(`streams/${name}/suggest-columns.ts`)]))},`,
+    `  pushes: ${group(Object.keys(descriptor.pushes).map((name) => [name, ref(`pushes/${name}/index.ts`)]))},`,
+    `  operations: ${group(Object.keys(descriptor.operations).map((name) => [name, ref(`operations/${name}/index.ts`)]))},`,
+    '} };',
+  ];
+  return { id: ENTRY_ID, body: lines.join('\n'), map: null, requires };
+}
+
+/** 模块表 + 查表的 `require`；整段作为 guest 会话里 `(function (module, exports, require) {…})` 的函数体。 */
+function assemble(modules: Module[], entry: string): { code: string; sourcemap: string } {
+  const lines: string[] = ['var __ontosModules = {'];
+  const sections: Array<{ offset: { line: number; column: number }; map: Record<string, unknown> }> = [];
+  let line = 1;
+  for (const module of modules) {
+    lines.push(`${JSON.stringify(module.id)}: [${JSON.stringify(module.requires)}, function (module, exports, require) {`);
+    line += 1;
+    if (module.map) sections.push({ offset: { line, column: 0 }, map: module.map });
+    const body = module.body.endsWith('\n') ? module.body.slice(0, -1) : module.body;
+    lines.push(body);
+    line += countLines(body) + 1;
+    lines.push('}],');
+    line += 1;
+  }
+  lines.push(
+    '};',
+    'var __ontosCache = {};',
+    'function __ontosRequire(id) {',
+    '  var cached = __ontosCache[id];',
+    '  if (cached) return cached.exports;',
+    '  var entry = __ontosModules[id];',
+    '  var mod = { exports: {} };',
+    '  __ontosCache[id] = mod;',
+    '  var table = entry[0];',
+    '  entry[1].call(mod.exports, mod, mod.exports, function (specifier) {',
+    '    if (!Object.prototype.hasOwnProperty.call(table, specifier)) throw new Error("cannot require " + String(specifier) + " from " + id);',
+    '    var target = table[specifier];',
+    '    return target === null ? require(specifier) : __ontosRequire(target);',
+    '  });',
+    '  return mod.exports;',
+    '}',
+    `module.exports = __ontosRequire(${JSON.stringify(entry)});`,
+  );
+  return {
+    code: lines.join('\n'),
+    sourcemap: JSON.stringify({ version: 3, file: 'connector.js', sections }),
+  };
+}
+
+/**
+ * 本地加载连接器源码目录（见文件头）。`options.typescript` 是项目自己的 TypeScript 编译器 API（`import ts from 'typescript'`）。
+ * 没有 `.ontos/descriptor.json` 时抛 `SourceLoadError('DESCRIPTOR_NOT_GENERATED')`。
+ */
+export async function loadLocalConnector(dir: string, options: { typescript: unknown }): Promise<LocalConnector> {
+  const ts = asTypeScript(options.typescript);
+  const root = path.resolve(dir);
+  const stat = await lstat(root).catch(() => null);
+  if (!stat) throw new SourceLoadError('MANIFEST_INVALID', `connector source directory not found: ${dir}`);
+  if (stat.isSymbolicLink()) throw new SourceLoadError('SYMLINK', `the connector source directory is a symbolic link: ${dir}`);
+  if (!stat.isDirectory()) throw new SourceLoadError('MANIFEST_INVALID', `not a directory: ${dir}`);
+
+  const descriptor = await readDescriptor(root);
+  const files = await collectFiles(root);
+  const sdkRange = readSdkRange(files);
+  const generated = await readGeneratedTypes(root);
+  const sources = generated === null ? files : { ...files, [GENERATED_TYPES_FILE]: generated };
+  const entry = entryModule(descriptor, files);
+  const modules: Module[] = [entry];
+  const seen = new Set<string>([entry.id]);
+  const queue = Object.values(entry.requires).filter((target): target is string => target !== null);
+  while (queue.length > 0) {
+    const id = queue.shift() as string;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const module = loadModule(ts, sources, id);
+    modules.push(module);
+    for (const target of Object.values(module.requires)) if (target !== null && !seen.has(target)) queue.push(target);
+  }
+  const { code, sourcemap } = assemble(modules, entry.id);
+  const testFiles = await readFixtureDir(root);
+  return { dir: root, name: descriptor.name, version: descriptor.version, descriptor, code, sourcemap, files, testFiles, sdkRange };
+}

package/src/testing/types.ts

@@ -0,0 +1,78 @@
+/**
+ * `./testing` 的公共类型与错误类（本地运行、本地模拟网关、源码加载器共用）。
+ */
+import type { ConnectorDescriptor, SuggestedColumn } from '../descriptor';
+import type { GuestJob, GuestOperationResult, HostMethod } from '../runtime/protocol';
+
+export type { GuestJob, HostMethod };
+
+/**
+ * 宿主：guest 的宿主调用（`http` / `db.*` / `crypto` / `cache.*` / `secret.reveal`）交给它应答。
+ * `emit` 由执行器自己处理，不交给宿主。实现有本地模拟网关（`createLocalGateway`）与夹具回放。
+ * 出站主机范围由调用方事先从连接器描述算好（`hosts` ∪ `url` 配置项的主机），交给本地网关。
+ * `call` 抛出的错误回给 guest 作为宿主调用失败（`code` 取错误的 `code`）；抛 `LocalRunError('DB_DRIVER_MISSING')` 时整次运行以该码结束。
+ */
+export interface LocalHost {
+  call(method: HostMethod, payload: unknown): Promise<unknown>;
+  close(): Promise<void>;
+  /** 可选：遮蔽文本里的 Secret 明文（执行器用它遮蔽结果里的日志与错误文案）；本地模拟网关提供。 */
+  redact?(text: string): string;
+}
+
+/** 本地运行的结果；`error` 非 null 时运行失败（code 为 guest 的失败码，或 `TIMEOUT` / `DB_DRIVER_MISSING` 等本地码）。 */
+export interface LocalRunResult {
+  records: Array<{ table: string; row: Record<string, unknown> }>;
+  removals: Array<{ table: string; key: Record<string, unknown> }>;
+  checkpoints: Array<{ seq: number; state: unknown }>;
+  logs: Array<{ at: string; level: 'info' | 'warn' | 'error'; message: string }>;
+  rejected: Array<{ requestId: string; code: string; message: string }>;
+  stopped: boolean;
+  error: { code: string; message: string; stack: string | null } | null;
+  /** 连接器操作作业的结果（文案已遮蔽）；其他作业或运行失败（`error` 非 null）时没有。 */
+  operation?: GuestOperationResult;
+  /** 建议列作业的结果；其他作业或运行失败时没有。 */
+  suggest?: SuggestedColumn[];
+}
+
+/**
+ * 执行器：同一个作业交给不同的执行方式；宿主调用一律交给传入的 host。
+ * `limit` 由执行器实现：累计记录数达到 limit 时对 `emit` 回 `{ stop: true }`，超出部分截掉。
+ */
+export interface GuestExecutor {
+  /** 执行器加载的连接器描述（便捷包装据此取凭证字段与表）。 */
+  readonly descriptor?: ConnectorDescriptor;
+  run(job: GuestJob, host: LocalHost, options?: { limit?: number; timeoutMs?: number }): Promise<LocalRunResult>;
+}
+
+export type LocalRunErrorCode = 'DB_DRIVER_MISSING' | 'HOST_DENIED' | 'TIMEOUT';
+
+/** 本地运行环境的问题（不是连接器代码的问题）。 */
+export class LocalRunError extends Error {
+  readonly code: LocalRunErrorCode;
+
+  constructor(code: LocalRunErrorCode, message: string) {
+    super(message);
+    this.name = 'LocalRunError';
+    this.code = code;
+  }
+}
+
+/**
+ * - `DESCRIPTOR_NOT_GENERATED`：没有 `.ontos/descriptor.json`（先运行 `ontos admin connector codegen`）；
+ * - `DESCRIPTOR_INVALID`：`.ontos/descriptor.json` 不是合法的连接器描述（重新运行 codegen）。
+ */
+export type SourceLoadErrorCode =
+  | 'IMPORT_FORBIDDEN' | 'PATH_ESCAPE' | 'SYMLINK' | 'MANIFEST_INVALID' | 'SYNTAX_ERROR' | 'TOO_LARGE' | 'DESCRIPTOR_NOT_GENERATED' | 'DESCRIPTOR_INVALID';
+
+/** 源码目录加载失败；`file` 为相对源码根目录的路径（与整个目录相关时为 null）。 */
+export class SourceLoadError extends Error {
+  readonly code: SourceLoadErrorCode;
+  readonly file: string | null;
+
+  constructor(code: SourceLoadErrorCode, message: string, file: string | null = null) {
+    super(message);
+    this.name = 'SourceLoadError';
+    this.code = code;
+    this.file = file;
+  }
+}