@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/runtime/protocol.ts

@@ -0,0 +1,557 @@
+/**
+ * guest 运行时与宿主（runner 执行子进程 / 父进程）之间的消息契约。
+ *
+ * 消息只用 JSON 兼容结构。子进程起来后发 `ready`，父进程回一条 `execute`；之后子进程按需发 `call`
+ * （宿主调用），父进程逐条回 `reply`；最后子进程发 `result` 或 `failure`。父进程随时可以发 `cancel`。
+ *
+ * 宿主调用的 payload 与 shared 的出站网关线协议（`EgressHttpRequest` 等）结构一致；SDK 不依赖 shared，
+ * 这里自己定义一份同形的类型。子进程里跑的是不可信代码，父进程用 `parseChildMessage` 逐字段重建消息，
+ * 不直接信任子进程产出的结构。
+ */
+import type { ColumnType, SuggestedColumn } from '../descriptor';
+
+export type HostMethod = 'http' | 'db.query' | 'db.next' | 'db.close' | 'crypto' | 'cache.get' | 'cache.set' | 'secret.reveal' | 'emit';
+
+export const HOST_METHODS: readonly HostMethod[] = Object.freeze([
+  'http', 'db.query', 'db.next', 'db.close', 'crypto', 'cache.get', 'cache.set', 'secret.reveal', 'emit',
+]);
+
+/**
+ * 本次运行的生效限流（连接器描述与连接覆盖取小），由宿主放进作业；guest 用 `concurrency` 收紧 `ctx.map` 的并发。
+ * 不给时只按描述的 `rateLimit`。
+ */
+export interface JobRateLimit { perSecond: number; concurrency: number }
+
+export interface GuestPushRequest {
+  requestId: string;
+  push: string;
+  receivedAt: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+export type GuestOperationPhase = 'run' | 'lookup' | 'simulate';
+
+/**
+ * 连接器操作作业：`phase` 为 `run` 时调 `run`，`lookup` 时调 `lookup`，`simulate` 时调 `simulate`（纯函数，期间不允许任何宿主调用）。
+ * `idempotencyKey` 只透传给 `run` / `lookup`。
+ */
+export type GuestOperationJob = {
+  kind: 'operation'; phase: GuestOperationPhase;
+  config: Record<string, unknown>; secretFields: string[];
+  operation: string; params: Record<string, unknown>; idempotencyKey: string;
+  rateLimit?: JobRateLimit;
+};
+
+/**
+ * 作业（guest 在执行任何作业前按连接器描述核对实现，不一致时以 `CONNECTOR_LOAD_FAILED` 失败）：
+ * - `operation`：见 `GuestOperationJob`，结果总是 `GuestOperationResult`（失败也走 `result`，只有加载失败走 `failure`）；
+ * - `check`：只跑连接器的 `check`（没有时直接成功），结果 `{ kind: 'check'; ok: true; logs }`；
+ * - `pull`：`tables` 是该数据流在本次运行生效的表（宿主取描述里该数据流的表），`emit` 的表必须在其中；
+ * - `suggest`：调该数据流的 `suggestColumns(ctx, { table })`，结果 `{ kind: 'suggest'; columns; logs }`，
+ *   返回值不合法时以 `SUGGEST_INVALID` 失败；`table` 必须是该数据流的可扩展表。
+ */
+export type GuestJob =
+  | { kind: 'push'; config: Record<string, unknown>; secretFields: string[]; requests: GuestPushRequest[] }
+  | { kind: 'check'; config: Record<string, unknown>; secretFields: string[]; rateLimit?: JobRateLimit }
+  | {
+    kind: 'pull'; config: Record<string, unknown>; secretFields: string[];
+    stream: string; mode: 'full' | 'incremental'; state: unknown; streamConfig: Record<string, unknown>; tables: string[];
+    rateLimit?: JobRateLimit;
+  }
+  | { kind: 'suggest'; config: Record<string, unknown>; secretFields: string[]; stream: string; table: string; rateLimit?: JobRateLimit }
+  | GuestOperationJob;
+
+export interface HostCallError {
+  code: string;
+  message: string;
+  status?: number;
+  retryAfterMs?: number;
+}
+
+export type ParentMessage =
+  | { type: 'execute'; guest: string; code: string; expect: { name: string; version: string }; job: GuestJob }
+  | { type: 'reply'; id: number; ok: true; value: unknown }
+  | { type: 'reply'; id: number; ok: false; error: HostCallError }
+  | { type: 'cancel' };
+
+export interface GuestLog {
+  at: string;
+  level: 'info' | 'warn' | 'error';
+  message: string;
+  requestId?: string;
+}
+
+/** 与 shared 的 `RunnerPushResult` 同形。 */
+export interface GuestPushResult {
+  kind: 'push';
+  records: Array<{ requestId: string; table: string; row: Record<string, unknown> }>;
+  removals: Array<{ requestId: string; table: string; key: Record<string, unknown> }>;
+  rejected: Array<{ requestId: string; code: string; message: string }>;
+  logs: GuestLog[];
+}
+
+/** `notImplemented` 只在操作没有实现 `lookup` 时出现。 */
+export type LookupAnswer = { status: 'applied'; output: Record<string, unknown> } | { status: 'not_applied' } | { status: 'unknown'; notImplemented?: true };
+
+/** 连接器操作失败的码：外部系统拒绝、结果不明、guest 通用失败码，以及入参 / 输出不符合声明。 */
+export type GuestOperationFailureCode = 'REJECTED' | 'INDETERMINATE' | GuestFailureCode | 'INPUT_INVALID' | 'OUTPUT_INVALID';
+
+/**
+ * 连接器操作的结果。`ok: false` 时 `external` 只在 `REJECTED` 时出现（外部系统的业务码与文案）。
+ * `simulate` 阶段没有声明 `simulate` 时为 `ok: false, code: 'FATAL_ERROR'`，宿主据此回退缺省结果。
+ */
+export type GuestOperationResult = (
+  | { kind: 'operation'; phase: 'run'; ok: true; output: Record<string, unknown> }
+  | { kind: 'operation'; phase: 'lookup'; ok: true; lookup: LookupAnswer }
+  | { kind: 'operation'; phase: 'simulate'; ok: true; output: Record<string, unknown> }
+  | { kind: 'operation'; phase: GuestOperationPhase; ok: false; code: GuestOperationFailureCode; message: string; external?: { code?: string; message: string } }
+) & { logs: GuestLog[] };
+
+/** `pull` 的 `stopped: true`：某次 `emit` 的回复带 `{ stop: true }`，guest 触发 `ctx.signal` 后正常结束（不是 `CANCELED`）。 */
+export type GuestResult =
+  | GuestPushResult
+  | { kind: 'check'; ok: true; logs: GuestLog[] }
+  | { kind: 'suggest'; columns: SuggestedColumn[]; logs: GuestLog[] }
+  | { kind: 'pull'; emittedBatches: number; stopped?: boolean; logs: GuestLog[] }
+  | GuestOperationResult;
+
+/**
+ * - `CONNECTOR_LOOKUP_REQUIRED`：加载时发现 `idempotency: unsupported` 的连接器操作没有实现 `lookup`；
+ * - `SUGGEST_INVALID`：`suggestColumns` 返回了不合法的列（列名、类型或结构）。
+ */
+export type GuestFailureCode =
+  | 'CONNECTOR_LOAD_FAILED' | 'CONNECTOR_LOOKUP_REQUIRED' | 'CONFIG_INVALID' | 'SCHEMA_ERROR' | 'FATAL_ERROR' | 'AUTH_ERROR' | 'TRANSIENT_ERROR' | 'PUSH_UNKNOWN'
+  | 'SUGGEST_INVALID' | 'CANCELED';
+
+export const GUEST_FAILURE_CODES: readonly GuestFailureCode[] = Object.freeze([
+  'CONNECTOR_LOAD_FAILED', 'CONNECTOR_LOOKUP_REQUIRED', 'CONFIG_INVALID', 'SCHEMA_ERROR', 'FATAL_ERROR', 'AUTH_ERROR', 'TRANSIENT_ERROR', 'PUSH_UNKNOWN',
+  'SUGGEST_INVALID', 'CANCELED',
+]);
+
+export const GUEST_OPERATION_FAILURE_CODES: readonly GuestOperationFailureCode[] = Object.freeze([
+  'REJECTED', 'INDETERMINATE', ...GUEST_FAILURE_CODES, 'INPUT_INVALID', 'OUTPUT_INVALID',
+]);
+
+export type ChildMessage =
+  | { type: 'ready' }
+  | { type: 'call'; id: number; method: HostMethod; payload: unknown }
+  | { type: 'result'; result: GuestResult }
+  | { type: 'failure'; code: GuestFailureCode; message: string; stack?: string; logs: GuestLog[] };
+
+// ---------------------------------------------------------------------------
+// 宿主调用的 payload 与回复（与 shared 的出站网关线协议同形）
+
+export interface EgressHttpRequest {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+  url: string;
+  headers: Record<string, string>;
+  query: Record<string, string | string[]>;
+  body: string | null;
+  bodyEncoding: 'utf8' | 'base64';
+  timeoutMs?: number;
+}
+export interface EgressHttpResponse { status: number; url: string; headers: Record<string, string>; body: string; bodyEncoding: 'utf8' | 'base64' }
+export interface DbQueryRequest { sql: string; params: unknown[] }
+export interface DbQueryResponse { cursorId: string | null; fields: Array<{ name: string; dataTypeId: number }>; rows: Array<Record<string, unknown>>; done: boolean }
+export interface DbCursorRequest { cursorId: string }
+export interface DbNextResponse { rows: Array<Record<string, unknown>>; done: boolean }
+export type CryptoRequest =
+  | { op: 'hmac'; algorithm: 'sha1' | 'sha256' | 'sha512'; key: string; data: string; encoding: 'hex' | 'base64' }
+  | { op: 'sign'; algorithm: 'rsa-sha256'; key: string; data: string; encoding: 'hex' | 'base64' }
+  | { op: 'hash'; algorithm: 'md5' | 'sha1' | 'sha256' | 'sha512'; data: string; encoding: 'hex' | 'base64' };
+export interface CryptoResponse { value: string }
+export interface CacheGetRequest { key: string }
+export interface CacheEntry { value: string; expiresAt: string }
+export interface CacheSetRequest { key: string; value: string; ttlSeconds: number }
+export interface SecretRevealRequest { field: string }
+export interface SecretRevealResponse { value: string }
+/** `emit` 宿主调用的回复：`stop: true` 时 guest 不再发 `emit`，以 `stopped: true` 结束。其余字段（seq 等）guest 不看。 */
+export interface EmitReply {
+  stop?: boolean;
+}
+
+/** `emit` 的 payload：与 shared 的 `RunnerPullBatch` 去掉 `seq` 后同形；`seq` 由宿主编号。 */
+export interface GuestPullBatch {
+  records: Array<{ table: string; row: Record<string, unknown> }>;
+  removals: Array<{ table: string; key: Record<string, unknown> }>;
+  checkpoint?: { state: unknown };
+  logs: GuestLog[];
+  /** 自上一批以来丢弃的超大记录 / 删除标记条数；为 0 时不带。 */
+  dropped?: number;
+}
+
+// ---------------------------------------------------------------------------
+// 解析
+
+const HTTP_METHODS: ReadonlySet<string> = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']);
+const BODY_ENCODINGS: ReadonlySet<string> = new Set(['utf8', 'base64']);
+const DIGEST_ENCODINGS: ReadonlySet<string> = new Set(['hex', 'base64']);
+const HMAC_ALGORITHMS: ReadonlySet<string> = new Set(['sha1', 'sha256', 'sha512']);
+const HASH_ALGORITHMS: ReadonlySet<string> = new Set(['md5', 'sha1', 'sha256', 'sha512']);
+const LOG_LEVELS: ReadonlySet<string> = new Set(['info', 'warn', 'error']);
+const SYNC_MODES: ReadonlySet<string> = new Set(['full', 'incremental']);
+const COLUMN_TYPES: ReadonlySet<string> = new Set<ColumnType>(['string', 'integer', 'decimal', 'boolean', 'date', 'instant', 'json']);
+const HOST_METHOD_SET: ReadonlySet<string> = new Set(HOST_METHODS);
+const FAILURE_CODE_SET: ReadonlySet<string> = new Set(GUEST_FAILURE_CODES);
+const OPERATION_PHASES: ReadonlySet<string> = new Set(['run', 'lookup', 'simulate']);
+const OPERATION_FAILURE_CODE_SET: ReadonlySet<string> = new Set(GUEST_OPERATION_FAILURE_CODES);
+
+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');
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every((item) => typeof item === 'string');
+}
+
+function isId(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+function parsePushRequest(value: unknown): GuestPushRequest | null {
+  if (!isRecord(value)) return null;
+  const { requestId, push, receivedAt, headers, body } = value;
+  if (typeof requestId !== 'string' || typeof push !== 'string' || typeof receivedAt !== 'string' || !isStringRecord(headers) || typeof body !== 'string') return null;
+  return { requestId, push, receivedAt, headers: { ...headers }, body };
+}
+
+/** 作业里的生效限流：不给为 undefined；给了但不合法为 null。 */
+function parseRateLimit(value: unknown): JobRateLimit | undefined | null {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) return null;
+  const { perSecond, concurrency } = value;
+  if (typeof perSecond !== 'number' || !Number.isFinite(perSecond) || perSecond <= 0) return null;
+  if (typeof concurrency !== 'number' || !Number.isSafeInteger(concurrency) || concurrency < 1) return null;
+  return { perSecond, concurrency };
+}
+
+function parseJob(value: unknown): GuestJob | null {
+  if (!isRecord(value) || !isRecord(value.config) || !isStringArray(value.secretFields)) return null;
+  const config = value.config;
+  const secretFields = [...value.secretFields];
+  if (value.kind === 'push') {
+    if (!Array.isArray(value.requests)) return null;
+    const requests: GuestPushRequest[] = [];
+    for (const item of value.requests) {
+      const request = parsePushRequest(item);
+      if (!request) return null;
+      requests.push(request);
+    }
+    return { kind: 'push', config, secretFields, requests };
+  }
+  const rateLimit = parseRateLimit(value.rateLimit);
+  if (rateLimit === null) return null;
+  const limit = rateLimit ? { rateLimit } : {};
+  if (value.kind === 'check') return { kind: 'check', config, secretFields, ...limit };
+  if (value.kind === 'pull') {
+    const { stream, mode, streamConfig, tables } = value;
+    if (typeof stream !== 'string' || typeof mode !== 'string' || !SYNC_MODES.has(mode) || !isRecord(streamConfig) || !isStringArray(tables)) return null;
+    return { kind: 'pull', config, secretFields, stream, mode: mode as 'full' | 'incremental', state: value.state, streamConfig, tables: [...tables], ...limit };
+  }
+  if (value.kind === 'suggest') {
+    const { stream, table } = value;
+    if (typeof stream !== 'string' || typeof table !== 'string') return null;
+    return { kind: 'suggest', config, secretFields, stream, table, ...limit };
+  }
+  if (value.kind === 'operation') {
+    const { phase, operation, params, idempotencyKey } = value;
+    if (typeof phase !== 'string' || !OPERATION_PHASES.has(phase) || typeof operation !== 'string' || !isRecord(params) || typeof idempotencyKey !== 'string') return null;
+    return { kind: 'operation', phase: phase as GuestOperationPhase, config, secretFields, operation, params, idempotencyKey, ...limit };
+  }
+  return null;
+}
+
+function parseHostError(value: unknown): HostCallError | null {
+  if (!isRecord(value) || typeof value.code !== 'string' || typeof value.message !== 'string') return null;
+  const error: HostCallError = { code: value.code, message: value.message };
+  if (value.status !== undefined) {
+    if (typeof value.status !== 'number' || !Number.isInteger(value.status)) return null;
+    error.status = value.status;
+  }
+  if (value.retryAfterMs !== undefined) {
+    if (typeof value.retryAfterMs !== 'number' || !Number.isFinite(value.retryAfterMs) || value.retryAfterMs < 0) return null;
+    error.retryAfterMs = value.retryAfterMs;
+  }
+  return error;
+}
+
+/** 解析父进程消息（子进程侧）；结构不合法时返回 null。 */
+export function parseParentMessage(value: unknown): ParentMessage | null {
+  if (!isRecord(value)) return null;
+  switch (value.type) {
+    case 'execute': {
+      const { guest, code, expect } = value;
+      if (typeof guest !== 'string' || typeof code !== 'string') return null;
+      if (!isRecord(expect) || typeof expect.name !== 'string' || typeof expect.version !== 'string') return null;
+      const job = parseJob(value.job);
+      return job ? { type: 'execute', guest, code, expect: { name: expect.name, version: expect.version }, job } : null;
+    }
+    case 'reply': {
+      if (!isId(value.id)) return null;
+      if (value.ok === true) return { type: 'reply', id: value.id, ok: true, value: value.value };
+      if (value.ok !== false) return null;
+      const error = parseHostError(value.error);
+      return error ? { type: 'reply', id: value.id, ok: false, error } : null;
+    }
+    case 'cancel':
+      return { type: 'cancel' };
+    default:
+      return null;
+  }
+}
+
+function parseLogs(value: unknown): GuestLog[] | null {
+  if (!Array.isArray(value)) return null;
+  const logs: GuestLog[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry) || typeof entry.at !== 'string' || typeof entry.level !== 'string' || !LOG_LEVELS.has(entry.level) || typeof entry.message !== 'string') return null;
+    if (entry.requestId !== undefined && typeof entry.requestId !== 'string') return null;
+    logs.push({
+      at: entry.at,
+      level: entry.level as GuestLog['level'],
+      message: entry.message,
+      ...(entry.requestId !== undefined ? { requestId: entry.requestId } : {}),
+    });
+  }
+  return logs;
+}
+
+function parsePushResult(value: Record<string, unknown>, requestIds: ReadonlySet<string>): GuestPushResult | null {
+  const { records, removals, rejected } = value;
+  if (!Array.isArray(records) || !Array.isArray(removals) || !Array.isArray(rejected)) return null;
+  const logs = parseLogs(value.logs);
+  if (!logs) return null;
+  const result: GuestPushResult = { kind: 'push', records: [], removals: [], rejected: [], logs };
+  for (const item of records) {
+    if (!isRecord(item) || typeof item.requestId !== 'string' || !requestIds.has(item.requestId)) return null;
+    if (typeof item.table !== 'string' || !isRecord(item.row)) return null;
+    result.records.push({ requestId: item.requestId, table: item.table, row: item.row });
+  }
+  for (const item of removals) {
+    if (!isRecord(item) || typeof item.requestId !== 'string' || !requestIds.has(item.requestId)) return null;
+    if (typeof item.table !== 'string' || !isRecord(item.key)) return null;
+    result.removals.push({ requestId: item.requestId, table: item.table, key: item.key });
+  }
+  for (const item of rejected) {
+    if (!isRecord(item) || typeof item.requestId !== 'string' || !requestIds.has(item.requestId)) return null;
+    if (typeof item.code !== 'string' || typeof item.message !== 'string') return null;
+    result.rejected.push({ requestId: item.requestId, code: item.code, message: item.message });
+  }
+  return result;
+}
+
+function parseResult(value: unknown, job: GuestJob): GuestResult | null {
+  if (!isRecord(value) || value.kind !== job.kind) return null;
+  if (job.kind === 'push') return parsePushResult(value, new Set(job.requests.map((request) => request.requestId)));
+  const logs = parseLogs(value.logs);
+  if (!logs) return null;
+  if (job.kind === 'operation') return parseOperationResult(value, job, logs);
+  if (job.kind === 'suggest') {
+    const columns = parseSuggestedColumns(value.columns);
+    return columns ? { kind: 'suggest', columns, logs } : null;
+  }
+  if (job.kind === 'check') return value.ok === true ? { kind: 'check', ok: true, logs } : null;
+  const emittedBatches = value.emittedBatches;
+  if (typeof emittedBatches !== 'number' || !Number.isSafeInteger(emittedBatches) || emittedBatches < 0) return null;
+  if (value.stopped !== undefined && typeof value.stopped !== 'boolean') return null;
+  return { kind: 'pull', emittedBatches, ...(value.stopped === true ? { stopped: true } : {}), logs };
+}
+
+function parseExternal(value: unknown): { code?: string; message: string } | null {
+  if (!isRecord(value) || typeof value.message !== 'string') return null;
+  if (value.code !== undefined && typeof value.code !== 'string') return null;
+  return { message: value.message, ...(value.code !== undefined ? { code: value.code } : {}) };
+}
+
+function parseLookupAnswer(value: unknown): LookupAnswer | null {
+  if (!isRecord(value)) return null;
+  if (value.status === 'applied') return isRecord(value.output) ? { status: 'applied', output: value.output } : null;
+  if (value.status === 'not_applied') return { status: 'not_applied' };
+  if (value.status === 'unknown') return value.notImplemented === true ? { status: 'unknown', notImplemented: true } : { status: 'unknown' };
+  return null;
+}
+
+/** 操作结果的阶段必须与作业一致。 */
+function parseOperationResult(value: Record<string, unknown>, job: GuestOperationJob, logs: GuestLog[]): GuestOperationResult | null {
+  if (value.phase !== job.phase) return null;
+  const phase = job.phase;
+  if (value.ok === false) {
+    if (typeof value.code !== 'string' || !OPERATION_FAILURE_CODE_SET.has(value.code) || typeof value.message !== 'string') return null;
+    let external: { code?: string; message: string } | undefined;
+    if (value.external !== undefined) {
+      const parsed = parseExternal(value.external);
+      if (!parsed) return null;
+      external = parsed;
+    }
+    return { kind: 'operation', phase, ok: false, code: value.code as GuestOperationFailureCode, message: value.message, ...(external ? { external } : {}), logs };
+  }
+  if (value.ok !== true) return null;
+  if (phase === 'lookup') {
+    const lookup = parseLookupAnswer(value.lookup);
+    return lookup ? { kind: 'operation', phase, ok: true, lookup, logs } : null;
+  }
+  if (!isRecord(value.output)) return null;
+  return phase === 'run'
+    ? { kind: 'operation', phase: 'run', ok: true, output: value.output, logs }
+    : { kind: 'operation', phase: 'simulate', ok: true, output: value.output, logs };
+}
+
+/** 只做结构重建；列名与类型的规则 guest 已按 `validateSuggestedColumns` 检查过，宿主写库前另按 shared 的规则再校验。 */
+function parseSuggestedColumns(value: unknown): SuggestedColumn[] | null {
+  if (!Array.isArray(value)) return null;
+  const columns: SuggestedColumn[] = [];
+  for (const item of value) {
+    if (!isRecord(item) || typeof item.name !== 'string' || typeof item.type !== 'string' || !COLUMN_TYPES.has(item.type) || typeof item.title !== 'string') return null;
+    const { precision, scale, description } = item;
+    if (precision !== undefined && (typeof precision !== 'number' || !Number.isSafeInteger(precision))) return null;
+    if (scale !== undefined && (typeof scale !== 'number' || !Number.isSafeInteger(scale))) return null;
+    if (description !== undefined && typeof description !== 'string') return null;
+    columns.push({
+      name: item.name, type: item.type as ColumnType, title: item.title,
+      ...(precision !== undefined ? { precision } : {}), ...(scale !== undefined ? { scale } : {}), ...(description !== undefined ? { description } : {}),
+    });
+  }
+  return columns;
+}
+
+function parseBatch(value: unknown, tables: ReadonlySet<string>): GuestPullBatch | null {
+  if (!isRecord(value) || !Array.isArray(value.records) || !Array.isArray(value.removals)) return null;
+  const logs = parseLogs(value.logs);
+  if (!logs) return null;
+  const batch: GuestPullBatch = { records: [], removals: [], logs };
+  for (const item of value.records) {
+    if (!isRecord(item) || typeof item.table !== 'string' || !tables.has(item.table) || !isRecord(item.row)) return null;
+    batch.records.push({ table: item.table, row: item.row });
+  }
+  for (const item of value.removals) {
+    if (!isRecord(item) || typeof item.table !== 'string' || !tables.has(item.table) || !isRecord(item.key)) return null;
+    batch.removals.push({ table: item.table, key: item.key });
+  }
+  if (value.checkpoint !== undefined) {
+    if (!isRecord(value.checkpoint) || !Object.hasOwn(value.checkpoint, 'state')) return null;
+    batch.checkpoint = { state: value.checkpoint.state };
+  }
+  if (value.dropped !== undefined) {
+    if (typeof value.dropped !== 'number' || !Number.isSafeInteger(value.dropped) || value.dropped < 0) return null;
+    batch.dropped = value.dropped;
+  }
+  return batch;
+}
+
+function parseHttpRequest(value: unknown): EgressHttpRequest | null {
+  if (!isRecord(value)) return null;
+  const { method, url, headers, query, body, bodyEncoding, timeoutMs } = value;
+  if (typeof method !== 'string' || !HTTP_METHODS.has(method) || typeof url !== 'string' || !isStringRecord(headers)) return null;
+  if (!isRecord(query) || !Object.values(query).every((item) => typeof item === 'string' || isStringArray(item))) return null;
+  if (body !== null && typeof body !== 'string') return null;
+  if (typeof bodyEncoding !== 'string' || !BODY_ENCODINGS.has(bodyEncoding)) return null;
+  if (timeoutMs !== undefined && (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0)) return null;
+  const parsedQuery: Record<string, string | string[]> = {};
+  for (const [key, item] of Object.entries(query)) parsedQuery[key] = Array.isArray(item) ? [...(item as string[])] : item as string;
+  return {
+    method: method as EgressHttpRequest['method'], url, headers: { ...headers }, query: parsedQuery, body,
+    bodyEncoding: bodyEncoding as EgressHttpRequest['bodyEncoding'], ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+  };
+}
+
+function parseCryptoRequest(value: unknown): CryptoRequest | null {
+  if (!isRecord(value) || typeof value.data !== 'string' || typeof value.algorithm !== 'string') return null;
+  if (typeof value.encoding !== 'string' || !DIGEST_ENCODINGS.has(value.encoding)) return null;
+  const { data, algorithm } = value;
+  const encoding = value.encoding as 'hex' | 'base64';
+  if (value.op === 'hash') {
+    return HASH_ALGORITHMS.has(algorithm) ? { op: 'hash', algorithm: algorithm as 'md5' | 'sha1' | 'sha256' | 'sha512', data, encoding } : null;
+  }
+  if (typeof value.key !== 'string') return null;
+  if (value.op === 'hmac') {
+    return HMAC_ALGORITHMS.has(algorithm) ? { op: 'hmac', algorithm: algorithm as 'sha1' | 'sha256' | 'sha512', key: value.key, data, encoding } : null;
+  }
+  if (value.op === 'sign') return algorithm === 'rsa-sha256' ? { op: 'sign', algorithm: 'rsa-sha256', key: value.key, data, encoding } : null;
+  return null;
+}
+
+/** 连接器操作作业能用的宿主方法：`simulate` 一个都不能用（纯函数），其余阶段没有 `db.*`、`emit`。 */
+const OPERATION_HOST_METHODS: ReadonlySet<HostMethod> = new Set<HostMethod>(['http', 'crypto', 'cache.get', 'cache.set', 'secret.reveal']);
+
+function parsePayload(method: HostMethod, payload: unknown, job: GuestJob): unknown {
+  if (job.kind === 'operation' && (job.phase === 'simulate' || !OPERATION_HOST_METHODS.has(method))) return null;
+  switch (method) {
+    case 'http':
+      return parseHttpRequest(payload);
+    case 'db.query':
+      return isRecord(payload) && typeof payload.sql === 'string' && Array.isArray(payload.params) ? { sql: payload.sql, params: [...payload.params] } : null;
+    case 'db.next':
+    case 'db.close':
+      return isRecord(payload) && typeof payload.cursorId === 'string' ? { cursorId: payload.cursorId } : null;
+    case 'crypto':
+      return parseCryptoRequest(payload);
+    case 'cache.get':
+      return isRecord(payload) && typeof payload.key === 'string' ? { key: payload.key } : null;
+    case 'cache.set': {
+      if (!isRecord(payload) || typeof payload.key !== 'string' || typeof payload.value !== 'string') return null;
+      const ttl = payload.ttlSeconds;
+      return typeof ttl === 'number' && Number.isSafeInteger(ttl) && ttl > 0 ? { key: payload.key, value: payload.value, ttlSeconds: ttl } : null;
+    }
+    case 'secret.reveal':
+      return isRecord(payload) && typeof payload.field === 'string' && job.secretFields.includes(payload.field) ? { field: payload.field } : null;
+    case 'emit':
+      return job.kind === 'pull' ? parseBatch(payload, new Set(job.tables)) : null;
+  }
+}
+
+/**
+ * `parseChildMessage` 拒绝一条 `emit` 时用来区分原因：记录或删除标记落在作业没声明的表上时返回第一张这样的表名，
+ * 宿主据此按 `SCHEMA_ERROR` 结束运行（与 guest 自己检查到时同一个错误码），而不是按子进程崩溃处理；其他情况返回 null。
+ */
+export function undeclaredEmitTable(value: unknown, job: GuestJob): string | null {
+  if (job.kind !== 'pull' || !isRecord(value) || value.type !== 'call' || value.method !== 'emit' || !isRecord(value.payload)) return null;
+  const allowed = new Set(job.tables);
+  for (const key of ['records', 'removals'] as const) {
+    const items = value.payload[key];
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      if (isRecord(item) && typeof item.table === 'string' && !allowed.has(item.table)) return item.table;
+    }
+  }
+  return null;
+}
+
+/**
+ * 解析子进程消息（父进程侧）并重建一份干净的对象；结构不合法时返回 null（父进程按崩溃处理）。
+ * 宿主调用的 payload 按方法校验：`emit` 只出现在 pull 作业且表必须在 `job.tables` 里，
+ * `secret.reveal` 的字段必须在 `job.secretFields` 里；结果的 `kind` 必须与作业一致。
+ */
+export function parseChildMessage(value: unknown, job: GuestJob): ChildMessage | null {
+  if (!isRecord(value)) return null;
+  switch (value.type) {
+    case 'ready':
+      return { type: 'ready' };
+    case 'call': {
+      if (!isId(value.id) || typeof value.method !== 'string' || !HOST_METHOD_SET.has(value.method)) return null;
+      const method = value.method as HostMethod;
+      const payload = parsePayload(method, value.payload, job);
+      return payload === null ? null : { type: 'call', id: value.id, method, payload };
+    }
+    case 'result': {
+      const result = parseResult(value.result, job);
+      return result ? { type: 'result', result } : null;
+    }
+    case 'failure': {
+      if (typeof value.code !== 'string' || !FAILURE_CODE_SET.has(value.code) || typeof value.message !== 'string') return null;
+      if (value.stack !== undefined && typeof value.stack !== 'string') return null;
+      const logs = parseLogs(value.logs);
+      if (!logs) return null;
+      return {
+        type: 'failure', code: value.code as GuestFailureCode, message: value.message,
+        ...(value.stack !== undefined ? { stack: value.stack } : {}), logs,
+      };
+    }
+    default:
+      return null;
+  }
+}