@deepexi/datasense-connector 3.0.1 → 3.1.0

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

@@ -0,0 +1,160 @@
+/**
+ * 连接器操作的本地运行与用例：经本地模拟网关执行并录制、用例往返、不联网回放与期望比较、用例格式。
+ */
+import { describe, expect, test } from 'bun:test';
+import { defineOperation, defineStream, errors } from '../../src';
+import {
+  createInProcessExecutor, createLocalGateway, createRecorder, parseFixtures, runFixtures, runOperation, serializeFixture,
+  type FixtureCase, type FixtureExchange, type GuestOperationResult,
+} from '../../src/testing';
+import { configField, descriptor, operation, stream, table, valueField } from '../fixtures/descriptor';
+
+const SECRETS = { token: 'tok-12345' };
+
+type D = {
+  config: Record<never, never>;
+  secrets: { token: string };
+  streams: { orders: { tables: { orders: { id: string } }; params: Record<never, never> } };
+  extensibleStreams: Record<never, never>;
+  pushes: Record<never, never>;
+  operations: { create_order: { input: { sku: string; qty: number }; output: { externalId: string; status: string }; idempotency: 'supported' } };
+};
+
+const DESCRIPTOR = descriptor({
+  name: 'erp', hosts: ['erp.example.com'], config: { token: configField('secret', { exposeToScript: true }) },
+  streams: { orders: stream({ orders: table({ id: 'string' }, ['id']) }, { syncModes: ['full'] }) },
+  operations: {
+    create_order: operation({ sku: valueField('string'), qty: valueField('integer') }, { externalId: valueField('string'), status: valueField('string') }, { risk: 'high' }),
+  },
+});
+
+const connector = {
+  descriptor: DESCRIPTOR,
+  implementations: {
+    streams: { orders: defineStream<D, 'orders'>('orders', async function* () {}) },
+    operations: {
+      create_order: defineOperation<D, 'create_order'>('create_order', {
+        async run(ctx, params, meta) {
+          const res = await ctx.http.post<{ id?: string; status?: string; code?: string }>('/api/orders', {
+            headers: { authorization: `Bearer ${ctx.secrets.token}`, 'idempotency-key': meta.idempotencyKey },
+            body: params,
+            raw: true,
+          });
+          const data = JSON.parse(res.text) as { id?: string; status?: string; code?: string };
+          if (res.status === 422) throw new errors.RejectedError('rejected by erp', data.code !== undefined ? { code: data.code } : undefined);
+          return { externalId: String(data.id), status: String(data.status) };
+        },
+      }),
+    },
+  },
+};
+
+/** 假的业务系统：qty > 10 时 422 OUT_OF_STOCK，否则建单。 */
+function erpFetch(seen: Array<{ url: string; authorization: string | null }>): typeof fetch {
+  return (async (input: string | URL | Request, init?: RequestInit) => {
+    const body = JSON.parse(new TextDecoder().decode(init?.body as Uint8Array)) as { qty: number };
+    seen.push({ url: String(input), authorization: new Headers(init?.headers).get('authorization') });
+    if (body.qty > 10) return new Response(JSON.stringify({ code: 'OUT_OF_STOCK' }), { status: 422, headers: { 'content-type': 'application/json' } });
+    return new Response(JSON.stringify({ id: 'SO-1', status: 'created' }), { status: 201, headers: { 'content-type': 'application/json' } });
+  }) as typeof fetch;
+}
+
+async function record(params: Record<string, unknown>): Promise<{ result: GuestOperationResult; exchanges: FixtureExchange[]; seen: Array<{ url: string; authorization: string | null }> }> {
+  const seen: Array<{ url: string; authorization: string | null }> = [];
+  const recorder = createRecorder({ secrets: SECRETS });
+  const gateway = createLocalGateway({ hosts: ['erp.example.com'], secrets: SECRETS, fetch: erpFetch(seen), onExchange: (exchange) => recorder.onExchange(exchange) });
+  const result = await runOperation(createInProcessExecutor(connector), {
+    config: {}, operation: 'create_order', params, idempotencyKey: 'stable:abc', host: gateway,
+  });
+  await gateway.close();
+  return { result, exchanges: recorder.exchanges(), seen };
+}
+
+function operationCase(params: Record<string, unknown>, expectation: Extract<FixtureCase, { kind: 'operation' }>['expect']): FixtureCase {
+  return { kind: 'operation', operation: 'create_order', params, idempotencyKey: 'stable:abc', config: {}, secrets: SECRETS, expect: expectation };
+}
+
+describe('runOperation 经本地模拟网关', () => {
+  test('返回 GuestOperationResult，请求经模拟网关（凭证由网关替换）并进入录制器', async () => {
+    const { result, exchanges, seen } = await record({ sku: 'A-1', qty: 2 });
+    expect(result).toMatchObject({ kind: 'operation', phase: 'run', ok: true, output: { externalId: 'SO-1', status: 'created' } });
+    expect(seen).toEqual([{ url: 'https://erp.example.com/api/orders', authorization: 'Bearer tok-12345' }]);
+    expect(exchanges).toHaveLength(1);
+    expect(exchanges[0]).toMatchObject({ kind: 'http', request: { method: 'POST', url: 'https://erp.example.com/api/orders', headers: { authorization: '***', 'idempotency-key': 'stable:abc' } } });
+  });
+
+  test('外部系统拒绝时 REJECTED 带外部业务码；simulate 阶段没声明 simulate 时 FATAL_ERROR', async () => {
+    const { result } = await record({ sku: 'A-1', qty: 99 });
+    expect(result).toMatchObject({ ok: false, code: 'REJECTED', external: { code: 'OUT_OF_STOCK' } });
+    const gateway = createLocalGateway({ hosts: [], secrets: {} });
+    const simulated = await runOperation(createInProcessExecutor(connector), {
+      config: {}, operation: 'create_order', params: { sku: 'A-1', qty: 2 }, idempotencyKey: 'k', phase: 'simulate', host: gateway,
+    });
+    expect(simulated).toMatchObject({ phase: 'simulate', ok: false, code: 'FATAL_ERROR' });
+  });
+});
+
+describe('操作夹具', () => {
+  test('录制一次成功调用后 serializeFixture → parseFixtures 得到 operation 用例，凭证被遮蔽，expect.ok 等于输出', async () => {
+    const { result, exchanges } = await record({ sku: 'A-1', qty: 2 });
+    if (!result.ok || result.phase !== 'run') throw new Error('expected a successful run');
+    const files = serializeFixture('create-ok', { case: operationCase({ sku: 'A-1', qty: 2 }, { ok: result.output }), exchanges });
+    expect(files.map((file) => file.content).join('')).not.toContain('tok-12345');
+    const [fixture] = parseFixtures(files);
+    expect(fixture?.case).toEqual({ ...operationCase({ sku: 'A-1', qty: 2 }, { ok: { externalId: 'SO-1', status: 'created' } }), secrets: { token: '***' } });
+    expect(fixture?.exchanges).toEqual(exchanges);
+  });
+
+  test('回放不联网：成功与 REJECTED 用例都通过；输出与 expect.ok 不同时失败并给出差异', async () => {
+    const ok = await record({ sku: 'A-1', qty: 2 });
+    const rejected = await record({ sku: 'A-1', qty: 99 });
+    if (!ok.result.ok || ok.result.phase !== 'run') throw new Error('expected a successful run');
+    const files = [
+      ...serializeFixture('create-ok', { case: operationCase({ sku: 'A-1', qty: 2 }, { ok: ok.result.output }), exchanges: ok.exchanges }),
+      ...serializeFixture('create-rejected', { case: operationCase({ sku: 'A-1', qty: 99 }, { error: 'REJECTED' }), exchanges: rejected.exchanges }),
+      ...serializeFixture('create-wrong', { case: operationCase({ sku: 'A-1', qty: 2 }, { ok: { externalId: 'SO-2', status: 'created' } }), exchanges: ok.exchanges }),
+    ];
+    const results = await runFixtures(createInProcessExecutor(connector), DESCRIPTOR, files);
+    const byName = Object.fromEntries(results.map((item) => [item.name, item]));
+    expect(byName['create-ok']).toMatchObject({ ok: true, error: null, findings: [] });
+    expect(byName['create-rejected']).toMatchObject({ ok: true, error: null, findings: [] });
+    const wrong = byName['create-wrong'];
+    expect(wrong?.ok).toBe(false);
+    expect(wrong?.findings).toHaveLength(1);
+    expect(wrong?.findings[0]).toMatchObject({
+      code: 'EXPECTATION_FAILED',
+      detail: { differences: [{ path: 'output.externalId', expected: 'SO-2', actual: 'SO-1' }] },
+    });
+  });
+
+  test('期望失败码却成功、或请求与录制不符，都不通过', async () => {
+    const ok = await record({ sku: 'A-1', qty: 2 });
+    const files = [
+      ...serializeFixture('expect-error', { case: operationCase({ sku: 'A-1', qty: 2 }, { error: 'REJECTED' }), exchanges: ok.exchanges }),
+      ...serializeFixture('mismatch', { case: operationCase({ sku: 'B-2', qty: 2 }, { ok: { externalId: 'SO-1', status: 'created' } }), exchanges: ok.exchanges }),
+    ];
+    const results = await runFixtures(createInProcessExecutor(connector), DESCRIPTOR, files);
+    const byName = Object.fromEntries(results.map((item) => [item.name, item]));
+    expect(byName['expect-error']?.ok).toBe(false);
+    expect(byName['expect-error']?.findings.map((finding) => finding.code)).toEqual(['EXPECTATION_FAILED']);
+    expect(byName.mismatch?.ok).toBe(false);
+    expect(byName.mismatch?.findings.map((finding) => finding.code)).toContain('FIXTURE_EXCHANGE_MISMATCH');
+  });
+
+  test('operation 用例格式：expect 必填且二选一；未知字段报错', () => {
+    const write = (value: unknown) => [{ path: 'operations/create_order/tests/op/case.json', content: JSON.stringify(value) }];
+    const base = { params: {}, idempotencyKey: 'k', config: {} };
+    expect(() => parseFixtures(write(base))).toThrow(/expect/);
+    expect(() => parseFixtures(write({ ...base, expect: { ok: {}, error: 'REJECTED' } }))).toThrow(/exactly one/);
+    expect(() => parseFixtures(write({ ...base, expect: { error: 'REJECTED' }, extra: 1 }))).toThrow(/unknown field/);
+    expect(parseFixtures(write({ ...base, expect: { error: 'REJECTED' } }))[0]?.case).toMatchObject({ kind: 'operation', operation: 'create_order' });
+  });
+
+  test('serializeFixture 把操作用例写到 operations/<名>/tests/<用例名>/，case.json 不含 kind 与 operation', () => {
+    const files = serializeFixture('create-ok', { case: operationCase({ sku: 'A-1', qty: 2 }, { ok: {} }), exchanges: [] });
+    expect(files.map((file) => file.path)).toEqual(['operations/create_order/tests/create-ok/case.json']);
+    const written = JSON.parse(files[0]?.content ?? '{}') as Record<string, unknown>;
+    expect(Object.keys(written)).not.toContain('kind');
+    expect(Object.keys(written)).not.toContain('operation');
+  });
+});

