@deepexi/datasense-connector 0.0.0-stage → 3.1.0

package/src/testing/fixtures.ts

@@ -0,0 +1,591 @@
+/**
+ * 测试用例格式（CLI 录制写、`runTests` 读、runner 服务端回放读，共享值域）。
+ *
+ * 用例放在能力目录下：`<streams|pushes|operations>/<名>/tests/<用例名>/`：
+ * - `case.json`（必有）：用例种类与所属能力由所在目录推出，文件里不写 `kind` / `stream` / `push` / `operation`；
+ *   唯一例外是数据流目录下的建议列用例，写 `"kind": "suggest"`；
+ * - `exchanges.ndjson`（可选）：每行一个 `FixtureExchange`，`seq` 严格递增；
+ * - `requests.ndjson`（推送用例必有，其他用例不能有）：每行一个 `FixtureRequest`。
+ *
+ * 用例种类：数据流目录下是 `pull`（或 `suggest`），推送目录下是 `push`，操作目录下是 `operation`（回放一次 `run`，`expect` 必填）。
+ *
+ * 用例名 `^[a-z0-9][a-z0-9_-]{0,63}$`。夹具里长度 ≥ 4 的 Secret 明文在录制时已替换为 `***`，凭证句柄
+ * `ontos:secret:<field>` 保持原样（见 `recorder.ts`）。NDJSON 每行以 `\n` 结尾，键按插入顺序输出（便于 diff）。
+ *
+ * 本文件除 `readFixtureDir`（动态导入 `node:fs`）外不依赖 Node 模块。
+ */
+import type { SuggestedColumn } from '../descriptor';
+import type { CryptoRequest } from '../runtime/protocol';
+import { REDACT_MIN_LENGTH, REDACTED } from './redaction';
+
+/** 用例目录里的一个文件；`path` 相对源码根目录，如 `streams/orders/tests/basic/case.json`（与 shared 的同名类型同形）。 */
+export interface ConnectorFixtureFile { path: string; content: string }
+
+/**
+ * 用例的期望（全部可选，给出的每一项都必须精确相等，否则 `EXPECTATION_FAILED`）：
+ * - `records` / `removals`：表 → 条数（只比较给出的表）；
+ * - `rejected`：推送拒收条数；`checkpoints`：断点个数。
+ */
+export interface FixtureExpectation { records?: Record<string, number>; removals?: Record<string, number>; rejected?: number; checkpoints?: number }
+
+/**
+ * 连接器操作用例的期望（必填，二选一）：`ok` 为 `run` 的输出（按值精确比较），`error` 为失败码（如 `REJECTED`）。
+ */
+export type OperationFixtureExpectation = { ok: Record<string, unknown> } | { error: string };
+
+/** 建议列用例的期望：`columns` 与建议结果按列名对齐后逐项精确比较（顺序不计）。 */
+export interface SuggestFixtureExpectation { columns: SuggestedColumn[] }
+
+/**
+ * 解析后的用例（内存形态，`kind` 与能力名由目录推出后补上）；`secrets` 是字段 → 值（录制后长度 ≥ 4 的值为 `***`），回放时 `secret.reveal` 照给。
+ */
+export type FixtureCase =
+  | {
+    kind: 'pull'; stream: string; mode: 'full' | 'incremental'; state?: unknown; streamConfig?: Record<string, unknown>;
+    config: Record<string, unknown>; secrets?: Record<string, string>; limit?: number; expect?: FixtureExpectation;
+  }
+  | { kind: 'push'; push: string; config: Record<string, unknown>; secrets?: Record<string, string>; expect?: FixtureExpectation }
+  | {
+    kind: 'operation'; operation: string; params: Record<string, unknown>; idempotencyKey: string;
+    config: Record<string, unknown>; secrets?: Record<string, string>; expect: OperationFixtureExpectation;
+  }
+  | { kind: 'suggest'; stream: string; table: string; config: Record<string, unknown>; secrets?: Record<string, string>; expect: SuggestFixtureExpectation };
+
+/**
+ * 一次宿主往来：
+ * - `http`：`request.url` 已并入 query 并按键排序、含句柄的 query 值为 `***`；凭证类头为 `***`；body 里的句柄原样保留；
+ * - `db`：一次查询的全部分页合成一条，`rows` 为全部行；
+ * - `crypto`：请求（key / data 里的句柄原样）与结果。
+ */
+export type FixtureExchange =
+  | {
+    seq: number; kind: 'http';
+    request: { method: string; url: string; headers: Record<string, string>; body: string | null; bodyEncoding: 'utf8' | 'base64' };
+    response: { status: number; headers: Record<string, string>; body: string; bodyEncoding: 'utf8' | 'base64' } | null;
+    error: { code: string; message: string } | null;
+  }
+  | {
+    seq: number; kind: 'db'; sql: string; params: unknown[]; fields: Array<{ name: string; dataTypeId: number }>;
+    rows: Array<Record<string, unknown>>; error: { code: string; message: string } | null;
+  }
+  | { seq: number; kind: 'crypto'; request: CryptoRequest; value: string };
+
+/** 推送用例重放的一条收件箱请求。 */
+export interface FixtureRequest { requestId: string; receivedAt: string; headers: Record<string, string>; body: string }
+
+/** `capability` 形如 `streams/orders`、`pushes/order_events`、`operations/create_followup`。 */
+export interface LoadedFixture { capability: string; name: string; case: FixtureCase; exchanges: FixtureExchange[]; requests: FixtureRequest[] }
+
+/** 夹具格式错误：`file` 为相对源码根目录的路径，`line` 为 NDJSON 的行号（从 1 起；与整个文件相关时为 null）。 */
+export class FixtureFormatError extends Error {
+  readonly file: string;
+  readonly line: number | null;
+
+  constructor(message: string, file: string, line: number | null = null) {
+    super(line === null ? `${file}: ${message}` : `${file}:${line}: ${message}`);
+    this.name = 'FixtureFormatError';
+    this.file = file;
+    this.line = line;
+  }
+}
+
+export const FIXTURE_CASE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** 能力目录下放用例的子目录名。 */
+export const TESTS_DIR = 'tests';
+
+type CapabilityGroup = 'streams' | 'pushes' | 'operations';
+const CAPABILITY_GROUPS: readonly CapabilityGroup[] = ['streams', 'pushes', 'operations'];
+const CAPABILITY_NAME_PATTERN: Record<CapabilityGroup, RegExp> = {
+  streams: /^[a-z][a-z0-9_]{0,27}$/,
+  pushes: /^[a-z][a-z0-9_]{0,27}$/,
+  operations: /^[a-z][a-z0-9_]{0,62}$/,
+};
+const COLUMN_TYPES: readonly string[] = ['string', 'integer', 'decimal', 'boolean', 'date', 'instant', 'json'];
+
+const CASE_FILE = 'case.json';
+const EXCHANGES_FILE = 'exchanges.ndjson';
+const REQUESTS_FILE = 'requests.ndjson';
+const CASE_FILES: ReadonlySet<string> = new Set([CASE_FILE, EXCHANGES_FILE, REQUESTS_FILE]);
+
+// ---------------------------------------------------------------------------
+// 结构校验
+
+/** 校验失败：消息交给调用方补上文件与行号。 */
+class ShapeError extends Error {}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fail(message: string): never {
+  throw new ShapeError(message);
+}
+
+function onlyKeys(value: Record<string, unknown>, allowed: readonly string[], where: string): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) fail(`${where} has an unknown field "${key}"`);
+  }
+}
+
+function requireString(value: unknown, where: string): string {
+  if (typeof value !== 'string') fail(`${where} must be a string`);
+  return value;
+}
+
+function requireNonEmptyString(value: unknown, where: string): string {
+  const text = requireString(value, where);
+  if (text === '') fail(`${where} must not be empty`);
+  return text;
+}
+
+function requireRecord(value: unknown, where: string): Record<string, unknown> {
+  if (!isRecord(value)) fail(`${where} must be an object`);
+  return value;
+}
+
+function requireStringRecord(value: unknown, where: string): Record<string, string> {
+  const record = requireRecord(value, where);
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item !== 'string') fail(`${where}.${key} must be a string`);
+  }
+  return record as Record<string, string>;
+}
+
+function requireCount(value: unknown, where: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) fail(`${where} must be a non-negative integer`);
+  return value;
+}
+
+function requireError(value: unknown, where: string): void {
+  if (value === null) return;
+  const error = requireRecord(value, where);
+  onlyKeys(error, ['code', 'message'], where);
+  requireString(error.code, `${where}.code`);
+  requireString(error.message, `${where}.message`);
+}
+
+function requireEncoding(value: unknown, where: string): void {
+  if (value !== 'utf8' && value !== 'base64') fail(`${where} must be "utf8" or "base64"`);
+}
+
+function validateExpectation(value: unknown): void {
+  const expectation = requireRecord(value, 'expect');
+  onlyKeys(expectation, ['records', 'removals', 'rejected', 'checkpoints'], 'expect');
+  for (const field of ['records', 'removals'] as const) {
+    if (expectation[field] === undefined) continue;
+    for (const [table, count] of Object.entries(requireRecord(expectation[field], `expect.${field}`))) requireCount(count, `expect.${field}.${table}`);
+  }
+  if (expectation.rejected !== undefined) requireCount(expectation.rejected, 'expect.rejected');
+  if (expectation.checkpoints !== undefined) requireCount(expectation.checkpoints, 'expect.checkpoints');
+}
+
+function validateOperationExpectation(value: unknown): void {
+  const expectation = requireRecord(value, 'expect');
+  onlyKeys(expectation, ['ok', 'error'], 'expect');
+  if ((expectation.ok === undefined) === (expectation.error === undefined)) fail('expect must have exactly one of "ok" and "error"');
+  if (expectation.ok !== undefined) requireRecord(expectation.ok, 'expect.ok');
+  else requireNonEmptyString(expectation.error, 'expect.error');
+}
+
+function validateSuggestExpectation(value: unknown): void {
+  const expectation = requireRecord(value, 'expect');
+  onlyKeys(expectation, ['columns'], 'expect');
+  if (!Array.isArray(expectation.columns)) fail('expect.columns must be an array of columns');
+  expectation.columns.forEach((item: unknown, i) => {
+    const where = `expect.columns[${i}]`;
+    const column = requireRecord(item, where);
+    onlyKeys(column, ['name', 'type', 'precision', 'scale', 'title', 'description'], where);
+    requireNonEmptyString(column.name, `${where}.name`);
+    if (typeof column.type !== 'string' || !COLUMN_TYPES.includes(column.type)) fail(`${where}.type must be a column type`);
+    requireString(column.title, `${where}.title`);
+    if (column.description !== undefined) requireString(column.description, `${where}.description`);
+    for (const key of ['precision', 'scale'] as const) {
+      if (column[key] !== undefined) requireCount(column[key], `${where}.${key}`);
+    }
+  });
+}
+
+/** 校验 `case.json`（文件形态：不写 `kind` 与能力名，建议列用例写 `"kind": "suggest"`），返回补上 `kind` 与能力名的用例。 */
+function validateCase(value: unknown, group: CapabilityGroup, capabilityName: string): FixtureCase {
+  const item = requireRecord(value, 'case');
+  const common = ['config', 'secrets', 'expect'];
+  const finish = (): void => {
+    requireRecord(item.config, 'config');
+    if (item.secrets !== undefined) requireStringRecord(item.secrets, 'secrets');
+  };
+  if (group === 'operations') {
+    if (item.kind !== undefined) fail('case.json under operations/ must not set "kind" (it follows from the directory)');
+    onlyKeys(item, [...common, 'params', 'idempotencyKey'], 'case');
+    requireRecord(item.params, 'params');
+    requireNonEmptyString(item.idempotencyKey, 'idempotencyKey');
+    finish();
+    if (item.expect === undefined) fail('operation cases need expect: { ok } or { error }');
+    validateOperationExpectation(item.expect);
+    return { ...item, kind: 'operation', operation: capabilityName } as unknown as FixtureCase;
+  }
+  if (group === 'pushes') {
+    if (item.kind !== undefined) fail('case.json under pushes/ must not set "kind" (it follows from the directory)');
+    onlyKeys(item, common, 'case');
+    finish();
+    if (item.expect !== undefined) validateExpectation(item.expect);
+    return { ...item, kind: 'push', push: capabilityName } as unknown as FixtureCase;
+  }
+  if (item.kind === 'suggest') {
+    onlyKeys(item, ['kind', ...common, 'table'], 'case');
+    requireNonEmptyString(item.table, 'table');
+    finish();
+    if (item.expect === undefined) fail('suggest cases need expect: { columns }');
+    validateSuggestExpectation(item.expect);
+    return { ...item, kind: 'suggest', stream: capabilityName } as unknown as FixtureCase;
+  }
+  if (item.kind !== undefined) fail('case.json under streams/ may only set "kind": "suggest" (other kinds follow from the directory)');
+  onlyKeys(item, [...common, 'mode', 'state', 'streamConfig', 'limit'], 'case');
+  if (item.mode !== 'full' && item.mode !== 'incremental') fail('mode must be "full" or "incremental"');
+  if (item.streamConfig !== undefined) requireRecord(item.streamConfig, 'streamConfig');
+  if (item.limit !== undefined && (typeof item.limit !== 'number' || !Number.isSafeInteger(item.limit) || item.limit <= 0)) fail('limit must be a positive integer');
+  finish();
+  if (item.expect !== undefined) validateExpectation(item.expect);
+  return { ...item, kind: 'pull', stream: capabilityName } as unknown as FixtureCase;
+}
+
+function validateCryptoRequest(value: unknown): void {
+  const request = requireRecord(value, 'request');
+  requireString(request.data, 'request.data');
+  if (request.encoding !== 'hex' && request.encoding !== 'base64') fail('request.encoding must be "hex" or "base64"');
+  switch (request.op) {
+    case 'hash':
+      onlyKeys(request, ['op', 'algorithm', 'data', 'encoding'], 'request');
+      if (!['md5', 'sha1', 'sha256', 'sha512'].includes(String(request.algorithm))) fail('request.algorithm is not a hash algorithm');
+      return;
+    case 'hmac':
+      onlyKeys(request, ['op', 'algorithm', 'key', 'data', 'encoding'], 'request');
+      requireString(request.key, 'request.key');
+      if (!['sha1', 'sha256', 'sha512'].includes(String(request.algorithm))) fail('request.algorithm is not an hmac algorithm');
+      return;
+    case 'sign':
+      onlyKeys(request, ['op', 'algorithm', 'key', 'data', 'encoding'], 'request');
+      requireString(request.key, 'request.key');
+      if (request.algorithm !== 'rsa-sha256') fail('request.algorithm must be "rsa-sha256"');
+      return;
+    default:
+      fail('request.op must be one of "hmac", "sign", "hash"');
+  }
+}
+
+function validateExchange(value: unknown): FixtureExchange {
+  const item = requireRecord(value, 'exchange');
+  if (typeof item.seq !== 'number' || !Number.isSafeInteger(item.seq) || item.seq <= 0) fail('seq must be a positive integer');
+  switch (item.kind) {
+    case 'http': {
+      onlyKeys(item, ['seq', 'kind', 'request', 'response', 'error'], 'exchange');
+      const request = requireRecord(item.request, 'request');
+      onlyKeys(request, ['method', 'url', 'headers', 'body', 'bodyEncoding'], 'request');
+      requireNonEmptyString(request.method, 'request.method');
+      requireNonEmptyString(request.url, 'request.url');
+      requireStringRecord(request.headers, 'request.headers');
+      if (request.body !== null) requireString(request.body, 'request.body');
+      requireEncoding(request.bodyEncoding, 'request.bodyEncoding');
+      if (item.response !== null) {
+        const response = requireRecord(item.response, 'response');
+        onlyKeys(response, ['status', 'headers', 'body', 'bodyEncoding'], 'response');
+        if (typeof response.status !== 'number' || !Number.isInteger(response.status)) fail('response.status must be an integer');
+        requireStringRecord(response.headers, 'response.headers');
+        requireString(response.body, 'response.body');
+        requireEncoding(response.bodyEncoding, 'response.bodyEncoding');
+      }
+      requireError(item.error, 'error');
+      if ((item.response === null) === (item.error === null)) fail('exactly one of response and error must be null');
+      break;
+    }
+    case 'db': {
+      onlyKeys(item, ['seq', 'kind', 'sql', 'params', 'fields', 'rows', 'error'], 'exchange');
+      requireString(item.sql, 'sql');
+      if (!Array.isArray(item.params)) fail('params must be an array');
+      if (!Array.isArray(item.fields)) fail('fields must be an array');
+      for (const field of item.fields) {
+        const entry = requireRecord(field, 'fields[]');
+        requireString(entry.name, 'fields[].name');
+        if (typeof entry.dataTypeId !== 'number' || !Number.isInteger(entry.dataTypeId)) fail('fields[].dataTypeId must be an integer');
+      }
+      if (!Array.isArray(item.rows) || !item.rows.every(isRecord)) fail('rows must be an array of objects');
+      requireError(item.error, 'error');
+      break;
+    }
+    case 'crypto':
+      onlyKeys(item, ['seq', 'kind', 'request', 'value'], 'exchange');
+      validateCryptoRequest(item.request);
+      requireString(item.value, 'value');
+      break;
+    default:
+      fail('kind must be one of "http", "db", "crypto"');
+  }
+  return item as unknown as FixtureExchange;
+}
+
+function validateRequest(value: unknown): FixtureRequest {
+  const item = requireRecord(value, 'request');
+  onlyKeys(item, ['requestId', 'receivedAt', 'headers', 'body'], 'request');
+  requireNonEmptyString(item.requestId, 'requestId');
+  requireNonEmptyString(item.receivedAt, 'receivedAt');
+  requireStringRecord(item.headers, 'headers');
+  requireString(item.body, 'body');
+  return item as unknown as FixtureRequest;
+}
+
+// ---------------------------------------------------------------------------
+// 解析
+
+function parseJsonFile<T>(file: ConnectorFixtureFile, validate: (value: unknown) => T): T {
+  let value: unknown;
+  try {
+    value = JSON.parse(file.content);
+  } catch (error) {
+    throw new FixtureFormatError(`not valid JSON (${error instanceof Error ? error.message : String(error)})`, file.path);
+  }
+  try {
+    return validate(value);
+  } catch (error) {
+    if (error instanceof ShapeError) throw new FixtureFormatError(error.message, file.path);
+    throw error;
+  }
+}
+
+/** NDJSON：逐行解析，空行跳过（行号照算）。 */
+function parseNdjson<T>(file: ConnectorFixtureFile, validate: (value: unknown, line: number) => T): T[] {
+  const items: T[] = [];
+  const lines = file.content.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const text = (lines[index] ?? '').replace(/\r$/, '');
+    if (text.trim() === '') continue;
+    const line = index + 1;
+    let value: unknown;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      throw new FixtureFormatError('not valid JSON', file.path, line);
+    }
+    try {
+      items.push(validate(value, line));
+    } catch (error) {
+      if (error instanceof ShapeError) throw new FixtureFormatError(error.message, file.path, line);
+      throw error;
+    }
+  }
+  return items;
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/** 用例所在能力目录的分组与名字。 */
+function capabilityOfCase(fixtureCase: FixtureCase): { group: CapabilityGroup; name: string } {
+  switch (fixtureCase.kind) {
+    case 'pull':
+    case 'suggest':
+      return { group: 'streams', name: fixtureCase.stream };
+    case 'push':
+      return { group: 'pushes', name: fixtureCase.push };
+    case 'operation':
+      return { group: 'operations', name: fixtureCase.operation };
+  }
+}
+
+/**
+ * 校验并解析用例文件（路径形如 `<streams|pushes|operations>/<名>/tests/<用例名>/<文件>`，其余路径报错）；
+ * 结果按能力、用例名排序。格式错误抛 `FixtureFormatError`（含 file、line）。以 `.` 开头的文件（如 `.DS_Store`）忽略。
+ */
+export function parseFixtures(files: ConnectorFixtureFile[]): LoadedFixture[] {
+  const groups = new Map<string, { group: CapabilityGroup; capabilityName: string; name: string; dir: string; files: Map<string, ConnectorFixtureFile> }>();
+  for (const raw of files) {
+    const file = { path: normalizePath(raw.path), content: raw.content };
+    const parts = file.path.split('/');
+    if (parts.some((part) => part === '' || part === '.' || part === '..')) throw new FixtureFormatError('test case paths must be plain relative paths', file.path);
+    if (parts.some((part) => part.startsWith('.'))) continue;
+    const [group, capabilityName = '', tests, name = '', fileName = ''] = parts;
+    if (parts.length !== 5 || !CAPABILITY_GROUPS.includes(group as CapabilityGroup) || tests !== TESTS_DIR) {
+      throw new FixtureFormatError(`unexpected file: test cases live at <streams|pushes|operations>/<name>/${TESTS_DIR}/<case>/{${[...CASE_FILES].join(',')}}`, file.path);
+    }
+    const capabilityGroup = group as CapabilityGroup;
+    if (!CAPABILITY_NAME_PATTERN[capabilityGroup].test(capabilityName)) {
+      throw new FixtureFormatError(`${capabilityGroup} name "${capabilityName}" must match ${CAPABILITY_NAME_PATTERN[capabilityGroup].source}`, file.path);
+    }
+    if (!FIXTURE_CASE_NAME_PATTERN.test(name)) {
+      throw new FixtureFormatError(`case name "${name}" must match ${FIXTURE_CASE_NAME_PATTERN.source}`, file.path);
+    }
+    if (!CASE_FILES.has(fileName)) {
+      throw new FixtureFormatError(`unexpected file in case "${name}": expected ${[...CASE_FILES].join(', ')}`, file.path);
+    }
+    const dir = parts.slice(0, 4).join('/');
+    const entry = groups.get(dir) ?? { group: capabilityGroup, capabilityName, name, dir, files: new Map<string, ConnectorFixtureFile>() };
+    if (entry.files.has(fileName)) throw new FixtureFormatError('duplicate file', file.path);
+    entry.files.set(fileName, file);
+    groups.set(dir, entry);
+  }
+
+  const fixtures: LoadedFixture[] = [];
+  for (const dir of [...groups.keys()].sort()) {
+    const entry = groups.get(dir);
+    if (!entry) continue;
+    const { name } = entry;
+    const casePath = `${dir}/${CASE_FILE}`;
+    const caseFile = entry.files.get(CASE_FILE);
+    if (!caseFile) throw new FixtureFormatError(`case "${name}" has no ${CASE_FILE}`, casePath);
+    const fixtureCase = parseJsonFile(caseFile, (value) => validateCase(value, entry.group, entry.capabilityName));
+
+    const exchangesFile = entry.files.get(EXCHANGES_FILE);
+    let previousSeq = 0;
+    const exchanges = exchangesFile
+      ? parseNdjson(exchangesFile, (value) => {
+        const exchange = validateExchange(value);
+        if (exchange.seq <= previousSeq) fail(`seq ${exchange.seq} must be greater than the previous seq ${previousSeq}`);
+        previousSeq = exchange.seq;
+        return exchange;
+      })
+      : [];
+
+    const requestsFile = entry.files.get(REQUESTS_FILE);
+    if (fixtureCase.kind === 'push' && !requestsFile) {
+      throw new FixtureFormatError(`push case "${name}" needs ${REQUESTS_FILE} next to ${CASE_FILE}`, casePath);
+    }
+    if (fixtureCase.kind !== 'push' && requestsFile) {
+      throw new FixtureFormatError(`${REQUESTS_FILE} only belongs to push cases`, requestsFile.path);
+    }
+    const seen = new Set<string>();
+    const requests = requestsFile
+      ? parseNdjson(requestsFile, (value) => {
+        const request = validateRequest(value);
+        if (seen.has(request.requestId)) fail(`requestId "${request.requestId}" appears more than once`);
+        seen.add(request.requestId);
+        return request;
+      })
+      : [];
+
+    fixtures.push({ capability: `${entry.group}/${entry.capabilityName}`, name, case: fixtureCase, exchanges, requests });
+  }
+  return fixtures;
+}
+
+// ---------------------------------------------------------------------------
+// 序列化
+
+/** `case.secrets` 写盘前：长度 ≥ 4 的值换成 `***`（与遮蔽规则一致，更短的值不替换）。 */
+function redactSecrets(secrets: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(secrets).map(([field, value]) => [field, value.length >= REDACT_MIN_LENGTH ? REDACTED : value]));
+}
+
+/** 内存形态 → `case.json` 的文件形态：去掉由目录推出的 `kind` 与能力名（建议列用例保留 `"kind": "suggest"`）。 */
+function caseFileContent(fixtureCase: FixtureCase): Record<string, unknown> {
+  const { kind, ...rest } = fixtureCase as FixtureCase & Record<string, unknown>;
+  const body: Record<string, unknown> = { ...rest };
+  delete body.stream;
+  delete body.push;
+  delete body.operation;
+  if (body.secrets !== undefined) body.secrets = redactSecrets(body.secrets as Record<string, string>);
+  return kind === 'suggest' ? { kind, ...body } : body;
+}
+
+function ndjson(items: readonly unknown[]): string {
+  return items.map((item) => `${JSON.stringify(item)}\n`).join('');
+}
+
+/**
+ * 把一个用例写成用例文件（目录由 `case.kind` 与能力名决定）：`case.json`（两格缩进）、`exchanges.ndjson`（有往来时）、
+ * `requests.ndjson`（推送用例）。`case.secrets` 里长度 ≥ 4 的值写成 `***`。与 `parseFixtures` 往返无损（`secrets` 已遮蔽时）。
+ */
+export function serializeFixture(
+  name: string,
+  input: { case: FixtureCase; exchanges: FixtureExchange[]; requests?: FixtureRequest[] },
+): ConnectorFixtureFile[] {
+  const capability = capabilityOfCase(input.case);
+  const dir = `${capability.group}/${capability.name}/${TESTS_DIR}/${name}`;
+  if (!CAPABILITY_NAME_PATTERN[capability.group].test(capability.name)) {
+    throw new FixtureFormatError(`${capability.group} name "${capability.name}" must match ${CAPABILITY_NAME_PATTERN[capability.group].source}`, `${dir}/${CASE_FILE}`);
+  }
+  if (!FIXTURE_CASE_NAME_PATTERN.test(name)) throw new FixtureFormatError(`case name "${name}" must match ${FIXTURE_CASE_NAME_PATTERN.source}`, `${dir}/${CASE_FILE}`);
+  const requests = input.requests ?? [];
+  if (input.case.kind !== 'push' && requests.length > 0) throw new FixtureFormatError(`${REQUESTS_FILE} only belongs to push cases`, `${dir}/${REQUESTS_FILE}`);
+  const files: ConnectorFixtureFile[] = [{ path: `${dir}/${CASE_FILE}`, content: `${JSON.stringify(caseFileContent(input.case), null, 2)}\n` }];
+  if (input.exchanges.length > 0) files.push({ path: `${dir}/${EXCHANGES_FILE}`, content: ndjson(input.exchanges) });
+  if (input.case.kind === 'push') files.push({ path: `${dir}/${REQUESTS_FILE}`, content: ndjson(requests) });
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// 读目录（Node）
+
+/**
+ * 读 `<dir>/<streams|pushes|operations>/<名>/tests/**` 下的全部文件（`path` 相对 `dir`、用 `/` 分隔、按路径排序）；没有时返回空数组。
+ * 以 `.` 开头的文件与目录跳过；遇到符号链接抛 `FixtureFormatError`（用例是租户数据，不跟随链接）。
+ */
+export async function readFixtureDir(dir: string): Promise<ConnectorFixtureFile[]> {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const files: ConnectorFixtureFile[] = [];
+
+  const walk = async (absolute: string, relative: string): Promise<void> => {
+    const entries = await fs.readdir(absolute, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const childAbsolute = path.join(absolute, entry.name);
+      const childRelative = `${relative}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw new FixtureFormatError('symbolic links are not allowed in test cases', childRelative);
+      if (entry.isDirectory()) await walk(childAbsolute, childRelative);
+      else if (entry.isFile()) files.push({ path: childRelative, content: await fs.readFile(childAbsolute, 'utf8') });
+    }
+  };
+
+  const listDirectories = async (absolute: string): Promise<string[]> => {
+    try {
+      const entries = await fs.readdir(absolute, { withFileTypes: true });
+      return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name);
+    } catch (error) {
+      if (isRecord(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return [];
+      throw error;
+    }
+  };
+
+  for (const group of CAPABILITY_GROUPS) {
+    for (const name of await listDirectories(path.join(dir, group))) {
+      const relative = `${group}/${name}/${TESTS_DIR}`;
+      const absolute = path.join(dir, group, name, TESTS_DIR);
+      let stat: Awaited<ReturnType<typeof fs.lstat>>;
+      try {
+        stat = await fs.lstat(absolute);
+      } catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT') continue;
+        throw error;
+      }
+      if (stat.isSymbolicLink()) throw new FixtureFormatError('symbolic links are not allowed in test cases', relative);
+      if (!stat.isDirectory()) throw new FixtureFormatError('must be a directory', relative);
+      await walk(absolute, relative);
+    }
+  }
+  return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+// ---------------------------------------------------------------------------
+// 录制与回放共用的规整
+
+/** http 请求的规范 URL：query 并入 URL，再按键排序（同名键保持相对顺序）。解析不了时原样返回。 */
+export function canonicalRequestUrl(url: string, query: Record<string, string | string[]> | undefined): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+  for (const [name, value] of Object.entries(query ?? {})) {
+    for (const item of Array.isArray(value) ? value : [value]) parsed.searchParams.append(name, item);
+  }
+  parsed.searchParams.sort();
+  return parsed.toString();
+}
+
+/** 键排序后的 JSON（db 参数、crypto 请求的比较用）。 */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(value, (_key, item: unknown) => {
+    if (!isRecord(item)) return item;
+    return Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]]));
+  });
+}