@pipefy/pipefy-process-coder 0.1.0

package/src/cli.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { parse, bool, type Parsed } from './cli/args.ts';
+import { UserError, bold, dim, error as logError, info, out, setVerbose, yellow } from './util/log.ts';
+
+/**
+ * `pipe` — a CLI, and only a CLI. The one
+ * thing a GUI buys today is *seeing* a diff, which `pipe diff --open` does.
+ *
+ * Zero runtime dependencies and no build step: Node strips the types itself, so
+ * `node src/cli.ts` works on a clean checkout. That matters for a tool an FDE
+ * runs on a client's laptop.
+ */
+
+type Command = {
+  summary: string;
+  help: () => Promise<string>;
+  run: (p: Parsed) => Promise<number | void>;
+};
+
+const commands: Record<string, Command> = {
+  login: {
+    summary: 'store a Pipefy API token',
+    help: async () => (await import('./commands/misc.ts')).loginHelp,
+    run: async (p) => (await import('./commands/misc.ts')).login(p),
+  },
+  doctor: {
+    summary: 'report what this endpoint can actually do',
+    help: async () => (await import('./commands/misc.ts')).doctorHelp,
+    run: async (p) => (await import('./commands/misc.ts')).doctor(p),
+  },
+  skills: {
+    summary: 'the Claude Code skills this install ships with; install them for every project',
+    help: async () => (await import('./commands/skills.ts')).help,
+    run: async (p) => (await import('./commands/skills.ts')).run(p),
+  },
+  create: {
+    summary: 'create an empty pipe and pull it, ready to be built from files',
+    help: async () => (await import('./commands/create.ts')).help,
+    run: async (p) => (await import('./commands/create.ts')).run(p),
+  },
+  pull: {
+    summary: 'pull a pipe and everything it connects to into a workspace',
+    help: async () => (await import('./commands/pull.ts')).help,
+    run: async (p) => (await import('./commands/pull.ts')).run(p),
+  },
+  export: {
+    summary: 'export one repo as a single snapshot-shaped payload',
+    help: async () => (await import('./commands/misc.ts')).exportHelp,
+    run: async (p) => (await import('./commands/misc.ts')).exportCmd(p),
+  },
+  validate: {
+    summary: 'check JSON shape and referential integrity, offline',
+    help: async () => (await import('./commands/misc.ts')).validateHelp,
+    run: async (p) => (await import('./commands/misc.ts')).validate(p),
+  },
+  diff: {
+    summary: 'what changed — against the baseline, live, or another pipe',
+    help: async () => (await import('./commands/diff.ts')).help,
+    run: async (p) => (await import('./commands/diff.ts')).run(p),
+  },
+  plan: {
+    summary: 'classify every change and order the applicable ones',
+    help: async () => (await import('./commands/plan.ts')).help,
+    run: async (p) => (await import('./commands/plan.ts')).run(p),
+  },
+  apply: {
+    summary: 'snapshot, apply step by step, verify',
+    help: async () => (await import('./commands/apply.ts')).help,
+    run: async (p) => (await import('./commands/apply.ts')).run(p),
+  },
+  verify: {
+    summary: 'read the pipe back and diff it against the workspace',
+    help: async () => (await import('./commands/verify.ts')).help,
+    run: async (p) => (await import('./commands/verify.ts')).run(p),
+  },
+  rollback: {
+    summary: 'restore a snapshot',
+    help: async () => (await import('./commands/misc.ts')).rollbackHelp,
+    run: async (p) => (await import('./commands/misc.ts')).rollback(p),
+  },
+  runs: {
+    summary: 'every run recorded in this workspace, and what each one did',
+    help: async () => (await import('./commands/runs.ts')).help,
+    run: async (p) => (await import('./commands/runs.ts')).run(p),
+  },
+  status: {
+    summary: 'what is in this workspace and how it was read',
+    help: async () => (await import('./commands/misc.ts')).statusHelp,
+    run: async (p) => (await import('./commands/misc.ts')).status(p),
+  },
+  capabilities: {
+    summary: 'the write-coverage registry',
+    help: async () => (await import('./commands/misc.ts')).capsHelp,
+    run: async (p) => (await import('./commands/misc.ts')).capabilities(p),
+  },
+  roundtrip: {
+    summary: 'codec self-check: pack(unpack(P)) must equal P',
+    help: async () => (await import('./commands/misc.ts')).roundtripHelp,
+    run: async (p) => (await import('./commands/misc.ts')).roundtrip(p),
+  },
+  viewer: {
+    summary: 'build the HTML diff view and open it',
+    help: async () => (await import('./commands/misc.ts')).viewerHelp,
+    run: async (p) => (await import('./commands/misc.ts')).viewer(p),
+  },
+};
+
+const usage = () => {
+  const width = Math.max(...Object.keys(commands).map((k) => k.length)) + 2;
+  out(bold('pipe') + ' — Pipefy process coder');
+  out('');
+  out('  Pull a pipe to disk as readable JSON, edit it with Claude, diff it, push it back.');
+  out('');
+  out(bold('usage'));
+  out('  pipe <command> [options]');
+  out('');
+  out(bold('commands'));
+  for (const [name, cmd] of Object.entries(commands)) {
+    out(`  ${name.padEnd(width)} ${dim(cmd.summary)}`);
+  }
+  out('');
+  out(bold('the loop'));
+  out(`  pipe pull <pipeId> --out ./my-pipe        ${dim('# snapshot, or GraphQL if there are none')}`);
+  out(`  pipe validate                             ${dim('# offline, instant')}`);
+  out(`  pipe diff --open                          ${dim('# see it')}`);
+  out(`  pipe plan --dry-run                       ${dim('# refuses what cannot be applied')}`);
+  out(`  pipe apply                                ${dim('# snapshot, apply, verify')}`);
+  out('');
+  out(bold('global options'));
+  out(`  --verbose      ${dim('log every request, retry and dropped argument')}`);
+  out(`  --help         ${dim('help for a command')}`);
+  out('');
+  out(dim('First run: pipe login --token <token>, then pipe doctor.'));
+};
+
+const main = async () => {
+  const argv = process.argv.slice(2);
+  const parsed = parse(argv);
+  setVerbose(bool(parsed, 'verbose') || bool(parsed, 'v'));
+
+  /**
+   * `--version` before anything else. It is the first thing anyone types to check
+   * an install worked, and answering it with `unknown command "--version"` makes a
+   * working install look broken.
+   *
+   * The path is included because `npm link` puts a symlink on PATH: when two
+   * clones exist, or one was moved, "which one am I running" is the actual
+   * question behind the version check.
+   */
+  if (parsed.command === '--version' || parsed.command === '-V' || parsed.command === 'version') {
+    const { readFile } = await import('node:fs/promises');
+    const { fileURLToPath } = await import('node:url');
+    const { dirname, join } = await import('node:path');
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(await readFile(join(here, '..', 'package.json'), 'utf8')) as {
+      name: string;
+      version: string;
+    };
+    out(`${pkg.name} ${pkg.version}`);
+    out(dim(`  node    ${process.version} (needs >=22.18 for native type stripping)`));
+    out(dim(`  running ${join(here, 'cli.ts')}`));
+    return 0;
+  }
+
+  if (parsed.command === 'help' || parsed.command === '--help' || parsed.command === '-h' || !argv.length) {
+    const topic = parsed.positionals[0];
+    if (topic && commands[topic]) {
+      out(await (commands[topic] as Command).help());
+      return 0;
+    }
+    usage();
+    return 0;
+  }
+
+  const cmd = commands[parsed.command];
+  if (!cmd) {
+    logError(`unknown command "${parsed.command}"`);
+    const near = Object.keys(commands).filter((k) => k.startsWith(parsed.command[0] ?? ''));
+    if (near.length) info(dim(`did you mean: ${near.join(', ')}?`));
+    info(dim('run `pipe help` for the list'));
+    return 64;
+  }
+
+  if (bool(parsed, 'help') || bool(parsed, 'h')) {
+    out(await cmd.help());
+    return 0;
+  }
+
+  const code = await cmd.run(parsed);
+  return typeof code === 'number' ? code : 0;
+};
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((e) => {
+    if (e instanceof UserError) {
+      logError(e.message);
+      if (e.hint) info(`${yellow('hint')}  ${e.hint}`);
+      process.exitCode = 65;
+      return;
+    }
+    logError((e as Error).message);
+    if (process.env.PPC_DEBUG || bool(parse(process.argv.slice(2)), 'verbose')) {
+      info(dim(String((e as Error).stack)));
+    } else {
+      info(dim('run again with --verbose for a stack trace'));
+    }
+    process.exitCode = 70;
+  });

