@deepexi/datasense-connector 0.0.0-stage → 3.1.0

package/test/runtime/session.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, test } from 'bun:test';
+import { createGuestSession, parseChildMessage, parseParentMessage, undeclaredEmitTable } from '../../src/runtime';
+import type { SuggestedColumn } from '../../src';
+import { descriptor, push, table } from '../fixtures/descriptor';
+import {
+  bundleConnector, bundleGuest, checkJob, expectFailure, expectResult, pullJob, pushJob, rawConnector, runGuest, suggestJob,
+} from './helpers';
+
+const PUSH_DESC = descriptor({ pushes: { default: push({ item: table({ id: 'string' }, ['id']) }) } });
+const pushOnly = (handler = '{ map() {} }', header = ''): string => rawConnector(PUSH_DESC, `pushes: { default: definePush('default', ${handler}) },`, header);
+
+describe('模块加载与 SDK 注入', () => {
+  test('打包产物（虚拟入口形状）require("@deepexi/datasense-connector") 拿到 guest 内的 definePush / errors', async () => {
+    const code = await bundleConnector(`
+import { definePush, errors, SDK_VERSION } from '@deepexi/datasense-connector';
+export const descriptor = ${JSON.stringify(PUSH_DESC)};
+export const implementations = {
+  pushes: { default: definePush('default', { map(ctx, req) {
+    const error = new errors.RejectedPayload('x');
+    ctx.record('item', { id: req.id, code: error.code, sdk: SDK_VERSION });
+  } }) },
+};`);
+    expect(code).toContain('require("@deepexi/datasense-connector")');
+    const { outcome } = await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }]) });
+    const result = expectResult(outcome);
+    expect(result).toMatchObject({ kind: 'push', records: [{ requestId: 'r1', table: 'item', row: { id: 'r1', code: 'REJECTED_PAYLOAD', sdk: '3.1.0' } }] });
+  });
+
+  test('require("fs") 加载失败 CONNECTOR_LOAD_FAILED', async () => {
+    const code = `require('fs');\n${pushOnly()}`;
+    const failure = expectFailure((await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }]) })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(failure.message).toContain('cannot require fs');
+  });
+
+  test('顶层访问 process / Bun / fetch / node:vm / WebAssembly / eval 都不可用，会话不崩', async () => {
+    const probe = `
+const attempt = (fn) => { try { const v = fn(); return v === undefined ? 'undefined' : typeof v; } catch (e) { return e && e.name ? e.name : 'thrown'; } };
+const probes = {
+  process: attempt(() => process), bun: attempt(() => Bun), fetch: attempt(() => fetch),
+  vm: attempt(() => require('node:vm')), wasm: attempt(() => WebAssembly), eval: attempt(() => eval('1')),
+  fn: attempt(() => Function('return 1')), console: attempt(() => console), shadowRealm: attempt(() => ShadowRealm),
+  setTimeout: attempt(() => setTimeout), url: typeof URL,
+  hostFn: attempt(() => module.constructor.constructor('return typeof process')()),
+  requireCtor: attempt(() => require.constructor('return typeof process')()),
+  intl: new Intl.DateTimeFormat('en-US', { timeZone: 'Asia/Shanghai', hour: 'numeric', hourCycle: 'h23' }).format(new Date(0)),
+};`;
+    const code = pushOnly(`{ map(ctx) { ctx.record('item', { id: '1', ...probes }); } }`, probe);
+    const result = expectResult((await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }]) })).outcome);
+    if (result.kind !== 'push') throw new Error('expected push result');
+    expect(result.records[0]?.row).toEqual({
+      id: '1', process: 'ReferenceError', bun: 'ReferenceError', fetch: 'ReferenceError', vm: 'ConnectorError', wasm: 'ReferenceError',
+      eval: 'EvalError', fn: 'EvalError', console: 'ReferenceError', shadowRealm: 'ReferenceError', setTimeout: 'ReferenceError', url: 'undefined',
+      hostFn: 'EvalError', requireCtor: 'EvalError', intl: '08',
+    });
+  });
+
+  test('描述的名字或版本与 expect 不符，失败 CONNECTOR_LOAD_FAILED', async () => {
+    const code = pushOnly();
+    const failure = expectFailure((await runGuest({ code, expect: { name: 'demo', version: '2.0.0' }, job: pushJob([]) })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(failure.message).toContain('expected demo@2.0.0');
+  });
+
+  test('描述结构不对，失败消息列出问题', async () => {
+    const failure = expectFailure((await runGuest({ code: `module.exports = { descriptor: { name: 'demo', version: '1.0.0' }, implementations: {} };`, job: checkJob() })).outcome);
+    expect(failure.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(failure.message).toContain('descriptor.config');
+  });
+
+  test('编译错误与加载时抛错都是 CONNECTOR_LOAD_FAILED', async () => {
+    const syntax = expectFailure((await runGuest({ code: 'module.exports = {', job: checkJob() })).outcome);
+    expect(syntax.code).toBe('CONNECTOR_LOAD_FAILED');
+    expect(syntax.message).toContain('failed to compile');
+    const thrown = expectFailure((await runGuest({ code: `throw new Error('top level');`, job: checkJob() })).outcome);
+    expect(thrown).toMatchObject({ code: 'CONNECTOR_LOAD_FAILED', message: 'connector code failed to load: top level' });
+  });
+
+  test('任何作业都不发 definition / declaration：宿主信息从描述派生', async () => {
+    const pushRun = await runGuest({ code: pushOnly(), job: pushJob([{ requestId: 'r1', body: '{}' }]) });
+    expect(pushRun.calls).toEqual([]);
+    expectResult(pushRun.outcome);
+    const checkRun = await runGuest({ code: pushOnly(), job: checkJob() });
+    expect(checkRun.calls).toEqual([]);
+    expectResult(checkRun.outcome);
+  });
+
+  test('连接器抛错时 stack 的行列号对应打包产物本身', async () => {
+    const desc = JSON.stringify({ ...PUSH_DESC, check: true });
+    const code = [
+      `const { defineCheck, definePush } = require('@deepexi/datasense-connector');`,
+      `function explode() {`,
+      `  throw new Error('kaboom');`,
+      `}`,
+      `module.exports = { descriptor: ${desc}, implementations: { pushes: { default: definePush('default', { map() {} }) },`,
+      `  check: defineCheck(() => { explode(); }) } };`,
+    ].join('\n');
+    const failure = expectFailure((await runGuest({ code, job: checkJob() })).outcome);
+    expect(failure.code).toBe('FATAL_ERROR');
+    expect(failure.message).toBe('kaboom');
+    expect(failure.stack).toContain('connector.js:3:');
+    expect(failure.stack).toContain('connector.js:6:');
+    expect(failure.stack).not.toContain('ontos-guest.js');
+    expect(failure.stack).not.toContain(import.meta.dir);
+  });
+
+  test('打包后的 TS 连接器抛错时行号对应打包产物', async () => {
+    const code = await bundleConnector(`
+import { defineCheck, definePush } from '@deepexi/datasense-connector';
+export const descriptor = ${JSON.stringify({ ...PUSH_DESC, check: true })};
+export const implementations = {
+  check: defineCheck(() => { throw new Error('bundled boom'); }),
+  pushes: { default: definePush('default', { map() {} }) },
+};`);
+    const failure = expectFailure((await runGuest({ code, job: checkJob() })).outcome);
+    const line = code.split('\n').findIndex((text) => text.includes('bundled boom')) + 1;
+    expect(line).toBeGreaterThan(0);
+    expect(failure.stack).toContain(`connector.js:${line}:`);
+  });
+});
+
+describe('会话边界', () => {
+  test('execute 之前的消息与重复的 execute 被忽略；畸形消息被忽略', async () => {
+    const guest = await bundleGuest();
+    const sent: string[] = [];
+    const session = createGuestSession((json) => sent.push(json));
+    session.handle('not json');
+    session.handle(JSON.stringify({ type: 'reply', id: 1, ok: true, value: 1 }));
+    const execute = JSON.stringify({ type: 'execute', guest, code: pushOnly(), expect: { name: 'demo', version: '1.0.0' }, job: pushJob([]) });
+    session.handle(execute);
+    session.handle(execute);
+    await Bun.sleep(50);
+    expect(sent.map((json) => JSON.parse(json).type)).toEqual(['result']);
+  });
+
+  test('guest 源码不可用时失败 CONNECTOR_LOAD_FAILED', async () => {
+    const sent: string[] = [];
+    const session = createGuestSession((json) => sent.push(json));
+    session.handle(JSON.stringify({ type: 'execute', guest: 'module.exports = {};', code: '', expect: { name: 'demo', version: '1.0.0' }, job: pushJob([]) }));
+    expect(JSON.parse(sent[0] ?? '{}')).toMatchObject({ type: 'failure', code: 'CONNECTOR_LOAD_FAILED' });
+  });
+
+  test('改写 Promise.prototype.then 或全局 JSON 拿不到宿主函数，也不影响消息通道', async () => {
+    const code = pushOnly(`{ map(ctx, req) {
+    const probe = (fn) => { try { return String(fn.constructor.constructor('return typeof process')()); } catch (e) { return e.name; } };
+    globalThis.leak = 'none';
+    const original = Promise.prototype.then;
+    Promise.prototype.then = function (a, b) { if (typeof a === 'function' && globalThis.leak === 'none') globalThis.leak = probe(a); return original.call(this, a, b); };
+    JSON.stringify = () => ({ forged: true });
+    ctx.record('item', { id: req.id, leak: globalThis.leak });
+  } }`);
+    const run = await runGuest({ code, job: pushJob([{ requestId: 'r1', body: '{}' }, { requestId: 'r2', body: '{}' }]) });
+    const result = expectResult(run.outcome);
+    if (result.kind !== 'push') throw new Error('expected push result');
+    expect(result.records.map((record) => record.row.id)).toEqual(['r1', 'r2']);
+    expect(['none', 'EvalError']).toContain(result.records[1]?.row.leak as string);
+  });
+});
+
+describe('协议解析', () => {
+  test('parseParentMessage 校验 execute / reply / cancel', () => {
+    expect(parseParentMessage({ type: 'cancel' })).toEqual({ type: 'cancel' });
+    expect(parseParentMessage({ type: 'reply', id: 1, ok: false, error: { code: 'EGRESS_RATE_LIMITED', message: 'slow down', retryAfterMs: 50 } }))
+      .toEqual({ type: 'reply', id: 1, ok: false, error: { code: 'EGRESS_RATE_LIMITED', message: 'slow down', retryAfterMs: 50 } });
+    expect(parseParentMessage({ type: 'reply', id: 0, ok: true, value: 1 })).toBeNull();
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: { kind: 'pull', config: {}, secretFields: [] } })).toBeNull();
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: pullJob() })).toMatchObject({ type: 'execute', job: { kind: 'pull', stream: 'items' } });
+  });
+
+  test('parseChildMessage 按作业校验：emit 的表、reveal 的字段、方法名、结果的 kind', () => {
+    const job = pullJob({ secretFields: ['token'] });
+    const batch = { records: [{ table: 'item', row: { id: 1 } }], removals: [], logs: [] };
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'emit', payload: batch }, job)).toMatchObject({ method: 'emit' });
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'emit', payload: { ...batch, records: [{ table: 'other', row: {} }] } }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'emit', payload: batch }, checkJob())).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 1, method: 'emit', payload: batch }, suggestJob('items', 'item'))).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 2, method: 'secret.reveal', payload: { field: 'token' } }, job)).toMatchObject({ payload: { field: 'token' } });
+    expect(parseChildMessage({ type: 'call', id: 2, method: 'secret.reveal', payload: { field: 'other' } }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 3, method: 'definition', payload: {} }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 3, method: 'declaration', payload: {} }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 4, method: 'exec', payload: {} }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'result', result: { kind: 'discover', summary: {}, discover: {}, logs: [] } }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'result', result: { kind: 'pull', emittedBatches: 2, logs: [] } }, job)).toEqual({ type: 'result', result: { kind: 'pull', emittedBatches: 2, logs: [] } });
+    expect(parseChildMessage({ type: 'failure', code: 'NOPE', message: 'x', logs: [] }, job)).toBeNull();
+    expect(parseChildMessage({ type: 'call', id: 5, method: 'http', payload: { method: 'GET', url: 'https://a', headers: {}, query: { a: ['1'] }, body: null, bodyEncoding: 'utf8' } }, job))
+      .toMatchObject({ method: 'http' });
+    expect(parseChildMessage({ type: 'call', id: 5, method: 'http', payload: { method: 'TRACE', url: 'https://a', headers: {}, query: {}, body: null, bodyEncoding: 'utf8' } }, job)).toBeNull();
+  });
+
+  test('推送结果的 requestId 必须属于本批请求', () => {
+    const job = pushJob([{ requestId: 'r1', body: '{}' }]);
+    const result = { kind: 'push', records: [{ requestId: 'r2', table: 'item', row: {} }], removals: [], rejected: [], logs: [] };
+    expect(parseChildMessage({ type: 'result', result }, job)).toBeNull();
+  });
+
+  test('check / suggest 作业、生效限流、stopped 与 undeclaredEmitTable', () => {
+    const check = checkJob();
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: check })).toMatchObject({ job: check });
+    expect(parseChildMessage({ type: 'result', result: { kind: 'check', ok: true, logs: [] } }, check)).toEqual({ type: 'result', result: { kind: 'check', ok: true, logs: [] } });
+    expect(parseChildMessage({ type: 'result', result: { kind: 'check', ok: false, logs: [] } }, check)).toBeNull();
+    // discover 作业已删除
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: { kind: 'discover', config: {}, secretFields: [] } })).toBeNull();
+
+    // 生效限流：合法时原样带上，不合法时整条作业不合法
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: pullJob({ rateLimit: { perSecond: 5, concurrency: 2 } }) }))
+      .toMatchObject({ job: { kind: 'pull', rateLimit: { perSecond: 5, concurrency: 2 } } });
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: { ...pullJob(), rateLimit: { perSecond: 5, concurrency: 0 } } })).toBeNull();
+
+    // suggest：结果只认 { kind: suggest, columns }，列的结构重建
+    const suggest = suggestJob('customers', 'customers');
+    expect(parseParentMessage({ type: 'execute', guest: '', code: '', expect: { name: 'a', version: '1.0.0' }, job: suggest })).toMatchObject({ job: suggest });
+    const columns: SuggestedColumn[] = [{ name: 'vip_level', type: 'string', title: 'VIP' }, { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'Credit', description: 'x' }];
+    expect(parseChildMessage({ type: 'result', result: { kind: 'suggest', columns, logs: [] } }, suggest)).toEqual({ type: 'result', result: { kind: 'suggest', columns, logs: [] } });
+    expect(parseChildMessage({ type: 'result', result: { kind: 'suggest', columns: [{ name: 'x', type: 'text', title: 'x' }], logs: [] } }, suggest)).toBeNull();
+    expect(parseChildMessage({ type: 'result', result: { kind: 'pull', emittedBatches: 0, logs: [] } }, suggest)).toBeNull();
+
+    // undeclaredEmitTable：只在 emit 写了作业表以外的表时给出表名（宿主按 SCHEMA_ERROR 结束），其他不合法消息为 null
+    const stray = { type: 'call', id: 5, method: 'emit', payload: { records: [{ table: 'item', row: {} }], removals: [{ table: 'ghost', key: {} }], logs: [] } };
+    expect(undeclaredEmitTable(stray, pullJob({ tables: ['item'] }))).toBe('ghost');
+    expect(undeclaredEmitTable(stray, pullJob({ tables: ['item', 'ghost'] }))).toBeNull();
+    expect(undeclaredEmitTable({ type: 'call', id: 6, method: 'http', payload: {} }, pullJob())).toBeNull();
+
+    // stopped
+    const job = pullJob();
+    expect(parseChildMessage({ type: 'result', result: { kind: 'pull', emittedBatches: 1, stopped: true, logs: [] } }, job))
+      .toEqual({ type: 'result', result: { kind: 'pull', emittedBatches: 1, stopped: true, logs: [] } });
+    expect(parseChildMessage({ type: 'result', result: { kind: 'pull', emittedBatches: 1, stopped: 'yes', logs: [] } }, job)).toBeNull();
+  });
+});

