@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/runtime/session.ts

@@ -0,0 +1,216 @@
+/**
+ * 宿主侧的 guest 会话（在 runner 的执行子进程里运行，不在 vm 里）。
+ *
+ * 收到 `execute` 后建一个新的 vm 上下文，先执行 guest 运行时源码并调用它的 `bootGuest()`，再把连接器代码编译成
+ * `(function (module, exports, require) {…})` 交给 guest 加载。之后宿主与 guest 之间只有字符串：
+ * 父进程的 `reply` / `cancel` 经 `handle(json)` 交进去，guest 待发的消息经 `poll()` 取出、原样转给父进程。
+ *
+ * 宿主绝不往上下文里放宿主的函数或对象（`constructor` 链能拿到宿主的 `Function`），也不 `await` 上下文里的 Promise。
+ * 上下文里没有定时器：guest 的 `sleep` 登记到期时间，`poll()` 回报 `wake`，宿主按它定时再 poll。
+ * 每次交进消息或触发定时器之后，在下一个宏任务里 poll（此时上下文里的微任务已经跑完）。
+ *
+ * 会话不发 `ready`：由子进程入口在接好 IPC 之后自己发。
+ */
+import vm from 'node:vm';
+import { parseParentMessage, type GuestFailureCode } from './protocol';
+
+/** guest 交给宿主的接口；三个函数都属于上下文，参数与返回值只有字符串和上下文里的值。 */
+interface GuestApi {
+  start(json: string, factory: unknown): void;
+  handle(json: string): void;
+  poll(): unknown;
+}
+
+const GUEST_FILENAME = 'ontos-guest.js';
+const CONNECTOR_FILENAME = 'connector.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 从上下文里抛出的值只取 message 字符串；读属性本身也可能抛错。 */
+function guestErrorMessage(error: unknown): string {
+  try {
+    if (error !== null && typeof error === 'object') {
+      const message = (error as { message?: unknown }).message;
+      if (typeof message === 'string') return message;
+    }
+  } catch {
+    // 落到缺省文案
+  }
+  return 'unknown error';
+}
+
+function bootGuest(context: vm.Context, guestSource: string): GuestApi {
+  // guest 是 CJS 打包产物；module / exports 在上下文里创建，不用宿主对象。
+  const wrapped = `(() => { const module = { exports: {} }; const exports = module.exports; ${guestSource}\n; return module.exports; })()`;
+  const exported = new vm.Script(wrapped, { filename: GUEST_FILENAME }).runInContext(context) as { bootGuest?: unknown };
+  const boot = exported.bootGuest;
+  if (typeof boot !== 'function') throw new Error('guest runtime does not export bootGuest');
+  const api = (boot as () => unknown)() as Record<string, unknown>;
+  const { start, handle, poll } = api;
+  if (typeof start !== 'function' || typeof handle !== 'function' || typeof poll !== 'function') throw new Error('guest runtime returned an incomplete API');
+  // 立即取下函数引用：之后连接器代码改写这个对象也不影响宿主。
+  return { start: start as GuestApi['start'], handle: handle as GuestApi['handle'], poll: poll as GuestApi['poll'] };
+}
+
+type BootOutcome = { ok: true; guest: GuestApi; factory: unknown } | { ok: false; code: GuestFailureCode; message: string };
+
+/** vm 启动：新上下文里执行 guest 运行时并 `bootGuest()`，再在同一上下文里编译连接器代码。 */
+function bootInVm(guestSource: string, code: string): BootOutcome {
+  const context = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false } });
+  let guest: GuestApi;
+  try {
+    guest = bootGuest(context, guestSource);
+  } catch (error) {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector runtime failed to start: ${guestErrorMessage(error)}` };
+  }
+  try {
+    // 包装与第一行同行（Bun 的 vm.Script 不认 lineOffset），调用栈的行号直接对应打包产物。
+    const factory = new vm.Script(`(function (module, exports, require) {${code}\n})`, { filename: CONNECTOR_FILENAME }).runInContext(context);
+    return { ok: true, guest, factory };
+  } catch (error) {
+    return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector code failed to compile: ${guestErrorMessage(error)}` };
+  }
+}
+
+/** 子进程入口里调用：收到 execute 时建 vm 上下文、加载其中的 guest 字符串；之后只吃字符串消息。 */
+export function createGuestSession(send: (json: string) => void): { handle(json: string): void } {
+  return createSession(send, bootInVm);
+}
+
+/**
+ * 进程内会话（`./testing` 的 `createInProcessExecutor`，给 vitest 用）：不建 vm，在当前全局里重新求值一份 guest 运行时
+ * （模块状态每次执行独立），连接器是调用方已导入的模块（`{ descriptor, implementations }`），`execute.code` 被忽略。消息协议与 vm 会话完全相同。
+ * 这里不是隔离边界：连接器代码与宿主同进程同全局，只用于作者在自己机器上跑测试。
+ */
+export function createInProcessGuestSession(send: (json: string) => void, connectorModule: unknown): { handle(json: string): void } {
+  return createSession(send, (guestSource) => {
+    let exported: { bootLocalGuest?: unknown };
+    try {
+      const module = { exports: {} as unknown };
+      const noRequire = (specifier: string): never => { throw new Error(`guest runtime cannot require ${specifier}`); };
+      // 受信任的 guest 运行时（SDK 自己的打包产物）
+      const load = new Function('module', 'exports', 'require', guestSource) as (module: unknown, exports: unknown, require: unknown) => void;
+      load(module, module.exports, noRequire);
+      exported = module.exports as { bootLocalGuest?: unknown };
+    } catch (error) {
+      return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: `connector runtime failed to start: ${guestErrorMessage(error)}` };
+    }
+    if (typeof exported.bootLocalGuest !== 'function') {
+      return { ok: false, code: 'CONNECTOR_LOAD_FAILED', message: 'connector runtime failed to start: guest runtime does not export bootLocalGuest' };
+    }
+    const guest = (exported.bootLocalGuest as () => GuestApi)();
+    const factory = (module: { exports: unknown }): void => {
+      module.exports = connectorModule;
+    };
+    return { ok: true, guest, factory };
+  });
+}
+
+function createSession(send: (json: string) => void, boot: (guestSource: string, code: string) => BootOutcome): { handle(json: string): void } {
+  let guest: GuestApi | null = null;
+  let started = false;
+  let done = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timerAt = Number.POSITIVE_INFINITY;
+
+  const stop = () => {
+    done = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const fail = (code: GuestFailureCode, message: string) => {
+    if (done) return;
+    stop();
+    send(JSON.stringify({ type: 'failure', code, message, logs: [] }));
+  };
+
+  const schedule = (delay: number) => {
+    if (done) return;
+    const at = Date.now() + delay;
+    if (timer !== undefined && timerAt <= at) return;
+    if (timer !== undefined) clearTimeout(timer);
+    timerAt = at;
+    timer = setTimeout(pump, delay);
+  };
+
+  function pump(): void {
+    timer = undefined;
+    timerAt = Number.POSITIVE_INFINITY;
+    if (done || !guest) return;
+    let text: unknown;
+    try {
+      text = guest.poll();
+    } catch (error) {
+      fail('FATAL_ERROR', `connector runtime failed: ${guestErrorMessage(error)}`);
+      return;
+    }
+    let parsed: unknown;
+    try {
+      parsed = typeof text === 'string' ? JSON.parse(text) : null;
+    } catch {
+      parsed = null;
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.out)) {
+      fail('FATAL_ERROR', 'connector runtime returned a malformed poll result');
+      return;
+    }
+    for (const message of parsed.out) {
+      if (!isRecord(message)) continue;
+      send(JSON.stringify(message));
+      if (message.type === 'result' || message.type === 'failure') {
+        stop();
+        return;
+      }
+    }
+    if (parsed.out.length > 0 || parsed.fired === true) schedule(0);
+    else if (typeof parsed.wake === 'number' && parsed.wake >= 0) schedule(parsed.wake);
+  }
+
+  const execute = (guestSource: string, code: string, payload: string) => {
+    const booted = boot(guestSource, code);
+    if (!booted.ok) {
+      fail(booted.code, booted.message);
+      return;
+    }
+    guest = booted.guest;
+    try {
+      guest.start(payload, booted.factory);
+    } catch (error) {
+      fail('FATAL_ERROR', `connector runtime failed: ${guestErrorMessage(error)}`);
+      return;
+    }
+    schedule(0);
+  };
+
+  return {
+    handle(json: string): void {
+      if (done || typeof json !== 'string') return;
+      let raw: unknown;
+      try {
+        raw = JSON.parse(json);
+      } catch {
+        return;
+      }
+      const message = parseParentMessage(raw);
+      if (!message) return;
+      if (message.type === 'execute') {
+        if (started) return;
+        started = true;
+        execute(message.guest, message.code, JSON.stringify({ expect: message.expect, job: message.job }));
+        return;
+      }
+      if (!guest) return;
+      try {
+        // 重新序列化校验过的消息，guest 只看到契约里的字段。
+        guest.handle(JSON.stringify(message));
+      } catch (error) {
+        fail('FATAL_ERROR', `connector runtime failed: ${guestErrorMessage(error)}`);
+        return;
+      }
+      schedule(0);
+    },
+  };
+}