package/src/codec/flow.ts

@@ -0,0 +1,199 @@
+import { canonicalString } from '../util/json.ts';
+import type { Row } from '../model/payload.ts';
+
+/**
+ * The flow codec: a linked list of nodes on the wire, an ordered array of files on
+ * disk, and back again without loss.
+ *
+ * This is the one place the workspace's "folding is movement only" rule does not
+ * hold. A pipe's fields are moved under their phase unchanged, which makes
+ * `pack(unpack(P)) == P` true by construction. A flow's chaining lives *in* the
+ * nodes — `nextAction`, `firstLoopAction`, `children[]` — so splitting them into
+ * one file per node is a transformation, and the guarantee has to be earned by
+ * `assertFlowRoundTrip` rather than assumed.
+ *
+ * The links are preserved as `_`-prefixed metadata, which every comparator already
+ * ignores and nothing sends to the API:
+ *
+ *   _nextAction      : the name of the next node, or absent at the end of a chain
+ *   _firstLoopAction : the first node inside a LOOP_ON_ITEMS
+ *   _children        : one name per router branch, index-aligned with
+ *                      settings.branches, null for an empty branch
+ */
+
+export type FlowNode = Row & { name: string; type: string };
+
+/** A flow as the workspace holds it: the row, its version, and its nodes in order. */
+export type FlowTree = {
+  /** The flow row, without `version`. */
+  flow: Row;
+  /** The version row, without `trigger`. */
+  version: Row;
+  /** Execution order: trigger first, then depth-first through the chain. */
+  nodes: FlowNode[];
+};
+
+const LINK_KEYS = ['nextAction', 'firstLoopAction', 'children'] as const;
+
+/** Split the linked list into an ordered array, recording the links as metadata. */
+export const unlinkFlow = (flowRow: Row): FlowTree => {
+  const { version, ...flow } = flowRow;
+  const v = (version ?? {}) as Row;
+  const { trigger, ...versionRest } = v;
+
+  const nodes: FlowNode[] = [];
+  const visit = (n: Row | null | undefined) => {
+    if (!n) return;
+    const { nextAction, firstLoopAction, children, ...rest } = n;
+    const node: FlowNode = {
+      ...(rest as Row),
+      name: String(n['name'] ?? ''),
+      type: String(n['type'] ?? ''),
+    };
+    if (firstLoopAction) node['_firstLoopAction'] = String((firstLoopAction as Row)['name']);
+    if (children) {
+      node['_children'] = (children as Array<Row | null>).map((c) => (c ? String(c['name']) : null));
+    }
+    if (nextAction) node['_nextAction'] = String((nextAction as Row)['name']);
+    nodes.push(node);
+
+    if (firstLoopAction) visit(firstLoopAction as Row);
+    for (const c of (children ?? []) as Array<Row | null>) visit(c);
+    visit(nextAction as Row | undefined);
+  };
+  visit(trigger as Row | undefined);
+
+  return { flow: flow as Row, version: versionRest as Row, nodes };
+};
+
+/** Reassemble the linked list from the ordered array. The inverse of `unlinkFlow`. */
+export const linkFlow = (tree: FlowTree): Row => {
+  const byName = new Map<string, FlowNode>();
+  for (const n of tree.nodes) byName.set(n.name, n);
+
+  /**
+   * Rebuilt depth-first from the trigger, so a node the chain does not reach is
+   * simply not in the result — and `assertFlowRoundTrip` then reports it, rather
+   * than the node vanishing silently into a flow that looks fine.
+   */
+  const seen = new Set<string>();
+  const build = (name: string | null | undefined): Row | undefined => {
+    if (!name) return undefined;
+    const node = byName.get(name);
+    if (!node) return undefined;
+    if (seen.has(name)) {
+      throw new Error(`flow codec: node ${JSON.stringify(name)} is reachable twice — the chain has a cycle`);
+    }
+    seen.add(name);
+
+    const { _nextAction, _firstLoopAction, _children, ...rest } = node;
+    const out: Row = { ...(rest as Row) };
+    if (_firstLoopAction) {
+      const first = build(String(_firstLoopAction));
+      if (first) out['firstLoopAction'] = first;
+    }
+    if (_children) {
+      out['children'] = (_children as Array<string | null>).map((c) => build(c ?? undefined) ?? null);
+    }
+    if (_nextAction) {
+      const next = build(String(_nextAction));
+      if (next) out['nextAction'] = next;
+    }
+    return out;
+  };
+
+  const trigger = build(tree.nodes[0]?.name);
+  return { ...tree.flow, version: { ...tree.version, ...(trigger ? { trigger } : {}) } };
+};
+
+export type RoundTripResult = { ok: boolean; differences: Array<{ where: string; detail: string }> };
+
+/**
+ * `link(unlink(F))` must equal `F`. The exit criterion PLAN-IPAAS sets for the
+ * read path, checked per flow rather than asserted once.
+ *
+ * A linear chain is the easy case; routers with empty branches and nested loops
+ * are where a fold like this breaks, so this runs on every pull.
+ */
+export const assertFlowRoundTrip = (flowRow: Row): RoundTripResult => {
+  const differences: Array<{ where: string; detail: string }> = [];
+  let rebuilt: Row;
+  try {
+    rebuilt = linkFlow(unlinkFlow(flowRow));
+  } catch (e) {
+    return { ok: false, differences: [{ where: '$', detail: (e as Error).message }] };
+  }
+
+  const a = canonicalString(flowRow);
+  const b = canonicalString(rebuilt);
+  if (a === b) return { ok: true, differences: [] };
+
+  // Narrow it to the node that drifted; "the flow differs" is not actionable.
+  const before = unlinkFlow(flowRow);
+  const after = unlinkFlow(rebuilt);
+  if (before.nodes.length !== after.nodes.length) {
+    differences.push({
+      where: 'nodes',
+      detail:
+        `${before.nodes.length} nodes before, ${after.nodes.length} after — ` +
+        `${before.nodes
+          .map((n) => n.name)
+          .filter((n) => !after.nodes.some((m) => m.name === n))
+          .join(', ') || 'order changed'} did not survive`,
+    });
+  }
+  for (const n of before.nodes) {
+    const m = after.nodes.find((x) => x.name === n.name);
+    if (!m) continue;
+    if (canonicalString(n) !== canonicalString(m)) {
+      const keys = [...new Set([...Object.keys(n), ...Object.keys(m)])].filter(
+        (k) => canonicalString(n[k]) !== canonicalString(m[k]),
+      );
+      differences.push({ where: `node ${n.name}`, detail: `differs at ${keys.join(', ')}` });
+    }
+  }
+  if (canonicalString(before.version) !== canonicalString(after.version)) {
+    differences.push({ where: 'version', detail: 'the version row differs' });
+  }
+  if (!differences.length) differences.push({ where: '$', detail: 'canonical forms differ but no node did' });
+  return { ok: false, differences };
+};
+
+/** The node names a flow reaches, in execution order. */
+export const nodeOrder = (tree: FlowTree): string[] => tree.nodes.map((n) => n.name);
+
+/**
+ * Which nodes run strictly before a given one.
+ *
+ * Execution order is the array order, which is depth-first through the chain — so
+ * a node in one router branch does precede a node in a later branch positionally
+ * while never running with it. That is why this walks the links instead: only the
+ * nodes on the path from the trigger to this node can be referenced by it.
+ */
+export const ancestorsOf = (tree: FlowTree, name: string): Set<string> => {
+  const byName = new Map(tree.nodes.map((n) => [n.name, n]));
+  const path: string[] = [];
+  const found = new Set<string>();
+
+  const walk = (current: string | null | undefined): boolean => {
+    if (!current) return false;
+    const node = byName.get(current);
+    if (!node) return false;
+    if (current === name) {
+      for (const p of path) found.add(p);
+      return true;
+    }
+    path.push(current);
+    const branches: Array<string | null | undefined> = [
+      node['_firstLoopAction'] as string | undefined,
+      ...(((node['_children'] as Array<string | null>) ?? []) as Array<string | null>),
+      node['_nextAction'] as string | undefined,
+    ];
+    for (const b of branches) if (walk(b ?? undefined)) return true;
+    path.pop();
+    return false;
+  };
+
+  walk(tree.nodes[0]?.name);
+  return found;
+};