package/test/testing/acceptance-fixtures.test.ts

@@ -0,0 +1,69 @@
+/**
+ * 两个验收连接器（`test/fixtures/connectors/{http-pull,pg-pull}`）各录一个用例（在数据流目录的 `tests/` 下），`runFixtures` 回放都 `ok: true`；
+ * 重新录制得到与已提交文件逐字节相同的内容（pg-pull 需要本机 :15432 的 Postgres，没有时跳过重录）。
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import path from 'node:path';
+import ts from 'typescript';
+import type { ConnectorDescriptor } from '../../src';
+import {
+  createInProcessExecutor, createVmExecutor, loadLocalConnector, readFixtureDir, runFixtures, type FixtureCaseResult,
+} from '../../src/testing';
+import {
+  dropPgSchema, HTTP_PULL_DIR, localPgUnavailable, PG_PULL_DIR, preparePgSchema, recordHttpPull, recordPgPull,
+} from '../fixtures/acceptance';
+
+const pgUnavailable = await localPgUnavailable();
+if (pgUnavailable) console.warn(`[acceptance-fixtures] 本机 :15432 没有 Postgres，跳过 pg_pull 重录：${pgUnavailable}`);
+
+const CASES = [
+  { connector: 'http_pull', source: HTTP_PULL_DIR, name: 'basic', stream: 'items', table: 'items' },
+  { connector: 'pg_pull', source: PG_PULL_DIR, name: 'customers-full', stream: 'customers', table: 'customers' },
+] as const;
+
+function expectPassed(results: FixtureCaseResult[], name: string, stream: string, table: string): void {
+  expect(results).toHaveLength(1);
+  const [result] = results;
+  expect(result?.error).toBeNull();
+  expect(result?.findings).toEqual([]);
+  expect(result?.ok).toBe(true);
+  expect(result?.name).toBe(name);
+  expect(result?.capability).toBe(`streams/${stream}`);
+  expect(result?.stats.records).toEqual({ [table]: 3 });
+  expect(result?.stats.checkpoints).toBe(2);
+}
+
+describe.each(CASES)('$connector fixture', ({ source, name, stream, table }) => {
+  test('replays ok in the vm (CLI path)', async () => {
+    const connector = await loadLocalConnector(source, { typescript: ts });
+    expectPassed(await runFixtures(createVmExecutor(connector), connector.descriptor, connector.testFiles), name, stream, table);
+  });
+
+  test('replays ok in process (vitest path)', async () => {
+    const descriptor = JSON.parse(await Bun.file(path.join(source, '.ontos/descriptor.json')).text()) as ConnectorDescriptor;
+    const streams: Record<string, unknown> = {};
+    for (const name of Object.keys(descriptor.streams)) streams[name] = ((await import(path.join(source, 'streams', name, 'index.ts'))) as { default: unknown }).default;
+    const executor = createInProcessExecutor({ descriptor, implementations: { streams } });
+    expectPassed(await runFixtures(executor, descriptor, await readFixtureDir(source)), name, stream, table);
+  });
+});
+
+describe('re-recording', () => {
+  afterAll(async () => {
+    await dropPgSchema();
+  });
+
+  test('http_pull: recording again gives the committed files byte for byte', async () => {
+    const recorded = await recordHttpPull();
+    expect(recorded.result.error).toBeNull();
+    expect(recorded.files).toEqual(await readFixtureDir(HTTP_PULL_DIR));
+  });
+
+  // 本机没有 :15432 的 Postgres 时跳过
+  test.skipIf(Boolean(pgUnavailable))('pg_pull: recording again against localhost:15432 gives the committed files byte for byte', async () => {
+    expect(await preparePgSchema()).toBe(true);
+    const recorded = await recordPgPull();
+    expect(recorded.result.error).toBeNull();
+    expect(recorded.files).toEqual(await readFixtureDir(PG_PULL_DIR));
+  });
+});

package/test/testing/compliance.test.ts

@@ -0,0 +1,247 @@
+/**
+ * 合规检查与结构推断：主键重复、列类型、未声明表与字段、断点单调、全量可重复、期望、ok 的判定。
+ */
+import { describe, expect, test } from 'bun:test';
+import { definePush, defineStream, defineSuggestColumns, errors } from '../../src';
+import {
+  checkCompliance, createInProcessExecutor, inferRecordSchema, runFixture, type ComplianceTable, type LoadedFixture, type LocalRunResult,
+} from '../../src/testing';
+import { descriptor, push, stream, table } from '../fixtures/descriptor';
+
+const ORDERS: Record<string, ComplianceTable> = {
+  orders: { columns: { id: { type: 'string' }, amount: { type: 'integer' }, placed_at: { type: 'instant' } }, primaryKey: ['id'], extensible: false },
+};
+const EVENTS: Record<string, ComplianceTable> = { events: { columns: { id: { type: 'string' } }, primaryKey: ['id'], extensible: false } };
+
+function result(overrides: Partial<LocalRunResult> = {}): LocalRunResult {
+  return { records: [], removals: [], checkpoints: [], logs: [], rejected: [], stopped: false, error: null, ...overrides };
+}
+
+const order = (row: Record<string, unknown>) => ({ table: 'orders', row });
+const codes = (findings: Array<{ code: string }>) => findings.map((finding) => finding.code);
+
+describe('records against the tables', () => {
+  test('two records with the same primary key give PRIMARY_KEY_DUPLICATE for that table', () => {
+    const findings = checkCompliance({
+      tables: ORDERS,
+      result: result({ records: [order({ id: 'a', amount: 1 }), order({ id: 'b', amount: 2 }), order({ id: 'a', amount: 3 })] }),
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ code: 'PRIMARY_KEY_DUPLICATE', table: 'orders', detail: { count: 1, sample: { id: 'a' } } });
+  });
+
+  test('a value of the wrong type gives RECORD_SCHEMA_MISMATCH', () => {
+    const wrongType = checkCompliance({ tables: ORDERS, result: result({ records: [order({ id: 'a', amount: 'x' })] }) });
+    expect(wrongType).toHaveLength(1);
+    expect(wrongType[0]).toMatchObject({ code: 'RECORD_SCHEMA_MISMATCH', table: 'orders', detail: { column: 'amount', sample: 'x' } });
+
+    const fine = checkCompliance({
+      tables: ORDERS,
+      result: result({ records: [order({ id: 'a', amount: '12', placed_at: '2026-10-01T00:00:00+08:00' }), order({ id: 'b', amount: null })] }),
+    });
+    expect(fine).toEqual([]);
+
+    const naive = checkCompliance({ tables: ORDERS, result: result({ records: [order({ id: 'a', placed_at: '2026-10-01T00:00:00' })] }) });
+    expect(codes(naive)).toEqual(['RECORD_SCHEMA_MISMATCH']);
+  });
+
+  test('the same problem on many records is reported once with a count', () => {
+    const findings = checkCompliance({
+      tables: ORDERS,
+      result: result({ records: [order({ id: 'a', amount: 'x' }), order({ id: 'b', amount: 'y' }), order({ id: 'c', amount: 1.5 })] }),
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.detail).toMatchObject({ count: 3, sample: 'x' });
+  });
+
+  test('undeclared fields on a non-extensible table give one UNDECLARED_FIELDS first, listing every field sorted', () => {
+    const findings = checkCompliance({
+      tables: ORDERS, result: result({ records: [order({ id: 'a', note: 'n', amount: 'x' }), order({ id: 'b', zeta: 1, alpha: 2 })] }),
+    });
+    expect(codes(findings)).toEqual(['UNDECLARED_FIELDS', 'RECORD_SCHEMA_MISMATCH']);
+    expect(findings[0]).toMatchObject({ table: 'orders', detail: { fields: ['alpha', 'note', 'zeta'] } });
+    expect(findings[0]?.message).toContain('alpha, note, zeta');
+  });
+
+  test('extra fields on an extensible table are not a finding', () => {
+    const tables = { orders: { ...ORDERS.orders!, extensible: true } };
+    expect(checkCompliance({ tables, result: result({ records: [order({ id: 'a', vip_level: 'gold' })] }) })).toEqual([]);
+  });
+
+  test('a record for a table outside the stream gives UNDECLARED_TABLE', () => {
+    const findings = checkCompliance({
+      tables: ORDERS,
+      result: result({ records: [{ table: 'events', row: { id: 'e' } }], removals: [{ table: 'ghost', key: { id: 'g' } }] }),
+    });
+    expect(findings.map((finding) => [finding.code, finding.table])).toEqual([['UNDECLARED_TABLE', 'events'], ['UNDECLARED_TABLE', 'ghost']]);
+    // 推送范围：events 是该推送的表
+    expect(checkCompliance({ tables: EVENTS, result: result({ records: [{ table: 'events', row: { id: 'e' } }] }) })).toEqual([]);
+    // 没有表结构时跳过依赖表结构的检查
+    expect(checkCompliance({ tables: null, result: result({ records: [{ table: 'events', row: { x: 1 } }] }) })).toEqual([]);
+  });
+
+  test('removal keys are checked against the primary key', () => {
+    const findings = checkCompliance({ tables: ORDERS, result: result({ removals: [{ table: 'orders', key: { id: 'a', amount: 1 } }] }) });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ code: 'RECORD_SCHEMA_MISMATCH', detail: { column: 'amount' } });
+  });
+});
+
+describe('checkpoints', () => {
+  const run = (states: unknown[]) => checkCompliance({ tables: null, result: result({ checkpoints: states.map((state, index) => ({ seq: index + 1, state })) }) });
+
+  test('a number going backwards is CHECKPOINT_NOT_MONOTONIC', () => {
+    const findings = run([{ cursor: 5 }, { cursor: 3 }]);
+    expect(codes(findings)).toEqual(['CHECKPOINT_NOT_MONOTONIC']);
+    expect(findings[0]?.detail).toEqual({ field: 'cursor', previous: 5, next: 3, seq: 2 });
+  });
+
+  test('ISO times compare by instant: 2026-10-02Z then 2026-10-01+08:00 goes backwards', () => {
+    expect(codes(run([{ updatedAt: '2026-10-02T00:00:00Z' }, { updatedAt: '2026-10-01T00:00:00+08:00' }]))).toEqual(['CHECKPOINT_NOT_MONOTONIC']);
+    // 同一时刻的不同写法不算倒退
+    expect(run([{ updatedAt: '2026-10-01T00:00:00+08:00' }, { updatedAt: '2026-09-30T16:00:00.000Z' }])).toEqual([]);
+  });
+
+  test('other strings are not compared: token b then a is fine; equal and increasing values are fine', () => {
+    expect(run([{ token: 'b' }, { token: 'a' }])).toEqual([]);
+    expect(run([{ cursor: 1, at: '2026-10-01' }, { cursor: 1, at: '2026-10-02' }, { cursor: 2 }])).toEqual([]);
+  });
+});
+
+describe('runFixture', () => {
+  const DESCRIPTOR = descriptor({
+    name: 'drift', hosts: ['api.example.com'],
+    streams: { items: stream({ item: table({ id: 'string', n: 'integer' }, ['id']) }) },
+  });
+
+  /** 每次运行产出不同的记录（第二遍多一条）。 */
+  function drifting() {
+    let runs = 0;
+    return createInProcessExecutor({
+      descriptor: DESCRIPTOR,
+      implementations: {
+        streams: {
+          items: defineStream('items', async function* (ctx) {
+            runs += 1;
+            for (let index = 0; index < runs + 1; index += 1) yield ctx.record('item', { id: `r${index}`, n: index });
+          }),
+        },
+      },
+    });
+  }
+
+  const fixture = (mode: 'full' | 'incremental', expect?: Record<string, unknown>): LoadedFixture => ({
+    capability: 'streams/items', name: 'drift', case: { kind: 'pull', stream: 'items', mode, config: {}, ...(expect ? { expect } : {}) }, exchanges: [], requests: [],
+  });
+
+  test('two full reads with different records give FULL_READ_NOT_REPEATABLE; incremental mode skips the check', async () => {
+    const full = await runFixture(drifting(), DESCRIPTOR, fixture('full'));
+    expect(codes(full.findings)).toEqual(['FULL_READ_NOT_REPEATABLE']);
+    expect(full.findings[0]?.detail).toMatchObject({ firstCount: 2, secondCount: 3 });
+    expect(full.ok).toBe(false);
+
+    const incremental = await runFixture(drifting(), DESCRIPTOR, fixture('incremental'));
+    expect(incremental.findings).toEqual([]);
+    expect(incremental.ok).toBe(true);
+    expect(incremental.stats.records).toEqual({ item: 2 });
+  });
+
+  test('expect.records { item: 3 } with 2 records gives EXPECTATION_FAILED and ok false', async () => {
+    const failed = await runFixture(drifting(), DESCRIPTOR, fixture('incremental', { records: { item: 3 } }));
+    expect(codes(failed.findings)).toEqual(['EXPECTATION_FAILED']);
+    expect(failed.findings[0]?.message).toContain('item: expected 3, got 2');
+    expect(failed.ok).toBe(false);
+
+    const passed = await runFixture(drifting(), DESCRIPTOR, fixture('incremental', { records: { item: 2 }, checkpoints: 0 }));
+    expect(passed.ok).toBe(true);
+  });
+
+  test('any finding other than FIXTURE_EXCHANGE_UNUSED fails the case; undeclared fields fail with UNDECLARED_FIELDS first', async () => {
+    const executor = createInProcessExecutor({
+      descriptor: DESCRIPTOR,
+      implementations: {
+        streams: { items: defineStream('items', async function* (ctx) { yield ctx.record('item', { id: 'same', n: 1, extra: 'x' }); yield ctx.record('item', { id: 'same', n: 2 }); }) },
+      },
+    });
+    const outcome = await runFixture(executor, DESCRIPTOR, fixture('incremental'));
+    expect(codes(outcome.findings)).toEqual(['UNDECLARED_FIELDS', 'PRIMARY_KEY_DUPLICATE']);
+    expect(outcome.ok).toBe(false);
+  });
+
+  test('a capability missing from the descriptor gives CAPABILITY_UNKNOWN', async () => {
+    const outcome = await runFixture(drifting(), DESCRIPTOR, { ...fixture('full'), capability: 'streams/ghost', case: { kind: 'pull', stream: 'ghost', mode: 'full', config: {} } });
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error?.code).toBe('CAPABILITY_UNKNOWN');
+  });
+
+  test('push cases replay requests.ndjson against the push tables', async () => {
+    const desc = descriptor({ name: 'pusher', pushes: { default: push({ event: table({ id: 'string' }, ['id']) }) } });
+    const pusher = createInProcessExecutor({
+      descriptor: desc,
+      implementations: {
+        pushes: {
+          default: definePush('default', {
+            map(ctx, request) {
+              const body = JSON.parse(request.body) as { id?: string };
+              if (!body.id) throw new errors.RejectedPayload('no id');
+              ctx.record(body.id === 'stray' ? 'other' : 'event', { id: body.id });
+            },
+          }),
+        },
+      },
+    });
+    const requests = ['{"id":"a"}', '{}', '{"id":"stray"}'].map((body, index) => ({ requestId: `r${index}`, receivedAt: '2026-10-25T00:00:00.000Z', headers: {}, body }));
+    const outcome = await runFixture(pusher, desc, {
+      capability: 'pushes/default', name: 'hook', case: { kind: 'push', push: 'default', config: {}, expect: { rejected: 1 } }, exchanges: [], requests,
+    });
+    expect(outcome.error).toBeNull();
+    expect(outcome.stats).toEqual({ records: { event: 1, other: 1 }, removals: {}, checkpoints: 0, rejected: 1 });
+    expect(codes(outcome.findings)).toEqual(['UNDECLARED_TABLE']);
+  });
+
+  test('suggest cases compare the suggestions with expect.columns, ignoring order', async () => {
+    const desc = descriptor({
+      name: 'crm',
+      streams: { customers: stream({ customers: table({ id: 'string' }, ['id'], { extensible: true }) }, { suggestColumns: true }) },
+    });
+    const executor = createInProcessExecutor({
+      descriptor: desc,
+      implementations: {
+        streams: { customers: defineStream('customers', async function* () {}) },
+        suggestColumns: {
+          customers: defineSuggestColumns('customers', async () => [
+            { name: 'vip_level', type: 'string', title: 'VIP level' },
+            { name: 'id', type: 'string', title: 'duplicate base column' },
+            { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'Credit' },
+          ]),
+        },
+      },
+    });
+    const suggestCase = (columns: unknown[]): LoadedFixture => ({
+      capability: 'streams/customers', name: 'fields', exchanges: [], requests: [],
+      case: { kind: 'suggest', stream: 'customers', table: 'customers', config: {}, expect: { columns: columns as never } },
+    });
+    const passed = await runFixture(executor, desc, suggestCase([
+      { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'Credit' },
+      { name: 'vip_level', type: 'string', title: 'VIP level' },
+    ]));
+    expect(passed).toMatchObject({ ok: true, kind: 'suggest', error: null });
+    const failed = await runFixture(executor, desc, suggestCase([{ name: 'vip_level', type: 'string', title: 'VIP level' }]));
+    expect(failed.ok).toBe(false);
+    expect(codes(failed.findings)).toEqual(['EXPECTATION_FAILED']);
+  });
+});
+
+describe('inferRecordSchema', () => {
+  test('nulls are ignored; ISO date-times are timestamps', () => {
+    expect(inferRecordSchema([{ a: 1 }, { a: null, b: '2026-10-01T00:00:00Z' }])).toEqual({ a: 'number', b: 'timestamp' });
+  });
+
+  test('all-null columns, mixed strings, objects and mixed kinds', () => {
+    expect(inferRecordSchema([
+      { n: null, s: '2026-10-01T00:00:00Z', o: { k: 1 }, m: 1, b: true, d: '2026-10-01' },
+      { n: null, s: 'plain', o: [1], m: 'x', b: false, d: '2026-10-02' },
+    ])).toEqual({ n: 'null', s: 'string', o: 'json', m: 'json', b: 'boolean', d: 'string' });
+    expect(inferRecordSchema([])).toEqual({});
+  });
+});