package/test/testing/recorder.test.ts

@@ -0,0 +1,163 @@
+/**
+ * 录制：遮蔽规则（明文、凭证类头、句柄原样）、db 分页合并、crypto；经本地模拟网关端到端录制。
+ */
+import { describe, expect, test } from 'bun:test';
+import * as shared from '@mu-ontos/shared';
+import { defineStream } from '../../src';
+import {
+  createLocalGateway, createRecorder, parseFixtures, runStream, serializeFixture, type FixtureExchange, type LocalExchange,
+} from '../../src/testing';
+import { localPgUnavailable } from '../fixtures/acceptance';
+import { configField, descriptor, stream, table } from '../fixtures/descriptor';
+
+const pgUnavailable = await localPgUnavailable();
+if (pgUnavailable) console.warn(`[recorder] 本机 :15432 没有 Postgres，跳过真库用例：${pgUnavailable}`);
+
+const SECRETS = { token: 'abcd1234', pin: 'x1' };
+
+type HttpExchange = Extract<FixtureExchange, { kind: 'http' }>;
+type DbExchange = Extract<FixtureExchange, { kind: 'db' }>;
+
+describe('redaction while recording', () => {
+  test('plaintext secrets of 4+ bytes and credential headers become ***; handles and short secrets stay', async () => {
+    const seen: Array<{ url: string; authorization: string | null; body: string }> = [];
+    const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+      seen.push({ url: String(input), authorization: new Headers(init?.headers).get('authorization'), body: String(init?.body ? new TextDecoder().decode(init.body as Uint8Array) : '') });
+      return new Response(JSON.stringify({ echo: 'abcd1234', pin: 'x1' }), { headers: { 'content-type': 'application/json', 'set-cookie': 'sid=1' } });
+    }) as typeof fetch;
+    const secrets = { ...SECRETS, handle: 'h4ndle-secret' };
+    const recorder = createRecorder({ secrets });
+    const gateway = createLocalGateway({ hosts: ['api.example.com'], secrets, fetch: fetchImpl, onExchange: (exchange) => recorder.onExchange(exchange) });
+
+    type D = {
+      config: Record<never, never>; secrets: { token: string; pin: string; handle: string };
+      streams: { items: { tables: { item: { id: string } }; params: Record<never, never> } }; extensibleStreams: Record<never, never>; pushes: Record<never, never>; operations: Record<never, never>;
+    };
+    const connector = {
+      descriptor: descriptor({
+        name: 'redact', hosts: ['api.example.com'],
+        config: { token: configField('secret', { exposeToScript: true }), pin: configField('secret', { exposeToScript: true }), handle: configField('secret') },
+        streams: { items: stream({ item: table({ id: 'string' }, ['id']) }, { syncModes: ['full'] }) },
+      }),
+      implementations: {
+        streams: {
+          items: defineStream<D, 'items'>('items', async function* (ctx) {
+            await ctx.http.post('https://api.example.com/v1/items', {
+              query: { sig: ctx.secrets.handle, page: '1' },
+              headers: { authorization: `Bearer ${ctx.secrets.token}`, 'x-trace': `t-${ctx.secrets.token}`, 'x-pin': ctx.secrets.pin },
+              body: { handle: ctx.secrets.handle, pin: ctx.secrets.pin },
+            });
+            yield ctx.record('item', { id: '1' });
+          }),
+        },
+      },
+    };
+    const recorded = await runStream(connector, { stream: 'items', config: {}, host: gateway });
+    expect(recorded.error).toBeNull();
+    // 上游收到的是替换后的明文
+    expect(seen[0]?.authorization).toBe('Bearer abcd1234');
+    expect(seen[0]?.url).toContain('sig=h4ndle-secret');
+    expect(seen[0]?.body).toBe('{"handle":"h4ndle-secret","pin":"x1"}');
+
+    const [exchange] = recorder.exchanges() as HttpExchange[];
+    expect(exchange?.request.headers).toEqual({ authorization: '***', 'x-trace': 't-***', 'x-pin': 'x1', 'content-type': 'application/json' });
+    expect(exchange?.request.url).toBe('https://api.example.com/v1/items?page=1&sig=***');
+    expect(exchange?.request.body).toBe('{"handle":"ontos:secret:handle","pin":"x1"}');
+    expect(exchange?.response?.body).toBe('{"echo":"***","pin":"x1"}');
+    expect(exchange?.response?.headers['set-cookie']).toBe('***');
+    expect(JSON.stringify(recorder.exchanges())).not.toContain('abcd1234');
+    expect(JSON.stringify(recorder.exchanges())).not.toContain('h4ndle-secret');
+
+    const files = serializeFixture('redact', { case: { kind: 'pull', stream: 'items', mode: 'full', config: {}, secrets }, exchanges: recorder.exchanges() });
+    expect(JSON.parse(files[0]?.content ?? '{}').secrets).toEqual({ token: '***', pin: 'x1', handle: '***' });
+    expect(files.map((file) => file.content).join('')).not.toContain('abcd1234');
+    expect(parseFixtures(files)[0]?.exchanges).toEqual(recorder.exchanges());
+  });
+
+  test('the recorder applies the same header and URL rules as shared connector-redaction', () => {
+    const recorder = createRecorder({ secrets: SECRETS });
+    const headers = { Authorization: 'Bearer abcd1234', Cookie: 'a=b', 'X-Api-Key': 'k', 'Proxy-Authorization': 'p', 'X-Auth-Token': 'q', 'X-Other': 'abcd1234!' };
+    recorder.onExchange({
+      kind: 'http',
+      request: { method: 'GET', url: 'https://api.example.com/x?z=1&key=ontos%3Asecret%3Atoken', headers, query: { a: 'abcd1234' }, body: null, bodyEncoding: 'utf8' },
+      response: { status: 204, url: 'https://api.example.com/x', headers: {}, body: '', bodyEncoding: 'utf8' },
+      error: null,
+      durationMs: 1,
+    });
+    const [exchange] = recorder.exchanges() as HttpExchange[];
+    expect(exchange?.request.headers).toEqual(shared.redactHeaders(headers, Object.values(SECRETS)));
+    expect(exchange?.request.url).toBe('https://api.example.com/x?a=***&key=***&z=1');
+  });
+
+  test('errors are recorded with redacted messages; base64 bodies are kept as is', () => {
+    const recorder = createRecorder({ secrets: SECRETS });
+    recorder.onExchange({
+      kind: 'http',
+      request: { method: 'POST', url: 'https://api.example.com/x', headers: {}, query: {}, body: 'AAEC', bodyEncoding: 'base64' },
+      response: null,
+      error: { code: 'EGRESS_UPSTREAM_FAILED', message: 'failed for abcd1234' },
+      durationMs: 1,
+    });
+    expect(recorder.exchanges()).toEqual([{
+      seq: 1, kind: 'http',
+      request: { method: 'POST', url: 'https://api.example.com/x', headers: {}, body: 'AAEC', bodyEncoding: 'base64' },
+      response: null,
+      error: { code: 'EGRESS_UPSTREAM_FAILED', message: 'failed for ***' },
+    }]);
+  });
+});
+
+describe('db and crypto', () => {
+  const page = (rows: number[], cursorId: string | null, done: boolean) => ({ cursorId, fields: [{ name: 'n', dataTypeId: 23 }], rows: rows.map((n) => ({ n })), done });
+
+  test('a query fetched in 3 pages becomes one db exchange holding every row', () => {
+    const recorder = createRecorder({ secrets: SECRETS });
+    const exchanges: LocalExchange[] = [
+      { kind: 'db', request: { sql: 'select n from t where k = $1', params: ['abcd1234'] }, response: page([1, 2], 'c1', false), error: null, durationMs: 1 },
+      { kind: 'db', request: { cursorId: 'c1' }, response: { rows: [{ n: 3 }, { n: 4 }], done: false }, error: null, durationMs: 1 },
+      { kind: 'crypto', request: { op: 'hash', algorithm: 'sha256', data: 'ontos:secret:token', encoding: 'hex' }, response: { value: 'h' }, error: null, durationMs: 1 },
+      { kind: 'db', request: { cursorId: 'c1' }, response: { rows: [{ n: 5 }], done: true }, error: null, durationMs: 1 },
+    ];
+    for (const exchange of exchanges) recorder.onExchange(exchange);
+    expect(recorder.exchanges()).toEqual([
+      { seq: 1, kind: 'db', sql: 'select n from t where k = $1', params: ['***'], fields: [{ name: 'n', dataTypeId: 23 }], rows: [1, 2, 3, 4, 5].map((n) => ({ n })), error: null },
+      { seq: 2, kind: 'crypto', request: { op: 'hash', algorithm: 'sha256', data: 'ontos:secret:token', encoding: 'hex' }, value: 'h' },
+    ]);
+  });
+
+  test('a cursor that fails midway keeps the rows fetched so far and the error', () => {
+    const recorder = createRecorder({ secrets: {} });
+    recorder.onExchange({ kind: 'db', request: { sql: 'select 1', params: [] }, response: page([1], 'c9', false), error: null, durationMs: 1 });
+    recorder.onExchange({ kind: 'db', request: { cursorId: 'c9' }, response: null, error: { code: 'DB_PROXY_FAILED', message: 'boom' }, durationMs: 1 });
+    recorder.onExchange({ kind: 'db', request: { cursorId: 'c9' }, response: { rows: [{ n: 2 }], done: true }, error: null, durationMs: 1 });
+    const [exchange] = recorder.exchanges() as DbExchange[];
+    expect(exchange?.rows).toEqual([{ n: 1 }]);
+    expect(exchange?.error).toEqual({ code: 'DB_PROXY_FAILED', message: 'boom' });
+  });
+
+  // 本机没有 :15432 的 Postgres 时跳过
+  test.skipIf(Boolean(pgUnavailable))('a real Postgres (localhost:15432) query read in 3 cursor pages is recorded as one exchange', async () => {
+    const recorder = createRecorder({ secrets: {} });
+    const gateway = createLocalGateway({
+      hosts: [], secrets: {}, db: { host: 'localhost', port: 15432, database: 'postgres', user: 'admin', password: 'password' },
+      onExchange: (exchange) => recorder.onExchange(exchange),
+    });
+    try {
+      let response = await gateway.call('db.query', {
+        sql: 'select n from generate_series(1, 2500) as n', params: [],
+      }) as { cursorId: string | null; done: boolean };
+      let pages = 1;
+      while (!response.done && response.cursorId) {
+        response = { ...(await gateway.call('db.next', { cursorId: response.cursorId }) as { done: boolean }), cursorId: response.cursorId };
+        pages += 1;
+      }
+      expect(pages).toBe(3);
+      const exchanges = recorder.exchanges() as DbExchange[];
+      expect(exchanges).toHaveLength(1);
+      expect(exchanges[0]?.rows).toHaveLength(2500);
+      expect(exchanges[0]?.rows[2499]).toEqual({ n: 2500 });
+    } finally {
+      await gateway.close();
+    }
+  });
+});