package/src/codec/pack.ts

@@ -0,0 +1,103 @@
+import { emptyRelations, type PayloadEnvelope, type RepoPayload, type Row } from '../model/payload.ts';
+import type { ConditionNode, Tree } from '../model/tree.ts';
+
+/**
+ * tree → payload. The exact inverse of unpack: it restores the owner-pointer
+ * columns that folding dropped and re-flattens the arrays.
+ *
+ * PLAN.md §3 — pack is not on v1's write path, and is built anyway, because it
+ * is the only rigorous proof that unpack is lossless, and because it is v2's
+ * engine arriving pre-tested.
+ */
+
+const num = (v: unknown): number | null => {
+  if (v === null || v === undefined || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+export const unfoldCondition = (
+  cond: ConditionNode,
+  sourceType: 'Automation' | 'FieldCondition',
+  sourceId: unknown,
+  conditions: Row[],
+  expressions: Row[],
+) => {
+  const { expressions: exprs, ...rest } = cond;
+  const condRow: Row = { ...rest, source_type: sourceType, source_id: sourceId };
+  conditions.push(condRow);
+  for (const e of exprs ?? []) {
+    expressions.push({ ...e, condition_id: condRow['id'] ?? null });
+  }
+};
+
+export const pack = (tree: Tree): RepoPayload => {
+  const relations = emptyRelations();
+
+  for (const phase of tree.phases) {
+    const { fields, jump_target_ids, team_member_ids, ...phaseRow } = phase;
+    const memberKey = String((phaseRow as Row)['_team_member_key'] ?? 'user_id');
+    relations.phases.push(phaseRow as Row);
+
+    for (const f of fields ?? []) {
+      relations.fields.push({ ...f, phase_id: num(phaseRow['id']) ?? phaseRow['id'] });
+    }
+    for (const t of jump_target_ids ?? []) {
+      relations.phase_jumps.push({ source_phase_id: num(phaseRow['id']), target_phase_id: num(t) });
+    }
+    for (const m of team_member_ids ?? []) {
+      relations.phase_team_memberships.push({ phase_id: num(phaseRow['id']), [memberKey]: num(m) });
+    }
+  }
+
+  for (const auto of tree.automations) {
+    const { condition, field_maps, distribute_assignments, response_schemas, ...autoRow } = auto;
+    relations.automations.push(autoRow as Row);
+    const id = autoRow['id'];
+    if (condition) unfoldCondition(condition, 'Automation', id, relations.conditions, relations.condition_expressions);
+    for (const m of field_maps ?? []) {
+      relations.field_maps.push({ ...m, owner_type: 'Automation', owner_id: id });
+    }
+    for (const d of distribute_assignments ?? []) {
+      relations.distribute_assignments.push({ ...d, automation_id: id });
+    }
+    for (const s of response_schemas ?? []) {
+      relations.response_schemas.push({ ...s, automation_id: id });
+    }
+  }
+
+  for (const fc of tree.field_conditions) {
+    const { actions, condition, ...fcRow } = fc;
+    relations.field_conditions.push(fcRow as Row);
+    for (const a of actions ?? []) {
+      relations.field_condition_actions.push({ ...a, field_condition_id: fcRow['id'] });
+    }
+    if (condition) {
+      unfoldCondition(condition, 'FieldCondition', fcRow['id'], relations.conditions, relations.condition_expressions);
+    }
+  }
+
+  relations.labels = tree.labels.map((r) => ({ ...r }));
+  relations.webhooks = tree.webhooks.map((r) => ({ ...r }));
+  relations.pipe_relations = tree.pipe_relations.map((r) => ({ ...r }));
+  relations.public_forms = tree.public_form ? [{ ...tree.public_form }] : [];
+  relations.repo_preferences = tree.preferences ? [{ ...tree.preferences }] : [];
+  relations.email_templates = tree.readonly.email_templates.map((r) => ({ ...r }));
+  relations.email_inboxes = tree.readonly.email_inboxes.map((r) => ({ ...r }));
+  relations.visibilities = tree.readonly.visibilities.map((r) => ({ ...r }));
+  // Restores the non-Automation field_maps rows the loop above never sees.
+  for (const m of tree.readonly.field_maps) relations.field_maps.push({ ...m });
+
+  return { ...tree.repo, id: Number(tree.repo['id']), relations };
+};
+
+/** Pack back into an envelope, preserving the provenance the tree carries. */
+export const packEnvelope = (tree: Tree): PayloadEnvelope => ({
+  source: tree.meta.source,
+  versionId: tree.meta.versionId ?? null,
+  readAt: tree.meta.readAt,
+  repoKind: tree.meta.repoKind,
+  coverage: tree.meta.coverage,
+  notes: tree.meta.notes,
+  payload: pack(tree),
+});

package/src/codec/roundtrip.ts

@@ -0,0 +1,94 @@
+import { canonical, canonicalString, type Json } from '../util/json.ts';
+import { ENTITIES, ENTITY_NAMES, type EntityName, type RepoPayload, type Row } from '../model/payload.ts';
+import { VOLATILE_KEYS } from '../model/volatile.ts';
+import { pack } from './pack.ts';
+import { unpack } from './unpack.ts';
+import type { PayloadEnvelope } from '../model/payload.ts';
+
+/**
+ * `pack(unpack(P)) ≡ P` under a canonical form — PLAN.md §3, corrected there
+ * from byte equality to semantic equality. Chasing byte-identity would waste a
+ * week and then fail: JSON.parse turns `index: 6.0` into `6`.
+ *
+ * Two normalisations beyond canonical JSON, both principled rather than
+ * convenient:
+ *
+ *  1. Volatile columns are dropped from both sides. The codec strips them by
+ *     design (PLAN.md §9); comparing them would only ever report noise.
+ *  2. For `owned` entities — the fourteen arrays with no `uuid` and no
+ *     identity of their own — `id` is dropped. ROUTE-B-V2.md §4 argues these
+ *     are replace-sets under their owner, which is precisely the claim that
+ *     their `id` is not identity. Rows are then compared as sorted sets.
+ *
+ * Anything else that differs is a real codec bug and blocks planning.
+ */
+
+const stripDeep = (v: unknown): unknown => {
+  if (Array.isArray(v)) return v.map(stripDeep);
+  if (v && typeof v === 'object') {
+    const out: Row = {};
+    for (const [k, val] of Object.entries(v as Row)) {
+      if (VOLATILE_KEYS.has(k)) continue;
+      if (k.startsWith('_')) continue; // tool metadata, never pipe structure
+      out[k] = stripDeep(val);
+    }
+    return out;
+  }
+  return v;
+};
+
+const normaliseRows = (name: EntityName, rows: Row[]): Json => {
+  const owned = ENTITIES[name].identity === 'owned';
+  const cleaned = rows.map((r) => {
+    const row = stripDeep(r) as Row;
+    if (owned) delete row['id'];
+    return canonicalString(row);
+  });
+  // Owned rows are sets; identified rows keep their order-independent identity
+  // too, so sorting is safe for both and removes ordering noise the codec
+  // introduces by grouping fields under phases.
+  return cleaned.sort() as unknown as Json;
+};
+
+export type RoundTripDiff = {
+  ok: boolean;
+  differences: Array<{ where: string; detail: string }>;
+};
+
+export const compare = (before: RepoPayload, after: RepoPayload): RoundTripDiff => {
+  const differences: RoundTripDiff['differences'] = [];
+
+  const rootBefore = canonical(stripDeep({ ...before, relations: undefined })) as Record<string, Json>;
+  const rootAfter = canonical(stripDeep({ ...after, relations: undefined })) as Record<string, Json>;
+  const rootKeys = new Set([...Object.keys(rootBefore), ...Object.keys(rootAfter)]);
+  for (const k of [...rootKeys].sort()) {
+    const a = JSON.stringify(rootBefore[k]);
+    const b = JSON.stringify(rootAfter[k]);
+    if (a !== b) differences.push({ where: `repo.${k}`, detail: `${a} -> ${b}` });
+  }
+
+  for (const name of ENTITY_NAMES) {
+    const a = normaliseRows(name, before.relations?.[name] ?? []) as unknown as string[];
+    const b = normaliseRows(name, after.relations?.[name] ?? []) as unknown as string[];
+    if (JSON.stringify(a) === JSON.stringify(b)) continue;
+
+    if (a.length !== b.length) {
+      differences.push({ where: name, detail: `${a.length} rows before, ${b.length} after` });
+    }
+    const setB = new Set(b);
+    const lost = a.filter((r) => !setB.has(r));
+    const setA = new Set(a);
+    const gained = b.filter((r) => !setA.has(r));
+    for (const l of lost.slice(0, 3)) differences.push({ where: `${name} (lost)`, detail: l.slice(0, 300) });
+    for (const g of gained.slice(0, 3)) differences.push({ where: `${name} (gained)`, detail: g.slice(0, 300) });
+    if (lost.length + gained.length > 6) {
+      differences.push({ where: name, detail: `…and ${lost.length + gained.length - 6} more row differences` });
+    }
+  }
+
+  return { ok: differences.length === 0, differences };
+};
+
+/** The Phase 0 exit criterion, callable on any payload. */
+export const assertRoundTrip = (env: PayloadEnvelope): RoundTripDiff =>
+  compare(env.payload, pack(unpack(env)));