@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/runtime/jobs.test.ts

@@ -0,0 +1,444 @@
+/** 作业的执行：加载核对 / push / pull / suggest / check。 */
+import { describe, expect, test } from 'bun:test';
+import type { GuestPullBatch } from '../../src/runtime';
+import { configField, descriptor, push, stream, table } from '../fixtures/descriptor';
+import { checkJob, expectFailure, expectResult, pullJob, pushJob, rawConnector, runGuest, suggestJob, type RunResult } from './helpers';
+
+const ITEM = { item: table({ id: 'string' }, ['id']) };
+
+function pushConnector(handler: string): string {
+  return rawConnector(descriptor({ pushes: { default: push(ITEM) } }), `pushes: { default: definePush('default', ${handler}) },`);
+}
+
+function emits(run: RunResult): GuestPullBatch[] {
+  return run.calls.filter((entry) => entry.method === 'emit').map((entry) => entry.payload as GuestPullBatch);
+}
+
+describe('加载：实现与描述核对', () => {
+  const desc = descriptor({
+    hosts: ['a.x.com'],
+    streams: { orders: stream({ orders: table({ id: 'string' }, ['id']) }), lines: stream({ lines: table({ id: 'string' }, ['id']) }) },
+  });
+
+  test('描述有数据流 orders 而实现里没有：任一作业都 CONNECTOR_LOAD_FAILED，消息列出缺失与多余的实现', async () => {
+    const code = rawConnector(desc, `streams: { lines: defineStream('lines', async function* () {}), extra: defineStream('extra', async function* () {}) },`);
+    for (const job of [checkJob(), pullJob({ stream: 'lines', tables: ['lines'] }), pushJob([])]) {
+      const failure = expectFailure((await runGuest({ code, job })).outcome);
+      expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+      expect(failure.message).toContain('missing streams/orders');
+      expect(failure.message).toContain('extra streams/extra');
+    }
+  });
+
+  test('实现的名字与所在目录不一致时 CONNECTOR_LOAD_FAILED', async () => {
+    const code = rawConnector(desc, `streams: { orders: defineStream('lines', async function* () {}), lines: defineStream('lines', async function* () {}) },`);
+    const failure = expectFailure((await runGuest({ code, job: checkJob() })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(failure.message).toContain('streams/orders/index.ts');
+  });
+
+  test('描述要求 check 而没有实现，或没有要求却给了：CONNECTOR_LOAD_FAILED', async () => {
+    const streams = `streams: { orders: defineStream('orders', async function* () {}), lines: defineStream('lines', async function* () {}) },`;
+    const missing = expectFailure((await runGuest({ code: rawConnector({ ...desc, check: true }, streams), job: checkJob() })).outcome);
+    expect(missing.message).toContain('missing check');
+    const extra = expectFailure((await runGuest({ code: rawConnector(desc, `${streams} check: defineCheck(() => {}),`), job: checkJob() })).outcome);
+    expect(extra.message).toContain('extra check');
+  });
+
+  test('产物的名字或版本与期望不同时 CONNECTOR_LOAD_FAILED', async () => {
+    const code = rawConnector(descriptor({ version: '2.0.0', pushes: { default: push(ITEM) } }), `pushes: { default: definePush('default', { map() {} }) },`);
+    const failure = expectFailure((await runGuest({ code, job: pushJob([]) })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(failure.message).toContain('demo@2.0.0');
+  });
+
+  test('产物没有导出 descriptor 时 CONNECTOR_LOAD_FAILED', async () => {
+    const failure = expectFailure((await runGuest({ code: 'module.exports = { implementations: {} };', job: checkJob() })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+  });
+});
+
+describe('push 作业', () => {
+  test('推送名不在描述里的请求拒收 PUSH_UNKNOWN，其余照常产出', async () => {
+    const code = pushConnector(`{ map(ctx, req) { ctx.record('item', req.json()); } }`);
+    const run = await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{"id":"a"}' }, { requestId: 'r2', push: 'orders', body: '{"id":"b"}' }]) });
+    const result = expectResult(run.outcome);
+    expect(result).toMatchObject({
+      kind: 'push',
+      records: [{ requestId: 'r1', table: 'item', row: { id: 'a' } }],
+      rejected: [{ requestId: 'r2', code: 'PUSH_UNKNOWN' }],
+    });
+  });
+
+  test('先 verify 再 map；单条请求失败只拒收该条并丢弃其记录；请求结束后 ctx 不可用', async () => {
+    const code = pushConnector(`{
+      verify(ctx, req) { ctx.log.info('verify ' + req.id); if (req.body === 'bad-sign') throw new errors.RejectedPayload('signature mismatch'); },
+      map(ctx, req) {
+        ctx.log.info('map ' + req.id);
+        if (req.body === 'keep') { globalThis.kept = ctx; return; }
+        ctx.record('item', { id: req.id });
+        if (req.body === 'boom') throw new Error('plain failure');
+        let late = 'none';
+        try { globalThis.kept.record('item', { id: 'late' }); } catch (e) { late = e.name; }
+        ctx.remove('item', { id: req.id + '-old', late });
+      },
+    }`);
+    const run = await runGuest({ code, job: pushJob([
+      { requestId: 'r1', body: 'keep' }, { requestId: 'r2', body: 'bad-sign' }, { requestId: 'r3', body: 'boom' }, { requestId: 'r4', body: 'ok' },
+    ]) });
+    const result = expectResult(run.outcome);
+    if (result.kind !== 'push') throw new Error('expected push');
+    expect(result.records).toEqual([{ requestId: 'r4', table: 'item', row: { id: 'r4' } }]);
+    expect(result.removals).toEqual([{ requestId: 'r4', table: 'item', key: { id: 'r4-old', late: 'TypeError' } }]);
+    expect(result.rejected).toEqual([
+      { requestId: 'r2', code: 'REJECTED_PAYLOAD', message: 'signature mismatch' },
+      { requestId: 'r3', code: 'CONNECTOR_ERROR', message: 'plain failure' },
+    ]);
+    expect(result.logs.map((log) => `${log.requestId}:${log.message}`)).toEqual([
+      'r1:verify r1', 'r1:map r1', 'r2:verify r2', 'r3:verify r3', 'r3:map r3', 'r4:verify r4', 'r4:map r4',
+    ]);
+  });
+
+  test('SCHEMA_ERROR / FATAL_ERROR 让整次失败', async () => {
+    for (const kind of ['SchemaError', 'FatalError']) {
+      const code = pushConnector(`{ map() { throw new errors.${kind}('stop'); } }`);
+      const failure = expectFailure((await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }]) })).outcome);
+      expect(failure).toMatchObject({ code: kind === 'SchemaError' ? 'SCHEMA_ERROR' : 'FATAL_ERROR', message: 'stop' });
+    }
+  });
+
+  test('没有推送的连接器做推送作业时加载失败', async () => {
+    const code = rawConnector(descriptor({ hosts: ['a.x.com'], streams: { items: stream(ITEM) } }), `streams: { items: defineStream('items', async function* () {}) },`);
+    expect(expectFailure((await runGuest({ code, job: pushJob([]) })).outcome).code).toBe('CONNECTOR_LOAD_FAILED');
+  });
+
+  test('记录写了不属于该推送的字段：照常交给宿主（由宿主丢弃）', async () => {
+    const code = pushConnector(`{ map(ctx, req) { ctx.record('item', { id: req.id, foo: 1 }); } }`);
+    const result = expectResult((await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }]) })).outcome);
+    expect(result).toMatchObject({ kind: 'push', records: [{ requestId: 'r1', table: 'item', row: { id: 'r1', foo: 1 } }] });
+  });
+});
+
+describe('pull 作业', () => {
+  const desc = descriptor({
+    hosts: ['a.x.com'],
+    streams: { items: stream({ item: table({ id: 'integer' }, ['id']), line: table({ id: 'integer' }, ['id']) }) },
+  });
+  function streamConnector(body: string): string {
+    return rawConnector(desc, `streams: { items: defineStream('items', async function* (ctx, input) { ${body} }) },`);
+  }
+
+  test('2500 条记录加 1 个断点：3 次 emit（1000、1000、500），断点附在最后一批，每次等回复后才继续', async () => {
+    const code = streamConnector(`
+      ctx.log.info('start ' + input.mode + ' ' + JSON.stringify(input.state) + ' ' + input.streamConfig.org);
+      for (let i = 0; i < 2500; i += 1) yield ctx.record('item', { id: i });
+      yield ctx.checkpoint({ cursor: 2500 });`);
+    let inFlight = false;
+    let overlapped = false;
+    const run = await runGuest({
+      code, job: pullJob({ mode: 'incremental', state: { cursor: 0 }, streamConfig: { org: 'o1' }, tables: ['item', 'line'] }),
+      host: {
+        emit: async () => {
+          if (inFlight) overlapped = true;
+          inFlight = true;
+          await Bun.sleep(20);
+          inFlight = false;
+          return { seq: 0, duplicate: false, rejected: 0 };
+        },
+      },
+    });
+    const result = expectResult(run.outcome);
+    const batches = emits(run);
+    expect(batches.map((batch) => batch.records.length)).toEqual([1000, 1000, 500]);
+    expect(batches.map((batch) => batch.checkpoint)).toEqual([undefined, undefined, { state: { cursor: 2500 } }]);
+    expect(batches[0]?.logs.map((log) => log.message)).toEqual(['start incremental {"cursor":0} o1']);
+    expect(batches[2]?.records[499]).toEqual({ table: 'item', row: { id: 2499 } });
+    expect(overlapped).toBe(false);
+    expect(result).toEqual({ kind: 'pull', emittedBatches: 3, logs: [] });
+    // emit 之后才发 result
+    expect(run.messages.at(-1)?.type).toBe('result');
+  });
+
+  test('断点立即连同之前的记录发出：3 页各 5 条、每页一个断点 → 3 批；之后抛错只丢断点之后的记录', async () => {
+    const code = streamConnector(`
+      for (let page = 1; page <= 3; page += 1) {
+        for (let i = 0; i < 5; i += 1) yield ctx.record('item', { id: page * 10 + i });
+        yield ctx.checkpoint({ page });
+      }
+      yield ctx.record('item', { id: 99 });
+      throw new errors.FatalError('page 4 failed');`);
+    const run = await runGuest({ code, job: pullJob(), host: { emit: () => ({ seq: 0, duplicate: false, rejected: 0 }) } });
+    expect(expectFailure(run.outcome)).toMatchObject({ code: 'FATAL_ERROR', message: 'page 4 failed' });
+    const batches = emits(run);
+    expect(batches.map((batch) => [batch.records.length, batch.checkpoint])).toEqual([
+      [5, { state: { page: 1 } }], [5, { state: { page: 2 } }], [5, { state: { page: 3 } }],
+    ]);
+  });
+
+  test('背压：emit 回复之前生成器不会继续产出', async () => {
+    const code = streamConnector(`
+      for (let i = 0; i < 1000; i += 1) yield ctx.record('item', { id: i });
+      ctx.log.info('after first batch');
+      yield ctx.record('item', { id: 1000 });`);
+    const seen: string[][] = [];
+    const run = await runGuest({ code, job: pullJob(), host: { emit: (payload) => { seen.push((payload as GuestPullBatch).logs.map((log) => log.message)); return null; } } });
+    expectResult(run.outcome);
+    expect(seen).toEqual([[], ['after first batch']]);
+  });
+
+  test('累计超过 4 MiB 而未满 1000 条时先发出这一批', async () => {
+    const code = streamConnector(`
+      const blob = 'x'.repeat(1024 * 1024);
+      for (let i = 0; i < 6; i += 1) yield ctx.record('item', { id: i, blob });`);
+    const run = await runGuest({ code, job: pullJob(), host: { emit: () => null } });
+    expectResult(run.outcome);
+    expect(emits(run).map((batch) => batch.records.map((record) => record.row.id))).toEqual([[0, 1, 2], [3, 4, 5]]);
+  });
+
+  test('批次字节数与服务端同口径：约 6 KB 的宽行与删除标记混合，每批都不超过服务端的 4 MiB 校验', async () => {
+    const MAX = 4 * 1024 * 1024;
+    const code = streamConnector(`
+      const blob = 'y'.repeat(6000);
+      for (let i = 0; i < 1500; i += 1) {
+        yield ctx.record('item', { id: i, blob });
+        if (i % 3 === 0) yield ctx.remove('line', { id: i });
+      }`);
+    const run = await runGuest({ code, job: pullJob({ tables: ['item', 'line'] }), host: { emit: () => null } });
+    expectResult(run.outcome);
+    const batches = emits(run);
+    // 服务端 runner-protocol/routes.ts 的 readBatch：Buffer.byteLength(JSON.stringify([records, removals])) ≤ 4 MiB
+    for (const batch of batches) expect(Buffer.byteLength(JSON.stringify([batch.records, batch.removals]))).toBeLessThanOrEqual(MAX);
+    expect(batches.reduce((sum, batch) => sum + batch.records.length, 0)).toBe(1500);
+    // 批次仍然尽量装满：除最后一批外，再加一条 6 KB 的记录就会超限
+    for (const batch of batches.slice(0, -1)) expect(Buffer.byteLength(JSON.stringify([batch.records, batch.removals]))).toBeGreaterThan(MAX - 6100);
+  });
+
+  test('单条超过 4 MiB 的记录按条拒收：丢弃并记 warn，其余记录照常发出，运行成功', async () => {
+    const code = streamConnector(`
+      yield ctx.record('item', { id: 1 });
+      yield ctx.record('item', { id: 2, blob: 'z'.repeat(5 * 1024 * 1024) });
+      yield ctx.remove('line', { id: 3, blob: 'z'.repeat(5 * 1024 * 1024) });
+      yield ctx.record('item', { id: 4 });`);
+    const run = await runGuest({ code, job: pullJob({ tables: ['item', 'line'] }), host: { emit: () => null } });
+    expectResult(run.outcome);
+    const batches = emits(run);
+    expect(batches.map((batch) => batch.records.map((record) => record.row.id))).toEqual([[1, 4]]);
+    expect(batches[0]?.removals).toEqual([]);
+    // 丢弃的条数随批次上报，服务端计入 stats.rejected
+    expect(batches[0]?.dropped).toBe(2);
+    const warnings = batches.flatMap((batch) => batch.logs).filter((entry) => entry.level === 'warn').map((entry) => entry.message);
+    expect(warnings).toHaveLength(2);
+    expect(warnings[0]).toContain('RECORD_TOO_LARGE');
+    expect(warnings[0]).toContain('"item"');
+    expect(warnings[1]).toContain('"line"');
+  });
+
+  test('断点之后只剩被丢弃的超大记录：仍发一批空批次上报丢弃条数', async () => {
+    const code = streamConnector(`
+      yield ctx.record('item', { id: 1 });
+      yield ctx.checkpoint({ page: 1 });
+      yield ctx.record('item', { id: 2, blob: 'z'.repeat(5 * 1024 * 1024) });`);
+    const run = await runGuest({ code, job: pullJob({ tables: ['item'] }), host: { emit: () => null } });
+    expectResult(run.outcome);
+    const batches = emits(run);
+    expect(batches).toHaveLength(2);
+    expect(batches[0]).toMatchObject({ records: [{ table: 'item', row: { id: 1 } }], checkpoint: { state: { page: 1 } } });
+    expect(batches[0]?.dropped).toBeUndefined();
+    expect(batches[1]).toMatchObject({ records: [], removals: [], dropped: 1 });
+  });
+
+  test('删除标记同样入批；记录在产出之后被改动不影响已产出的值', async () => {
+    const code = streamConnector(`
+      const row = { id: 1 };
+      yield ctx.record('item', row);
+      row.id = 2;
+      yield ctx.remove('line', { id: 9 });`);
+    const run = await runGuest({ code, job: pullJob({ tables: ['item', 'line'] }), host: { emit: () => null } });
+    expectResult(run.outcome);
+    expect(emits(run)).toEqual([{ records: [{ table: 'item', row: { id: 1 } }], removals: [{ table: 'line', key: { id: 9 } }], logs: [] }]);
+  });
+
+  test('记录落在 job.tables 以外的表时 SCHEMA_ERROR，消息带表名', async () => {
+    const code = streamConnector(`yield ctx.record('line', { id: 1 });`);
+    const failure = expectFailure((await runGuest({ code, job: pullJob({ tables: ['item'] }), host: { emit: () => null } })).outcome);
+    expect(failure.code).toBe('SCHEMA_ERROR');
+    expect(failure.message).toContain('table line');
+  });
+
+  test('生成器产出非 StreamItem 的值时 SCHEMA_ERROR', async () => {
+    for (const value of [`{ id: 1 }`, `{ __ontos: 'record', table: 'item', row: [] }`, `42`]) {
+      const failure = expectFailure((await runGuest({ code: streamConnector(`yield ${value};`), job: pullJob() })).outcome);
+      expect(failure.code).toBe('SCHEMA_ERROR');
+    }
+  });
+
+  test('未知数据流名时 CONNECTOR_LOAD_FAILED', async () => {
+    const run = await runGuest({ code: streamConnector(`yield ctx.record('item', { id: 1 });`), job: pullJob({ stream: 'missing' }) });
+    expect(expectFailure(run.outcome).code).toBe('CONNECTOR_LOAD_FAILED');
+  });
+
+  test('生成器正常结束：先发剩余记录的 emit，再发 result；只有断点也会发', async () => {
+    const run = await runGuest({ code: streamConnector(`yield ctx.record('item', { id: 1 }); ctx.log.info('done');`), job: pullJob(), host: { emit: () => null } });
+    expect(run.messages.map((message) => (message.type === 'call' ? message.method : message.type))).toEqual(['emit', 'result']);
+    expect(emits(run)[0]?.logs.map((log) => log.message)).toEqual(['done']);
+
+    const onlyCheckpoint = await runGuest({ code: streamConnector(`yield ctx.checkpoint({ at: 1 });`), job: pullJob(), host: { emit: () => null } });
+    expect(emits(onlyCheckpoint)).toEqual([{ records: [], removals: [], checkpoint: { state: { at: 1 } }, logs: [] }]);
+
+    const empty = await runGuest({ code: streamConnector(`ctx.log.info('nothing');`), job: pullJob() });
+    expect(emits(empty)).toEqual([]);
+    expect(expectResult(empty.outcome)).toMatchObject({ emittedBatches: 0, logs: [{ message: 'nothing' }] });
+  });
+
+  test('生成器抛 TransientError 时 TRANSIENT_ERROR，未发出的记录丢弃', async () => {
+    const run = await runGuest({ code: streamConnector(`yield ctx.record('item', { id: 1 }); throw new errors.TransientError('later');`), job: pullJob() });
+    expect(expectFailure(run.outcome)).toMatchObject({ code: 'TRANSIENT_ERROR', message: 'later' });
+    expect(emits(run)).toEqual([]);
+  });
+
+  test('收到 cancel 后生成器还在产出：停止拉取下一项，回 CANCELED', async () => {
+    const code = streamConnector(`
+      for (let i = 0; ; i += 1) {
+        yield ctx.record('item', { id: i });
+        if (i === 1500) globalThis.reached = true;
+      }`);
+    let pulledAfterCancel = 0;
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: {
+        emit: (_payload, host) => {
+          pulledAfterCancel += 1;
+          host.cancel();
+          return null;
+        },
+      },
+    });
+    const failure = expectFailure(run.outcome);
+    expect(failure.code).toBe('CANCELED');
+    expect(pulledAfterCancel).toBe(1);
+    expect(emits(run)).toHaveLength(1);
+  });
+
+  test('config 不符合描述的配置项时 CONFIG_INVALID，消息含配置项名', async () => {
+    const code = rawConnector({ ...desc, config: { region: configField('string') } }, `streams: { items: defineStream('items', async function* () {}) },`);
+    const failure = expectFailure((await runGuest({ code, job: pullJob({ config: { region: 1 } }) })).outcome);
+    expect(failure.code).toBe('CONFIG_INVALID');
+    expect(failure.message).toContain('region');
+  });
+
+  test('不可扩展表的记录带未声明字段 foo：照常 emit（字段由宿主丢弃），运行成功', async () => {
+    const run = await runGuest({ code: streamConnector(`yield ctx.record('item', { id: 1, foo: 'x' });`), job: pullJob(), host: { emit: () => null } });
+    expect(expectResult(run.outcome)).toMatchObject({ kind: 'pull', emittedBatches: 1 });
+    expect(emits(run)[0]?.records).toEqual([{ table: 'item', row: { id: 1, foo: 'x' } }]);
+  });
+
+  test('作业带生效限流时 ctx.map 的并发按它收紧', async () => {
+    const code = rawConnector({ ...desc, rateLimit: { perSecond: 10, concurrency: 8 } }, `streams: { items: defineStream('items', async function* (ctx) {
+      let active = 0; let peak = 0;
+      await ctx.map([1, 2, 3, 4, 5, 6], async () => { active += 1; peak = Math.max(peak, active); await new Promise((r) => r()); await ctx.cache.get('k'); active -= 1; });
+      ctx.log.info('peak ' + peak);
+    }) },`);
+    const run = await runGuest({ code, job: pullJob({ rateLimit: { perSecond: 10, concurrency: 2 } }), host: { 'cache.get': async () => { await Bun.sleep(5); return null; } } });
+    expect(expectResult(run.outcome)).toMatchObject({ logs: [{ message: 'peak 2' }] });
+  });
+});
+
+describe('pull 作业：emit 回复 stop', () => {
+  const STOP_DESC = descriptor({ hosts: ['a.x.com'], streams: { items: stream({ item: table({ id: 'integer' }, ['id']) }) } });
+
+  test('回复 { stop: true } 后触发 ctx.signal、不再 emit，结果 stopped: true（不是 CANCELED）', async () => {
+    const code = rawConnector(STOP_DESC, `streams: { items: defineStream('items', async function* (ctx) {
+    ctx.signal.onAbort(() => ctx.log.info('aborted ' + ctx.signal.aborted));
+    for (let page = 0; page < 10; page += 1) {
+      yield ctx.record('item', { id: page });
+      yield ctx.checkpoint({ page });
+    }
+  }) },`);
+    let emitted = 0;
+    const run = await runGuest({
+      code, job: pullJob(),
+      host: { emit: () => { emitted += 1; return { seq: emitted, duplicate: false, rejected: 0, stop: emitted === 2 }; } },
+    });
+    const result = expectResult(run.outcome);
+    expect(emits(run)).toHaveLength(2);
+    expect(result).toEqual({ kind: 'pull', emittedBatches: 2, stopped: true, logs: [{ at: expect.any(String), level: 'info', message: 'aborted true' }] });
+  });
+
+  test('最后一批的回复带 stop 时同样 stopped: true', async () => {
+    const code = rawConnector(STOP_DESC, `streams: { items: defineStream('items', async function* (ctx) { yield ctx.record('item', { id: 1 }); }) },`);
+    const run = await runGuest({ code, job: pullJob(), host: { emit: () => ({ stop: true }) } });
+    expect(expectResult(run.outcome)).toEqual({ kind: 'pull', emittedBatches: 1, stopped: true, logs: [] });
+  });
+});
+
+describe('suggest 作业', () => {
+  const desc = descriptor({
+    hosts: ['a.x.com'],
+    streams: {
+      customers: stream({ customers: table({ id: 'string', name: 'string' }, ['id'], { extensible: true }), groups: table({ id: 'string' }, ['id']) }, { suggestColumns: true }),
+    },
+  });
+  const connector = (body: string) => rawConnector(desc, `streams: { customers: defineStream('customers', async function* () {}) },
+  suggestColumns: { customers: defineSuggestColumns('customers', async (ctx, input) => { ${body} }) },`);
+
+  test('suggestColumns 的返回值就是作业结果', async () => {
+    const run = await runGuest({ code: connector(`return [{ name: 'vip_level', type: 'string', title: 'VIP 等级' }];`), job: suggestJob('customers', 'customers') });
+    expect(expectResult(run.outcome)).toEqual({ kind: 'suggest', columns: [{ name: 'vip_level', type: 'string', title: 'VIP 等级' }], logs: [] });
+  });
+
+  test('收到的 table 参数是作业里的表名；与基础列同名的建议去掉并记 warn', async () => {
+    const run = await runGuest({
+      code: connector(`return [{ name: 'name', type: 'string', title: input.table }, { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: input.table }];`),
+      job: suggestJob('customers', 'customers'),
+    });
+    const result = expectResult(run.outcome);
+    expect(result).toMatchObject({ kind: 'suggest', columns: [{ name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'customers' }] });
+    expect(result.logs.map((log) => log.level)).toEqual(['warn']);
+  });
+
+  test('返回非法列名或类型时 SUGGEST_INVALID', async () => {
+    for (const value of [
+      `[{ name: '_secret', type: 'string', title: 'x' }]`,
+      `[{ name: 'vip level', type: 'string', title: 'x' }]`,
+      `[{ name: 'vip', type: 'text', title: 'x' }]`,
+      `[{ name: 'vip', type: 'decimal', title: 'x' }]`,
+      `'not a list'`,
+    ]) {
+      const failure = expectFailure((await runGuest({ code: connector(`return ${value};`), job: suggestJob('customers', 'customers') })).outcome);
+      expect(failure.code).toBe('SUGGEST_INVALID');
+    }
+  });
+
+  test('表不是该数据流的可扩展表、或数据流没有实现建议列时 CONNECTOR_LOAD_FAILED', async () => {
+    const code = connector('return [];');
+    expect(expectFailure((await runGuest({ code, job: suggestJob('customers', 'groups') })).outcome).code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(expectFailure((await runGuest({ code, job: suggestJob('customers', 'missing') })).outcome).code).toBe('CONNECTOR_LOAD_FAILED');
+  });
+
+  test('作业里不允许 emit；suggestColumns 抛 AuthError 时 AUTH_ERROR', async () => {
+    const failure = expectFailure((await runGuest({ code: connector(`throw new errors.AuthError('bad key');`), job: suggestJob('customers', 'customers') })).outcome);
+    expect(failure).toMatchObject({ code: 'AUTH_ERROR', message: 'bad key' });
+  });
+});
+
+describe('check 作业', () => {
+  const desc = (check: boolean) => descriptor({ hosts: ['a.x.com'], check, config: { token: configField('secret') }, streams: { items: stream(ITEM) } });
+  const connector = (check: string | null) => rawConnector(desc(check !== null), `streams: { items: defineStream('items', async function* () {}) },
+  ${check !== null ? `check: defineCheck(${check}),` : ''}`);
+
+  test('check 正常返回时 { kind: check, ok: true, logs }，不发任何宿主调用', async () => {
+    const run = await runGuest({ code: connector(`(ctx) => { ctx.log.info('token ' + ctx.secrets.token); }`), job: checkJob({}, ['token']) });
+    expect(expectResult(run.outcome)).toEqual({ kind: 'check', ok: true, logs: [{ at: expect.any(String), level: 'info', message: 'token ontos:secret:token' }] });
+    expect(run.calls).toEqual([]);
+  });
+
+  test('check 抛 AuthError 时失败 AUTH_ERROR', async () => {
+    const run = await runGuest({ code: connector(`() => { throw new errors.AuthError('bad token'); }`), job: checkJob() });
+    expect(expectFailure(run.outcome)).toMatchObject({ code: 'AUTH_ERROR', message: 'bad token' });
+  });
+
+  test('没有 check 时直接成功', async () => {
+    const run = await runGuest({ code: connector(null), job: checkJob() });
+    expect(expectResult(run.outcome)).toEqual({ kind: 'check', ok: true, logs: [] });
+  });
+});

package/test/runtime/operation.test.ts

@@ -0,0 +1,175 @@
+/** 连接器操作作业：run / lookup / simulate 的入参与输出校验、错误归类、ctx 的成员与加载时的 lookup 必填校验。 */
+import { describe, expect, test } from 'bun:test';
+import { parseChildMessage, type GuestJob, type GuestOperationResult } from '../../src/runtime';
+import { descriptor, operation as operationDescriptor, stream, table, valueField } from '../fixtures/descriptor';
+import { checkJob, expectFailure, expectResult, rawConnector, runGuest, type RunOptions } from './helpers';
+
+const INPUT = { sku: valueField('string'), qty: valueField('integer'), note: valueField('string', { optional: true }) };
+const OUTPUT = { externalId: valueField('string') };
+
+/**
+ * 一个有数据流（占位）与若干操作的连接器；`operations` 是操作名 → 实现对象源码，
+ * `idempotency` 给出各操作在描述里的幂等方式（缺省 supported）。
+ */
+function operationConnector(operations: Record<string, string>, idempotency: Record<string, 'supported' | 'unsupported'> = {}): string {
+  const desc = descriptor({
+    hosts: ['erp.example.com'],
+    streams: { orders: stream({ orders: table({ id: 'string' }, ['id']) }) },
+    operations: Object.fromEntries(Object.keys(operations).map((name) => [name, operationDescriptor(INPUT, OUTPUT, { risk: 'high', idempotency: idempotency[name] ?? 'supported' })])),
+  });
+  const impls = Object.entries(operations).map(([name, body]) => `${name}: defineOperation('${name}', { ${body} })`).join(', ');
+  return rawConnector(desc, `streams: { orders: defineStream('orders', async function* () {}) }, operations: { ${impls} },`);
+}
+
+function operation(body: string, extra = ''): Record<string, string> {
+  return { create_order: `${body}\n${extra}` };
+}
+
+function operationJob(overrides: Partial<Extract<GuestJob, { kind: 'operation' }>> = {}): GuestJob {
+  return {
+    kind: 'operation', phase: 'run', config: {}, secretFields: [], operation: 'create_order',
+    params: { sku: 'A-1', qty: 2 }, idempotencyKey: 'key-1', ...overrides,
+  };
+}
+
+async function runOperation(code: string, job: GuestJob, host: RunOptions['host'] = {}): Promise<{ result: GuestOperationResult; methods: string[] }> {
+  const run = await runGuest({ code, job, host });
+  const result = expectResult(run.outcome);
+  if (result.kind !== 'operation') throw new Error(`expected operation result, got ${result.kind}`);
+  return { result, methods: run.calls.map((call) => call.method) };
+}
+
+describe('run', () => {
+  test('入参缺非 optional 字段时 INPUT_INVALID，run 没被调用', async () => {
+    const code = operationConnector(operation(`async run(ctx) { ctx.log.info('called'); await ctx.http.post('/orders'); return { externalId: 'x' }; },`));
+    const { result, methods } = await runOperation(code, operationJob({ params: { sku: 'A-1' } }));
+    expect(result).toMatchObject({ kind: 'operation', phase: 'run', ok: false, code: 'INPUT_INVALID' });
+    expect(methods).toEqual([]);
+    expect(result.logs).toEqual([]);
+  });
+
+  test('成功：idempotencyKey 透传给 run，请求经宿主，输出按声明校验后原样返回', async () => {
+    const code = operationConnector(operation(`async run(ctx, params, meta) {
+      const res = await ctx.http.post('/orders', { headers: { 'Idempotency-Key': meta.idempotencyKey }, body: params });
+      return { externalId: res.data.id };
+    },`));
+    const seen: unknown[] = [];
+    const { result, methods } = await runOperation(code, operationJob(), {
+      http: (payload) => {
+        seen.push(payload);
+        return { status: 201, url: 'https://erp.example.com/orders', headers: { 'content-type': 'application/json' }, body: '{"id":"SO-1"}', bodyEncoding: 'utf8' };
+      },
+    });
+    expect(result).toEqual({ kind: 'operation', phase: 'run', ok: true, output: { externalId: 'SO-1' }, logs: [] });
+    expect(methods).toEqual(['http']);
+    expect(seen[0]).toMatchObject({ method: 'POST', url: 'https://erp.example.com/orders', headers: { 'idempotency-key': 'key-1' } });
+  });
+
+  test('返回值缺 output 声明的字段时 OUTPUT_INVALID', async () => {
+    const code = operationConnector(operation(`run() { return { other: 1 }; },`));
+    const { result } = await runOperation(code, operationJob());
+    expect(result).toMatchObject({ ok: false, code: 'OUTPUT_INVALID' });
+  });
+
+  test('RejectedError 得 REJECTED 并带外部业务码；IndeterminateError 得 INDETERMINATE；AuthError 得 AUTH_ERROR', async () => {
+    const cases: Array<[string, Record<string, unknown>]> = [
+      [`throw new errors.RejectedError('库存不足', { code: 'OUT_OF_STOCK' });`, { code: 'REJECTED', external: { code: 'OUT_OF_STOCK', message: '库存不足' } }],
+      [`throw new errors.IndeterminateError('connection dropped');`, { code: 'INDETERMINATE', message: 'connection dropped' }],
+      [`throw new errors.AuthError('token expired');`, { code: 'AUTH_ERROR', message: 'token expired' }],
+      [`throw new errors.RateLimited(10);`, { code: 'TRANSIENT_ERROR' }],
+      [`throw new Error('boom');`, { code: 'FATAL_ERROR', message: 'boom' }],
+    ];
+    for (const [statement, expected] of cases) {
+      const { result } = await runOperation(operationConnector(operation(`run() { ${statement} },`)), operationJob());
+      expect(result).toMatchObject({ kind: 'operation', phase: 'run', ok: false, ...expected });
+    }
+  });
+
+  test('ctx 没有 record 与 db，调用 ctx.db 得 TypeError', async () => {
+    const code = operationConnector(operation(`run(ctx) {
+      let name = 'none';
+      try { ctx.db.query('select 1'); } catch (e) { name = e.name; }
+      return { externalId: [name, 'record' in ctx, 'db' in ctx, typeof ctx.http.post, typeof ctx.crypto.hash, typeof ctx.cache.get].join(',') };
+    },`));
+    const { result } = await runOperation(code, operationJob());
+    expect(result).toMatchObject({ ok: true, output: { externalId: 'TypeError,false,false,function,function,function' } });
+  });
+
+  test('操作名不在描述里时 CONNECTOR_LOAD_FAILED', async () => {
+    const code = operationConnector(operation(`run() { return { externalId: 'x' }; },`));
+    const { result } = await runOperation(code, operationJob({ operation: 'missing' }));
+    expect(result).toMatchObject({ ok: false, code: 'CONNECTOR_LOAD_FAILED' });
+  });
+});
+
+describe('lookup', () => {
+  const lookupConnector = (lookup: string) => operationConnector(operation(`run() { return { externalId: 'x' }; },`, `lookup: ${lookup},`));
+
+  test('lookup 抛错按 unknown', async () => {
+    const { result } = await runOperation(lookupConnector(`() => { throw new Error('erp down'); }`), operationJob({ phase: 'lookup' }));
+    expect(result).toMatchObject({ kind: 'operation', phase: 'lookup', ok: true, lookup: { status: 'unknown' } });
+  });
+
+  test('applied 的输出按声明校验：合格时带出，不合格按 unknown；not_applied 原样', async () => {
+    const applied = await runOperation(
+      lookupConnector(`(ctx, input) => ({ status: 'applied', output: { externalId: input.idempotencyKey + ':' + input.params.sku } })`),
+      operationJob({ phase: 'lookup' }),
+    );
+    expect(applied.result).toMatchObject({ ok: true, lookup: { status: 'applied', output: { externalId: 'key-1:A-1' } } });
+    const invalid = await runOperation(lookupConnector(`() => ({ status: 'applied', output: { wrong: 1 } })`), operationJob({ phase: 'lookup' }));
+    expect(invalid.result).toMatchObject({ ok: true, lookup: { status: 'unknown' } });
+    const notApplied = await runOperation(lookupConnector(`async () => ({ status: 'not_applied' })`), operationJob({ phase: 'lookup' }));
+    expect(notApplied.result).toMatchObject({ ok: true, lookup: { status: 'not_applied' } });
+    const odd = await runOperation(lookupConnector(`() => ({ status: 'maybe' })`), operationJob({ phase: 'lookup' }));
+    expect(odd.result).toMatchObject({ ok: true, lookup: { status: 'unknown' } });
+  });
+
+  test('没有实现 lookup 的 supported 操作按 unknown', async () => {
+    const code = operationConnector(operation(`run() { return { externalId: 'x' }; },`));
+    const { result } = await runOperation(code, operationJob({ phase: 'lookup' }));
+    expect(result).toMatchObject({ ok: true, lookup: { status: 'unknown', notImplemented: true } });
+  });
+});
+
+describe('simulate', () => {
+  test('simulate 只收 params，不发任何宿主调用', async () => {
+    const code = operationConnector(operation(`run() { return { externalId: 'real' }; },`,
+      `simulate(params) { return { externalId: 'sim-' + params.sku + '-' + arguments.length }; },`));
+    const { result, methods } = await runOperation(code, operationJob({ phase: 'simulate' }));
+    expect(result).toEqual({ kind: 'operation', phase: 'simulate', ok: true, output: { externalId: 'sim-A-1-1' }, logs: [] });
+    expect(methods).toEqual([]);
+  });
+
+  test('没实现 simulate 时 FATAL_ERROR（宿主据此回退缺省结果）', async () => {
+    const code = operationConnector(operation(`run() { return { externalId: 'real' }; },`));
+    const { result } = await runOperation(code, operationJob({ phase: 'simulate' }));
+    expect(result).toMatchObject({ phase: 'simulate', ok: false, code: 'FATAL_ERROR' });
+  });
+
+  test('simulate 作业里的任何宿主调用在宿主侧都不合法；其余阶段不允许 db 与 emit', () => {
+    const simulateJob = operationJob({ phase: 'simulate' });
+    for (const method of ['http', 'secret.reveal', 'cache.get']) {
+      expect(parseChildMessage({ type: 'call', id: 1, method, payload: { key: 'k' } }, simulateJob)).toBeNull();
+    }
+    const runJob = operationJob();
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'db.query', payload: { sql: 'select 1', params: [] } }, runJob)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'cache.get', payload: { key: 'k' } }, runJob)).toMatchObject({ type: 'call', method: 'cache.get' });
+  });
+});
+
+describe('加载', () => {
+  test('unsupported 操作没有 lookup 时加载失败，失败码 CONNECTOR_LOOKUP_REQUIRED（其他作业同样）', async () => {
+    const code = operationConnector({ update_order: `run() { return { externalId: 'x' }; },` }, { update_order: 'unsupported' });
+    const failure = expectFailure((await runGuest({ code, job: checkJob() })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOOKUP_REQUIRED');
+    expect(failure.message).toContain('update_order');
+    const operationFailure = expectFailure((await runGuest({ code, job: operationJob({ operation: 'update_order' }) })).outcome);
+    expect(operationFailure.code).toBe('CONNECTOR_LOOKUP_REQUIRED');
+  });
+
+  test('unsupported 操作实现了 lookup 时正常执行', async () => {
+    const code = operationConnector({ update_order: `run() { return { externalId: 'x' }; }, lookup() { return { status: 'not_applied' }; },` }, { update_order: 'unsupported' });
+    const { result } = await runOperation(code, operationJob({ operation: 'update_order' }));
+    expect(result).toMatchObject({ ok: true, output: { externalId: 'x' } });
+  });
+});