package/test/testing/redaction.test.ts

@@ -0,0 +1,54 @@
+/**
+ * SDK 的遮蔽实现与 shared `connector-redaction.ts` 的对照：SDK 不能依赖 shared，两份实现的结论必须一致。
+ */
+import { describe, expect, test } from 'bun:test';
+import * as shared from '@mu-ontos/shared';
+import { CREDENTIAL_HEADER_NAMES, redactHeaders, redactQuery, redactSecretValues, redactUrl } from '../../src/testing';
+
+const SECRETS = ['abcd1234', 'abcd', 'x1', 'longer-secret-value'];
+
+const TEXT_SAMPLES = [
+  'Bearer abcd1234',
+  'token=abcd&other=abcd1234',
+  'pin x1 stays',
+  'nested longer-secret-value and abcd',
+  '',
+  'no secrets here',
+];
+
+const HEADER_SAMPLES: Array<Record<string, string>> = [
+  { Authorization: 'Bearer abcd1234', 'X-Trace': 'abcd1234-trace' },
+  { cookie: 'session=1', 'set-cookie': 'a=b', 'X-API-Key': 'k', 'content-type': 'application/json' },
+  { 'x-auth-token': 'ontos:secret:token', accept: 'x1' },
+];
+
+describe('redaction matches shared connector-redaction', () => {
+  test('credential header names are identical', () => {
+    expect([...CREDENTIAL_HEADER_NAMES]).toEqual([...shared.CREDENTIAL_HEADER_NAMES]);
+  });
+
+  test.each(TEXT_SAMPLES)('redactSecretValues(%p)', (text) => {
+    expect(redactSecretValues(text, SECRETS)).toBe(shared.redactSecretValues(text, SECRETS));
+  });
+
+  test.each(HEADER_SAMPLES)('redactHeaders(%p)', (headers) => {
+    expect(redactHeaders(headers, SECRETS)).toEqual(shared.redactHeaders(headers, SECRETS));
+  });
+
+  test('longer secrets are replaced first and short values stay', () => {
+    expect(redactSecretValues('abcd1234 abcd x1', SECRETS)).toBe('*** *** x1');
+  });
+});
+
+describe('query and url redaction', () => {
+  test('query values that contain a secret handle are masked; the handle form is never revealed', () => {
+    expect(redactQuery({ token: 'ontos:secret:token', page: '2', list: ['a', 'ontos:secret:x'] }, [])).toEqual({
+      token: '***', page: '2', list: ['a', '***'],
+    });
+  });
+
+  test('url query handles and plaintext secrets are masked', () => {
+    expect(redactUrl('https://api.example.com/x?key=ontos%3Asecret%3Atoken&p=1', [])).toBe('https://api.example.com/x?key=***&p=1');
+    expect(redactUrl('https://api.example.com/abcd1234/x', SECRETS)).toBe('https://api.example.com/***/x');
+  });
+});