package/src/testing/child.ts

@@ -0,0 +1,21 @@
+/**
+ * `createVmExecutor` 的子进程入口（父进程用空环境变量 fork，不被 import）。与 runner 的子进程入口相同：
+ * IPC 收到的 JSON 字符串交给 guest 会话（`createGuestSession`，vm 上下文里跑 guest 与连接器），会话要发的消息原样发回。
+ * 子进程不读环境变量、不发网络请求；父进程收到结果、超时或取消时杀掉它，父进程断开时自行退出。
+ * 构建时打成 `dist/testing/child.cjs`（Node 可直接执行）。
+ */
+import { createGuestSession } from '../runtime/session';
+
+const session = createGuestSession((json) => {
+  process.send?.(json);
+});
+
+process.on('message', (raw: unknown) => {
+  if (typeof raw === 'string') session.handle(raw);
+});
+
+process.on('disconnect', () => {
+  process.exit(0);
+});
+
+process.send?.(JSON.stringify({ type: 'ready' }));

package/src/testing/compliance.ts

@@ -0,0 +1,343 @@
+/**
+ * 合规检查：拿一次本地运行（用例回放或预览）的结果对照连接器描述里的表，找出平台写入时会出问题、或违反连接器约定的地方。
+ * 纯函数，不依赖 Node 模块（meta 组装预览视图时调用，UI 也可能用）。
+ *
+ * - `UNDECLARED_TABLE`：记录 / 删除标记落在给定的表之外（拉取给该数据流的表、推送给该推送的表）；
+ * - `UNDECLARED_FIELDS`：不可扩展表的记录带了未声明的字段（线上运行会丢弃这些字段），每张表一条，列出全部字段名；
+ *   可扩展表的额外字段可以成为扩展列，不算问题；
+ * - `RECORD_SCHEMA_MISMATCH`：值与声明的列类型不符（规则与 connector 写入时的值换算相同）、缺主键列；
+ * - `PRIMARY_KEY_DUPLICATE`：同一次运行里两条记录主键相同；
+ * - `CHECKPOINT_NOT_MONOTONIC`：断点 `state` 的顶层字段（有限数字或 ISO-8601 时间字符串）比上一个断点小；
+ * - `FULL_READ_NOT_REPEATABLE`：全量模式下两遍读到的记录集合不同（给了 `rerun` 时才比）。
+ *
+ * 同一类问题按「表 + 列 + 原因」合并成一条，`detail.count` 为条数、`detail.sample` 为第一条的值。
+ * `FIXTURE_EXCHANGE_*` 与 `EXPECTATION_FAILED` 由用例回放（`replay.ts`）给出。
+ */
+import { parseIsoInstant } from './schema';
+import type { LocalRunResult } from './types';
+
+/** 合规检查码（与 shared 的 `ComplianceCode` 同值）。 */
+export type ComplianceCode =
+  | 'PRIMARY_KEY_DUPLICATE'
+  | 'RECORD_SCHEMA_MISMATCH'
+  | 'UNDECLARED_TABLE'
+  | 'UNDECLARED_FIELDS'
+  | 'CHECKPOINT_NOT_MONOTONIC'
+  | 'FULL_READ_NOT_REPEATABLE'
+  | 'FIXTURE_EXCHANGE_UNUSED'
+  | 'FIXTURE_EXCHANGE_MISMATCH'
+  | 'EXPECTATION_FAILED';
+
+export const COMPLIANCE_CODES: readonly ComplianceCode[] = Object.freeze([
+  'PRIMARY_KEY_DUPLICATE',
+  'RECORD_SCHEMA_MISMATCH',
+  'UNDECLARED_TABLE',
+  'UNDECLARED_FIELDS',
+  'CHECKPOINT_NOT_MONOTONIC',
+  'FULL_READ_NOT_REPEATABLE',
+  'FIXTURE_EXCHANGE_UNUSED',
+  'FIXTURE_EXCHANGE_MISMATCH',
+  'EXPECTATION_FAILED',
+]);
+
+export interface ComplianceFinding { code: ComplianceCode; message: string; table?: string; detail?: unknown }
+
+/** 检查用的表结构：`TableDescriptor` 的子集（可以把连接的扩展列并进 `columns` 再传进来）。 */
+export interface ComplianceTable {
+  columns: Record<string, { type: string; precision?: number; scale?: number }>;
+  primaryKey: string[];
+  extensible: boolean;
+}
+
+export interface ComplianceInput {
+  /** 用例范围内的表（拉取取该数据流的表、推送取该推送的表）；为 null 时跳过依赖表结构的检查。 */
+  tables: Record<string, ComplianceTable> | null;
+  /** 消息里的范围说明，如 `stream "orders"`。 */
+  scope?: string;
+  mode?: 'full' | 'incremental';
+  result: LocalRunResult;
+  rerun?: LocalRunResult;
+}
+
+type DeclaredColumn = ComplianceTable['columns'][string];
+type DeclaredTable = ComplianceTable;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 未声明字段在消息里最多列出的个数（与线上丢弃告警一致）。 */
+const UNDECLARED_FIELDS_LISTED = 20;
+
+// ---------------------------------------------------------------------------
+// 值（与 connector `storage/writer.ts` 的 `coerceValue` 同一套规则，只判断不换算）
+
+const INSTANT_PATTERN = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}(?::?\d{2})?)$/i;
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const INTEGER_PATTERN = /^-?\d+$/;
+const DECIMAL_PATTERN = /^-?(\d+)(?:\.(\d+))?$/;
+
+function validCalendarDate(year: number, month: number, day: number): boolean {
+  return month >= 1 && month <= 12 && day >= 1 && day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+/** 值不符合列类型时返回原因，符合（含空值）时返回 null。 */
+export function columnValueProblem(type: DeclaredColumn, value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  switch (type.type) {
+    case 'string':
+      return typeof value === 'string' ? null : 'is not a valid string';
+    case 'integer':
+      if (typeof value === 'number' && Number.isSafeInteger(value)) return null;
+      if (typeof value === 'bigint') return null;
+      if (typeof value === 'string' && INTEGER_PATTERN.test(value)) return null;
+      return 'is not a valid integer';
+    case 'decimal': {
+      let text: string;
+      if (typeof value === 'number' && Number.isFinite(value)) text = String(value);
+      else if (typeof value === 'string') text = value;
+      else return 'is not a valid decimal';
+      const match = DECIMAL_PATTERN.exec(text);
+      if (!match) return 'is not a valid decimal';
+      if (type.precision !== undefined && type.scale !== undefined) {
+        const integerDigits = (match[1] ?? '').replace(/^0+(?=\d)/, '');
+        if (integerDigits !== '0' && integerDigits.length > type.precision - type.scale) return `exceeds decimal precision ${type.precision},${type.scale}`;
+      }
+      return null;
+    }
+    case 'boolean':
+      return typeof value === 'boolean' ? null : 'is not a valid boolean';
+    case 'date': {
+      if (typeof value !== 'string') return 'is not a valid date';
+      const match = DATE_PATTERN.exec(value);
+      return match && validCalendarDate(Number(match[1]), Number(match[2]), Number(match[3])) ? null : 'is not a valid date';
+    }
+    case 'instant': {
+      if (typeof value !== 'string') return 'is not a valid instant';
+      const match = INSTANT_PATTERN.exec(value);
+      if (!match) return 'is not an ISO 8601 timestamp with a time zone offset';
+      const [, year, month, day, hour, minute, second] = match;
+      const valid = validCalendarDate(Number(year), Number(month), Number(day)) && Number(hour) <= 23 && Number(minute) <= 59 && Number(second ?? '0') <= 59;
+      return valid && parseIsoInstant(value) !== null ? null : 'is not a valid point in time';
+    }
+    case 'json':
+      try {
+        return JSON.stringify(value) === undefined ? 'is not valid JSON' : null;
+      } catch {
+        return 'is not valid JSON';
+      }
+    default:
+      return `has an unsupported column type ${type.type}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 合并同类问题
+
+class FindingSet {
+  private readonly items = new Map<string, { finding: ComplianceFinding; count: number }>();
+  private readonly ordered: ComplianceFinding[] = [];
+
+  /** `key` 相同的问题合并：只留第一条的 message 与 sample，`detail.count` 累加。 */
+  add(key: string, build: () => { code: ComplianceCode; message: string; table?: string; sample?: unknown; extra?: Record<string, unknown> }): void {
+    const existing = this.items.get(key);
+    if (existing) {
+      existing.count += 1;
+      (existing.finding.detail as Record<string, unknown>).count = existing.count;
+      return;
+    }
+    const { code, message, table, sample, extra } = build();
+    const finding: ComplianceFinding = { code, message, ...(table !== undefined ? { table } : {}), detail: { count: 1, ...(sample !== undefined ? { sample } : {}), ...extra } };
+    this.items.set(key, { finding, count: 1 });
+    this.ordered.push(finding);
+  }
+
+  push(finding: ComplianceFinding): void {
+    this.ordered.push(finding);
+  }
+
+  prepend(items: readonly ComplianceFinding[]): void {
+    this.ordered.unshift(...items);
+  }
+
+  list(): ComplianceFinding[] {
+    return this.ordered;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 记录与删除标记
+
+function checkRows(input: ComplianceInput, tables: Record<string, DeclaredTable>, findings: FindingSet): void {
+  const keysSeen = new Map<string, Set<string>>();
+  const undeclaredFields = new Map<string, Set<string>>();
+  const undeclared = (table: string, sample: unknown): void => {
+    findings.add(`undeclared\0${table}`, () => ({
+      code: 'UNDECLARED_TABLE', table, sample,
+      message: `table "${table}" is not declared${input.scope !== undefined ? ` by ${input.scope}` : ''}`,
+    }));
+  };
+  const mismatch = (table: string, column: string, reason: string, sample: unknown): void => {
+    findings.add(`schema\0${table}\0${column}\0${reason}`, () => ({
+      code: 'RECORD_SCHEMA_MISMATCH', table, sample, extra: { column },
+      message: `column "${column}" of table "${table}" ${reason}`,
+    }));
+  };
+
+  for (const record of input.result.records) {
+    const declared = Object.hasOwn(tables, record.table) ? tables[record.table] : undefined;
+    if (!declared) {
+      undeclared(record.table, record.row);
+      continue;
+    }
+    if (!declared.extensible) {
+      for (const column of Object.keys(record.row)) {
+        if (Object.hasOwn(declared.columns, column)) continue;
+        const fields = undeclaredFields.get(record.table) ?? new Set<string>();
+        fields.add(column);
+        undeclaredFields.set(record.table, fields);
+      }
+    }
+    for (const [column, type] of Object.entries(declared.columns)) {
+      const problem = columnValueProblem(type, record.row[column]);
+      if (problem) mismatch(record.table, column, problem, record.row[column]);
+    }
+    const missing = declared.primaryKey.filter((column) => record.row[column] === null || record.row[column] === undefined);
+    for (const column of missing) mismatch(record.table, column, 'is a primary key column and is missing', record.row);
+    if (declared.primaryKey.length === 0 || missing.length > 0) continue;
+    const key = JSON.stringify(declared.primaryKey.map((column) => record.row[column]));
+    const seen = keysSeen.get(record.table) ?? new Set<string>();
+    if (seen.has(key)) {
+      const sample = Object.fromEntries(declared.primaryKey.map((column) => [column, record.row[column]]));
+      findings.add(`pk\0${record.table}`, () => ({
+        code: 'PRIMARY_KEY_DUPLICATE', table: record.table, sample,
+        message: `table "${record.table}" received more than one record with the same primary key (${declared.primaryKey.join(', ')})`,
+      }));
+    }
+    seen.add(key);
+    keysSeen.set(record.table, seen);
+  }
+
+  // 未声明字段放在最前：线上运行会静默丢弃它们，是最需要作者先看到的问题。
+  const fieldFindings: ComplianceFinding[] = [];
+  for (const [table, set] of undeclaredFields) {
+    const fields = [...set].sort();
+    const listed = fields.slice(0, UNDECLARED_FIELDS_LISTED).join(', ');
+    fieldFindings.push({
+      code: 'UNDECLARED_FIELDS', table,
+      message: `table "${table}" received ${fields.length} undeclared field(s): ${listed}${fields.length > UNDECLARED_FIELDS_LISTED ? ', …' : ''}; table "${table}" is not extensible, so these fields would be discarded`,
+      detail: { fields },
+    });
+  }
+  findings.prepend(fieldFindings);
+
+  for (const removal of input.result.removals) {
+    const declared = Object.hasOwn(tables, removal.table) ? tables[removal.table] : undefined;
+    if (!declared) {
+      undeclared(removal.table, removal.key);
+      continue;
+    }
+    for (const column of Object.keys(removal.key)) {
+      if (!declared.primaryKey.includes(column)) mismatch(removal.table, column, 'is not part of the primary key (removal)', removal.key);
+    }
+    for (const column of declared.primaryKey) {
+      const value = removal.key[column];
+      if (value === null || value === undefined) {
+        mismatch(removal.table, column, 'is a primary key column and is missing (removal)', removal.key);
+        continue;
+      }
+      const type = declared.columns[column];
+      const problem = type ? columnValueProblem(type, value) : 'is not declared';
+      if (problem) mismatch(removal.table, column, `${problem} (removal)`, value);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 断点
+
+/** 可比较的断点字段值：有限数字按数值，ISO-8601 时间字符串按时刻；其他类型不判。 */
+function comparable(value: unknown): { kind: 'number' | 'time'; at: number } | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return { kind: 'number', at: value };
+  if (typeof value === 'string') {
+    const at = parseIsoInstant(value);
+    if (at !== null) return { kind: 'time', at };
+  }
+  return null;
+}
+
+function checkCheckpoints(checkpoints: LocalRunResult['checkpoints'], findings: FindingSet): void {
+  for (let index = 1; index < checkpoints.length; index += 1) {
+    const previous = checkpoints[index - 1];
+    const next = checkpoints[index];
+    if (!previous || !next || !isRecord(previous.state) || !isRecord(next.state)) continue;
+    for (const [field, before] of Object.entries(previous.state)) {
+      if (!Object.hasOwn(next.state, field)) continue;
+      const after = next.state[field];
+      const a = comparable(before);
+      const b = comparable(after);
+      if (!a || !b || a.kind !== b.kind || b.at >= a.at) continue;
+      findings.push({
+        code: 'CHECKPOINT_NOT_MONOTONIC',
+        message: `checkpoint field "${field}" went backwards from ${JSON.stringify(before)} to ${JSON.stringify(after)} (checkpoint ${next.seq})`,
+        detail: { field, previous: before, next: after, seq: next.seq },
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 全量可重复
+
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_key, item: unknown) => (isRecord(item) ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item));
+}
+
+/** 记录按「表 + 主键 + 整行」排序后的规范文本（主键缺失时只按整行）。 */
+function recordSet(records: LocalRunResult['records'], tables: Record<string, DeclaredTable> | null): string[] {
+  return records
+    .map((record) => {
+      const primaryKey = tables && Object.hasOwn(tables, record.table) ? tables[record.table]?.primaryKey ?? [] : [];
+      return `${record.table}\0${canonical(primaryKey.map((column) => record.row[column]))}\0${canonical(record.row)}`;
+    })
+    .sort();
+}
+
+function checkRepeatable(input: ComplianceInput, tables: Record<string, DeclaredTable> | null, findings: FindingSet): void {
+  const rerun = input.rerun;
+  if (input.mode !== 'full' || !rerun) return;
+  if (rerun.error) {
+    findings.push({
+      code: 'FULL_READ_NOT_REPEATABLE',
+      message: `the second full read failed (${rerun.error.code}: ${rerun.error.message})`,
+      detail: { error: rerun.error },
+    });
+    return;
+  }
+  const first = recordSet(input.result.records, tables);
+  const second = recordSet(rerun.records, tables);
+  if (first.length === second.length && first.every((item, index) => item === second[index])) return;
+  const firstSet = new Set(first);
+  const secondSet = new Set(second);
+  findings.push({
+    code: 'FULL_READ_NOT_REPEATABLE',
+    message: `two full reads returned different records (${first.length} vs ${second.length} record(s))`,
+    detail: {
+      firstCount: first.length,
+      secondCount: second.length,
+      onlyInFirst: first.filter((item) => !secondSet.has(item)).length,
+      onlyInSecond: second.filter((item) => !firstSet.has(item)).length,
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+
+export function checkCompliance(input: ComplianceInput): ComplianceFinding[] {
+  const findings = new FindingSet();
+  const tables = input.tables;
+  if (tables) checkRows(input, tables, findings);
+  checkCheckpoints(input.result.checkpoints, findings);
+  checkRepeatable(input, tables, findings);
+  return findings.list();
+}