package/test/testing/replay.test.ts

@@ -0,0 +1,207 @@
+/**
+ * 用例回放：按序应答、不匹配时报错且绝不联网、未用往来、secret / cache / crypto / db 的应答。
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { defineStream, type ConnectorDescriptor } from '../../src';
+import {
+  createInProcessExecutor, createReplayHost, FixtureReplayError, runFixture, type FixtureExchange, type LoadedFixture,
+} from '../../src/testing';
+import { HTTP_PULL_DIR } from '../fixtures/acceptance';
+import { configField, descriptor, stream, table } from '../fixtures/descriptor';
+
+const CONFIG = { baseUrl: 'https://api.example.com/v1' };
+
+function httpExchange(seq: number, url: string, body: unknown): FixtureExchange {
+  return {
+    seq, kind: 'http',
+    request: { method: 'GET', url, headers: { authorization: '***' }, body: null, bodyEncoding: 'utf8' },
+    response: { status: 200, headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), bodyEncoding: 'utf8' },
+    error: null,
+  };
+}
+
+const TWO_PAGES: FixtureExchange[] = [
+  httpExchange(1, 'https://api.example.com/v1/items', { items: [{ id: 'a', name: 'A', updatedAt: '2026-10-01T00:00:00Z' }], nextCursor: 'p2' }),
+  httpExchange(2, 'https://api.example.com/v1/items?cursor=p2', { items: [{ id: 'b', name: 'B', updatedAt: '2026-10-02T00:00:00Z' }], nextCursor: null }),
+];
+
+function pullFixture(exchanges: FixtureExchange[], overrides: Partial<Extract<LoadedFixture['case'], { kind: 'pull' }>> = {}): LoadedFixture {
+  return { capability: 'streams/items', name: 'basic', case: { kind: 'pull', stream: 'items', mode: 'incremental', config: CONFIG, secrets: { token: '***' }, ...overrides }, exchanges, requests: [] };
+}
+
+const HTTP_PULL_DESCRIPTOR = JSON.parse(await Bun.file(path.join(HTTP_PULL_DIR, '.ontos/descriptor.json')).text()) as ConnectorDescriptor;
+
+/** 验收连接器 http_pull 的进程内执行器。 */
+async function httpPull() {
+  const items = ((await import(path.join(HTTP_PULL_DIR, 'streams/items/index.ts'))) as { default: unknown }).default;
+  return createInProcessExecutor({ descriptor: HTTP_PULL_DESCRIPTOR, implementations: { streams: { items } } });
+}
+
+/** 回放期间把全局 fetch 换成会抛错的替身，记下有没有被调用。 */
+let fetchCalls = 0;
+const realFetch = globalThis.fetch;
+beforeEach(() => {
+  fetchCalls = 0;
+  globalThis.fetch = (async () => {
+    fetchCalls += 1;
+    throw new Error('fixture replay must never reach the network');
+  }) as unknown as typeof fetch;
+});
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('http', () => {
+  test('two recorded GETs answer the same two requests in order; nothing is left unused', async () => {
+    const fixture = pullFixture(TWO_PAGES);
+    const host = createReplayHost(fixture);
+    const request = (url: string, query: Record<string, string> = {}) => ({
+      method: 'GET', url, headers: { authorization: 'Bearer ontos:secret:token' }, query, body: null, bodyEncoding: 'utf8',
+    });
+    const first = await host.call('http', request('https://api.example.com/v1/items')) as { status: number; body: string; url: string };
+    expect(first.status).toBe(200);
+    expect(JSON.parse(first.body).nextCursor).toBe('p2');
+    expect(first.url).toBe('https://api.example.com/v1/items');
+    const second = await host.call('http', request('https://api.example.com/v1/items', { cursor: 'p2' })) as { body: string };
+    expect(JSON.parse(second.body).nextCursor).toBeNull();
+    expect(host.unused()).toEqual([]);
+    expect(host.mismatches()).toEqual([]);
+
+    const result = await runFixture(await httpPull(), HTTP_PULL_DESCRIPTOR, fixture);
+    expect(result).toMatchObject({ name: 'basic', ok: true, findings: [], error: null, stats: { records: { items: 2 }, checkpoints: 2 } });
+    expect(fetchCalls).toBe(0);
+  });
+
+  test('a request the fixture does not have fails with FIXTURE_EXCHANGE_MISMATCH and never reaches fetch', async () => {
+    const host = createReplayHost(pullFixture(TWO_PAGES));
+    const base = { headers: {}, query: {}, bodyEncoding: 'utf8' };
+    const codeOf = (payload: unknown) => host.call('http', payload).then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(await codeOf({ ...base, method: 'POST', url: 'https://api.example.com/v1/items', body: null })).toBe('FIXTURE_EXCHANGE_MISMATCH');
+    expect(await codeOf({ ...base, method: 'GET', url: 'https://api.example.com/v1/other', body: null })).toBe('FIXTURE_EXCHANGE_MISMATCH');
+    expect(await codeOf({ ...base, method: 'GET', url: 'https://api.example.com/v1/items', body: '{"x":1}' })).toBe('FIXTURE_EXCHANGE_MISMATCH');
+    expect(host.mismatches().map((item) => item.method)).toEqual(['http', 'http', 'http']);
+    expect(host.unused()).toHaveLength(2);
+
+    // 连接器发出夹具里没有的请求（第二页的游标不同）：运行失败，结果带 FIXTURE_EXCHANGE_MISMATCH
+    const fixture = pullFixture([TWO_PAGES[0] as FixtureExchange, httpExchange(2, 'https://api.example.com/v1/items?cursor=p9', { items: [], nextCursor: null })]);
+    const result = await runFixture(await httpPull(), HTTP_PULL_DESCRIPTOR, fixture);
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toBeNull();
+    expect(result.findings.map((finding) => finding.code)).toEqual(['FIXTURE_EXCHANGE_MISMATCH']);
+    expect(String((result.findings[0]?.detail as { detail: string }).detail)).toContain('cursor=p2');
+    expect(fetchCalls).toBe(0);
+  });
+
+  test('an unused recorded exchange is reported, but the case still passes', async () => {
+    const fixture = pullFixture([...TWO_PAGES, httpExchange(3, 'https://api.example.com/v1/extra', {})]);
+    const result = await runFixture(await httpPull(), HTTP_PULL_DESCRIPTOR, fixture);
+    expect(result.ok).toBe(true);
+    expect(result.findings.map((finding) => finding.code)).toEqual(['FIXTURE_EXCHANGE_UNUSED']);
+    expect(result.findings[0]?.detail).toEqual({ seq: 3, kind: 'http' });
+  });
+
+  test('a recorded error is replayed as the same host call failure', async () => {
+    const host = createReplayHost(pullFixture([{
+      seq: 1, kind: 'http', request: { method: 'GET', url: 'https://api.example.com/x', headers: {}, body: null, bodyEncoding: 'utf8' },
+      response: null, error: { code: 'EGRESS_TIMEOUT', message: 'The outbound request timed out' },
+    }]));
+    const error = await host.call('http', { method: 'GET', url: 'https://api.example.com/x', headers: {}, query: {}, body: null, bodyEncoding: 'utf8' })
+      .then(() => null, (caught: unknown) => caught as FixtureReplayError);
+    expect(error?.code).toBe('EGRESS_TIMEOUT');
+    expect(host.unused()).toEqual([]);
+  });
+});
+
+describe('secret, cache and crypto', () => {
+  test('secret.reveal answers from case.secrets (even ***); cache lives for one replay', async () => {
+    const fixture = pullFixture([], { secrets: { token: '***', pin: 'x1' } });
+    const host = createReplayHost(fixture);
+    expect(await host.call('secret.reveal', { field: 'token' })).toEqual({ value: '***' });
+    expect(await host.call('secret.reveal', { field: 'pin' })).toEqual({ value: 'x1' });
+    const missing = await host.call('secret.reveal', { field: 'other' }).then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(missing).toBe('EGRESS_SECRET_UNAVAILABLE');
+    expect(await host.call('cache.get', { key: 'k' })).toBeNull();
+    await host.call('cache.set', { key: 'k', value: 'v', ttlSeconds: 60 });
+    expect(await host.call('cache.get', { key: 'k' })).toMatchObject({ value: 'v' });
+    expect(await createReplayHost(fixture).call('cache.get', { key: 'k' })).toBeNull();
+  });
+
+  test('crypto: recorded results first, hash computed locally, an unrecorded hmac or sign is a mismatch', async () => {
+    const hmac = { op: 'hmac', algorithm: 'sha256', key: 'ontos:secret:token', data: 'payload', encoding: 'hex' } as const;
+    const host = createReplayHost(pullFixture([{ seq: 1, kind: 'crypto', request: hmac, value: 'recorded-signature' }], { secrets: { token: '***' } }));
+    expect(await host.call('crypto', hmac)).toEqual({ value: 'recorded-signature' });
+    expect(await host.call('crypto', { op: 'hash', algorithm: 'sha256', data: 'abc', encoding: 'hex' }))
+      .toEqual({ value: createHash('sha256').update('abc').digest('hex') });
+    expect(await host.call('crypto', { op: 'hash', algorithm: 'md5', data: 'k=ontos:secret:token', encoding: 'base64' }))
+      .toEqual({ value: createHash('md5').update('k=***').digest('base64') });
+    const again = await host.call('crypto', hmac).then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(again).toBe('FIXTURE_EXCHANGE_MISMATCH');
+    const sign = await host.call('crypto', { op: 'sign', algorithm: 'rsa-sha256', key: 'k', data: 'd', encoding: 'base64' })
+      .then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(sign).toBe('FIXTURE_EXCHANGE_MISMATCH');
+  });
+
+  test('a connector that signs requests replays from recorded crypto exchanges in process', async () => {
+    type D = {
+      config: Record<never, never>; secrets: { key: string };
+      streams: { items: { tables: { item: { sig: string } }; params: Record<never, never> } }; extensibleStreams: Record<never, never>; pushes: Record<never, never>; operations: Record<never, never>;
+    };
+    const signer = descriptor({
+      name: 'signer', config: { key: configField('secret') }, hosts: ['api.example.com'],
+      streams: { items: stream({ item: table({ sig: 'string' }, ['sig']) }, { syncModes: ['full'] }) },
+    });
+    const connector = {
+      descriptor: signer,
+      implementations: {
+        streams: {
+          items: defineStream<D, 'items'>('items', async function* (ctx) {
+            const sig = await ctx.crypto.hmac('sha256', ctx.secrets.key, 'payload');
+            yield ctx.record('item', { sig });
+          }),
+        },
+      },
+    };
+    const fixture: LoadedFixture = {
+      capability: 'streams/items',
+      name: 'sign',
+      case: { kind: 'pull', stream: 'items', mode: 'incremental', config: {}, secrets: { key: '***' }, expect: { records: { item: 1 } } },
+      exchanges: [{ seq: 1, kind: 'crypto', request: { op: 'hmac', algorithm: 'sha256', key: 'ontos:secret:key', data: 'payload', encoding: 'hex' }, value: 'beef' }],
+      requests: [],
+    };
+    const result = await runFixture(createInProcessExecutor(connector), signer, fixture);
+    expect(result.error).toBeNull();
+    expect(result.ok).toBe(true);
+    expect(result.findings).toEqual([]);
+  });
+});
+
+describe('db', () => {
+  const dbExchange = (seq: number, sql: string, params: unknown[], rows: number[], error: { code: string; message: string } | null = null): FixtureExchange => ({
+    seq, kind: 'db', sql, params, fields: rows.length > 0 ? [{ name: 'n', dataTypeId: 23 }] : [], rows: rows.map((n) => ({ n })), error,
+  });
+
+  test('a query is answered with every recorded row in one page, matched by SQL and parameters', async () => {
+    const host = createReplayHost(pullFixture([dbExchange(1, 'select n from t where k = $1', ['a'], [1, 2, 3])]));
+    const miss = await host.call('db.query', { sql: 'select n from t where k = $1', params: ['b'] }).then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(miss).toBe('FIXTURE_EXCHANGE_MISMATCH');
+    expect(await host.call('db.query', { sql: 'select n from t where k = $1', params: ['a'] }))
+      .toEqual({ cursorId: null, fields: [{ name: 'n', dataTypeId: 23 }], rows: [{ n: 1 }, { n: 2 }, { n: 3 }], done: true });
+    expect(host.unused()).toEqual([]);
+  });
+
+  test('a recorded failure: a failed query throws; a cursor that failed midway returns its rows, then db.next throws', async () => {
+    const host = createReplayHost(pullFixture([
+      dbExchange(1, 'select broken', [], [], { code: 'DB_PROXY_FAILED', message: 'syntax error' }),
+      dbExchange(2, 'select n', [], [1], { code: 'DB_PROXY_FAILED', message: 'connection lost' }),
+    ]));
+    const failed = await host.call('db.query', { sql: 'select broken', params: [] }).then(() => null, (error: unknown) => (error as FixtureReplayError).code);
+    expect(failed).toBe('DB_PROXY_FAILED');
+    const partial = await host.call('db.query', { sql: 'select n', params: [] }) as { cursorId: string; rows: unknown[]; done: boolean };
+    expect(partial.rows).toEqual([{ n: 1 }]);
+    expect(partial.done).toBe(false);
+    const next = await host.call('db.next', { cursorId: partial.cursorId }).then(() => null, (error: unknown) => (error as FixtureReplayError).message);
+    expect(next).toBe('connection lost');
+  });
+});