@pipefy/pipefy-process-coder 0.1.0

package/src/diff/diff.ts

@@ -0,0 +1,1130 @@
+import { canonicalString } from '../util/json.ts';
+import { VOLATILE_KEYS } from '../model/volatile.ts';
+import { ENTITIES, type Coverage, type EntityName, type Row } from '../model/payload.ts';
+import type { AutomationNode, FieldConditionNode, PhaseNode, Tree } from '../model/tree.ts';
+
+/**
+ * The diff engine, modelled on what the Change Migrator recipes actually do.
+ *
+ * The recipes reduce a migration to one list per entity type, each row tagged
+ * create / update / delete, and then walk those lists in a fixed order:
+ * phases → start-form fields → phase fields → field conditions → automations
+ * (`Apply Changes` steps 4, 30, 45, 65, 116). This produces the same ChangeSet,
+ * with two things the recipes do by hand:
+ *
+ *  - **Matching.** The recipes match phases by name and fields through a Pipefy
+ *    table keyed `dev_pipe_field_internal_id → prod_pipe_field_internal_id`.
+ *    Here, `same-repo` mode matches on uuid then id — exact, no lookups — and
+ *    `cross-repo` mode falls back to the natural key (phase name, phase+label,
+ *    automation name), which is the recipes' rule, and records the id map so
+ *    embedded field references can be rewritten.
+ *  - **Nesting.** Conditions, field_maps and condition actions are applied
+ *    through their owner, so a change to one is reported as a change to the
+ *    owner rather than as an independent change that could be ordered wrongly.
+ */
+
+export type ChangeOp = 'create' | 'update' | 'delete' | 'reorder' | 'archive' | 'unarchive';
+
+export type FieldDelta = { key: string; before: unknown; after: unknown };
+
+export type Change = {
+  entity: EntityName | 'repo';
+  op: ChangeOp;
+  /** Stable identity for this change: uuid, id, or owner+natural key. */
+  key: string;
+  /** Human label, for the CLI and the viewer. */
+  label: string;
+  /** Workspace-relative file the change came from, when there is one. */
+  file?: string;
+  before?: Row | null;
+  after?: Row | null;
+  deltas: FieldDelta[];
+  /** For nested/owned entities: what owns this change. */
+  owner?: { entity: EntityName; key: string; label: string };
+  /** Set when a change is a special case the planner treats differently. */
+  flags: string[];
+};
+
+export type ChangeSet = {
+  mode: 'same-repo' | 'cross-repo';
+  from: { repoId: number; name: string; source: string };
+  to: { repoId: number; name: string; source: string };
+  changes: Change[];
+  /** Entity groups skipped because one side had no read path for them. */
+  skipped: Array<{ entity: EntityName; reason: string }>;
+  /**
+   * uuid/natural-key → id map, per entity, built while matching. This is the
+   * recipes' dev→prod lookup table, computed locally instead of by an API call
+   * per id.
+   */
+  idMap: Partial<Record<EntityName, Record<string, number>>>;
+};
+
+// ── comparison ───────────────────────────────────────────────────────────────
+
+const IGNORED_IN_COMPARISON = new Set([...VOLATILE_KEYS, 'id', 'repo_id', 'organization_id', 'organization_uuid']);
+
+
+/**
+ * Keys holding an id, compared as strings.
+ *
+ * Pipefy is inconsistent about whether an id is `12345` or `"12345"` —
+ * the payload uses numbers, the APIs mostly strings — and an id is the same id
+ * either way. Comparing them typed reported changes on values that matched.
+ */
+const ID_VALUED_KEYS = new Set([
+  'phase_id', 'field_id', 'to_phase_id', 'from_phase_id', 'in_phase_id', 'card_id',
+  'title_field_id', 'connected_pipe_id', 'source_id', 'owner_id', 'field_address',
+  'target_phase_id', 'source_phase_id', 'action_repo_id', 'event_repo_id',
+  'submitter_email_field_id', 'email_template_id', 'field_condition_id',
+]);
+
+const looseId = (v: unknown): unknown =>
+  typeof v === 'number' ? String(v) : v;
+
+/**
+ * Text columns where the endpoint uses `null` and `""` interchangeably.
+ *
+ * Kept to a named set rather than applied to every string column, because
+ * elsewhere the difference between "unset" and "set to empty" can carry meaning.
+ * These four were measured returning both spellings from the same read.
+ */
+const EMPTY_EQUIVALENT = new Set(['description', 'help', 'custom_validation', 'index_name']);
+
+const isBlank = (v: unknown) => v === null || v === undefined || v === '';
+
+const comparable = (row: Row, extraIgnore: Set<string> = new Set()): Row => {
+  const out: Row = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (IGNORED_IN_COMPARISON.has(k) || extraIgnore.has(k) || k.startsWith('_')) continue;
+    out[k] = ID_VALUED_KEYS.has(k) ? looseId(v) : v;
+  }
+  return out;
+};
+
+/**
+ * Which side of a comparison read this entity group only partially.
+ *
+ * Coverage is tracked per group, but a *partial* read is partial per column: the
+ * public API has no `color_uuid`, no `only_admin_can_move_to_previous`, no
+ * `authorization`. Comparing a snapshot against a reconstruction without this,
+ * a real pipe reported ten "changes" per phase, every one of them a column the
+ * reconstruction simply cannot see — and every one of them a proposal to set it
+ * to null.
+ *
+ * So absence on a partial side is treated as no information, exactly as an
+ * `unknown` group is. Absence on a *complete* side still means null.
+ */
+type PartialSides = { before: boolean; after: boolean };
+
+const NO_PARTIAL: PartialSides = { before: false, after: false };
+
+/**
+ * Columns the server mints, which no create path accepts.
+ *
+ * When verifying intent, a null on the authored side of one of these is the
+ * absence of an opinion, not a request to clear it: `createPhaseField` derives
+ * the slug from the label, `createPhase` picks a `color_uuid`, and neither takes
+ * the value as input. Comparing them turned 60 successful creates into 60
+ * reported failures. A value the author *did* write is still asserted.
+ */
+const SERVER_MINTED = new Set(['slug', 'color_uuid', 'suid']);
+
+/**
+ * Column names the payload never uses, per entity.
+ *
+ * `createPipeRelation` names three of its flags `canCreateNewItems`,
+ * `canConnectExistingItems` and `canConnectMultipleItems`; the payload row
+ * spells the same three `can_create_connected_cards`, `can_search_connected_cards`
+ * and `can_connect_multiple_cards`. An author who writes the mutation's spelling
+ * — the one the API documents — gets a row whose keys no read can ever produce,
+ * and comparing them reported three differences on a relation that was exactly
+ * right. They are aliases, dropped from comparison; the payload spellings beside
+ * them are compared normally, because those the payload does carry.
+ */
+const UNREADABLE_IN_PAYLOAD: Partial<Record<EntityName, Set<string>>> = {
+  pipe_relations: new Set([
+    'can_create_new_items',
+    'can_connect_existing_items',
+    'can_connect_multiple_items',
+  ]),
+};
+
+/**
+ * Two jump target lists, compared as the sets they are.
+ *
+ * `PUT /internal_api/settings/phases/:id` replaces the whole set (PLAN.md §2.1)
+ * and answers in whatever order it likes, so ordering carries no meaning on
+ * either side. Comparing them as ordered lists reported a phase whose jumps were
+ * exactly right as needing another write — every single run.
+ */
+const sameIdSet = (x: unknown, y: unknown): boolean => {
+  const norm = (v: unknown) =>
+    JSON.stringify(
+      (Array.isArray(v) ? v : [])
+        .map((n) => String(n))
+        .sort(),
+    );
+  return norm(x) === norm(y);
+};
+
+/**
+ * `intentOnly` compares only the columns the *after* side actually states.
+ *
+ * This is what verification means. A newly authored entity is a partial
+ * specification: the author writes the columns they care about and the server
+ * fills the rest — `slug`, `card_synced`, `unique`, the connector flags. Asking
+ * "are these rows identical" then fails a perfectly correct apply, reporting
+ * seven differences per created field, all of them defaults the author never
+ * spoke about. Asking "does the live pipe satisfy the intent" is both the useful
+ * question and the answerable one.
+ *
+ * Off for the ordinary edit-loop diff, where both sides come from full reads and
+ * an absent column really is information.
+ */
+const deltasOf = (
+  before: Row,
+  after: Row,
+  extraIgnore?: Set<string>,
+  partial: PartialSides = NO_PARTIAL,
+  intentOnly = false,
+): FieldDelta[] => {
+  const a = comparable(before, extraIgnore);
+  const b = comparable(after, extraIgnore);
+  const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  const out: FieldDelta[] = [];
+  for (const k of keys) {
+    if (intentOnly && !(k in b)) continue;
+
+    /**
+     * A client-minted uuid on a new entity is a local handle, not a request.
+     * `CreatePhaseFieldInput` has no `uuid` field — the introspection filter drops
+     * it and the server mints its own — so verification must not assert a value
+     * that was never sent. The post-apply sync replaces the handle with the real
+     * uuid, and from then on it is compared normally.
+     */
+    /**
+     * A uuid is never asserted when verifying intent.
+     *
+     * No create path on this endpoint accepts one — `CreatePhaseFieldInput` and
+     * the internal `createAutomation` both lack the field, and the server mints
+     * its own — so a uuid is always server-owned and never something the tool
+     * asked for. It also cannot survive the recreate strategy: delete + create
+     * is the only automation update available, and it necessarily yields a new
+     * uuid, which verification would otherwise report as a failed apply.
+     */
+    if (intentOnly && k === 'uuid') continue;
+
+    /**
+     * Nor is a slug the author never wrote.
+     *
+     * `CreatePhaseFieldInput` has no slug either: the server derives one from the
+     * label. A field authored by hand therefore says `"slug": null`, and after a
+     * successful create the pipe says `"slug": "request_title"` — which
+     * verification would report as 55 failed field creates, all of which
+     * actually succeeded. A slug the author *did* write is still asserted, since
+     * automations and conditions can legitimately reference one.
+     */
+    if (intentOnly && SERVER_MINTED.has(k) && (b[k] === null || b[k] === undefined)) continue;
+
+    const aRaw = a[k] ?? null;
+    const bRaw = b[k] ?? null;
+
+    /**
+     * On a text column, `null` and `""` are the same absence.
+     *
+     * Both spellings come back from the same endpoint for the same column, on
+     * the same repo — measured across ten fields of three databases:
+     * `description` was `""` nine times and `null` once, `help` the same, and
+     * `custom_validation` `""` eight times and `null` twice. So a field whose
+     * file says `""` verifies against a pipe that says `null` and reports
+     * `custom_validation: null -> ""`, which is a difference nobody can act on
+     * and which blocks the file sync.
+     *
+     * Only the empty pair collapses. Clearing a real value to `""` still differs
+     * from that value, which is the change an author actually makes.
+     */
+    if (EMPTY_EQUIVALENT.has(k) && isBlank(aRaw) && isBlank(bRaw)) continue;
+
+    const av = canonicalString(ID_VALUED_KEYS.has(k) ? looseId(aRaw) : aRaw);
+    const bv = canonicalString(ID_VALUED_KEYS.has(k) ? looseId(bRaw) : bRaw);
+    if (av === bv) continue;
+
+    /**
+     * An unresolved placeholder in the intent was a request to substitute, and
+     * the substitution is what the pipe now holds. Verify cannot assert the id
+     * the server chose unless it has the plan's id map (which `pipe apply`
+     * passes in), so a placeholder is treated as satisfied.
+     */
+    if (intentOnly && typeof bRaw === 'string' && bRaw.includes('%{_new:')) continue;
+    if (intentOnly && JSON.stringify(bRaw ?? '').includes('%{_new:')) continue;
+
+    if (partial.after && bRaw === null && aRaw !== null) continue;
+    if (partial.before && aRaw === null && bRaw !== null) continue;
+
+    out.push({ key: k, before: aRaw, after: bRaw });
+  }
+  return out;
+};
+
+/** Owned rows have no identity, so they are compared as sorted sets. */
+const setOf = (rows: Row[]): string[] =>
+  rows.map((r) => canonicalString(comparable(r))).sort();
+
+const sameSet = (a: Row[], b: Row[]) => canonicalString(setOf(a)) === canonicalString(setOf(b));
+
+/**
+ * Whether a nested collection differs *informatively*.
+ *
+ * The collection counterpart of the column and row rules. Measured: the internal
+ * automations endpoint returns no `field_map` for four `update_card_field`
+ * automations a snapshot shows five entries for, and no `condition` for one that
+ * has one. Reported literally, that is "empty every field map" — so an empty
+ * collection on a partial side is unseen, not emptied.
+ */
+const hasPlaceholder = (v: unknown): boolean => JSON.stringify(v ?? '').includes('%{_new:');
+
+/**
+ * A nested structure, normalised for comparison at every depth.
+ *
+ * `comparable` only ever reached the top level of a row, so a nested collection
+ * was compared raw. That made a freshly created field condition impossible to
+ * verify: the server mints an `id` on the condition and on every expression, and
+ * stores `expressions_structure` leaves as strings where the workspace writes
+ * numbers, so the read-back never equalled the intent no matter what was sent.
+ *
+ * Numbers become strings here, at every depth, for the same reason `looseId`
+ * exists: this payload is inconsistent about `0` versus `"0"` and they are the
+ * same value. Applied only to nested structures, so column deltas keep comparing
+ * types as they always did.
+ */
+const nestedComparable = (v: unknown): unknown => {
+  if (Array.isArray(v)) return v.map(nestedComparable);
+  if (v && typeof v === 'object') {
+    const out: Row = {};
+    for (const [k, val] of Object.entries(v as Row)) {
+      if (IGNORED_IN_COMPARISON.has(k) || k.startsWith('_')) continue;
+      out[k] = nestedComparable(val);
+    }
+    return out;
+  }
+  return typeof v === 'number' ? String(v) : v;
+};
+
+/**
+ * The live side, reduced to what the intent side actually states — at every depth.
+ *
+ * `deltasOf` already skips a column the intent does not mention (`!(k in b)`).
+ * That rule stopped at the top level, so a nested key the workspace never wrote
+ * still failed verification: `phase_id` on a field condition action, and
+ * `structure_id` on an expression, are both added by the server.
+ *
+ * Array elements are reduced against the union of the keys their intent
+ * counterparts state, rather than pairwise by position, so element order cannot
+ * mis-pair them. That can only relax the comparison, never tighten it — the
+ * outer comparison still sorts, so a real difference in the values still shows.
+ */
+const asStated = (live: unknown, intent: unknown): unknown => {
+  if (Array.isArray(live)) {
+    const peers = Array.isArray(intent) ? intent : [];
+    const merged = peers.reduce<Row>(
+      (acc, e) => (e && typeof e === 'object' && !Array.isArray(e) ? { ...acc, ...(e as Row) } : acc),
+      {},
+    );
+    const shape = Object.keys(merged).length ? merged : peers[0];
+    return live.map((l) => asStated(l, shape));
+  }
+  if (live && typeof live === 'object' && intent && typeof intent === 'object' && !Array.isArray(intent)) {
+    const out: Row = {};
+    for (const [k, val] of Object.entries(live as Row)) {
+      if (!(k in (intent as Row))) continue;
+      out[k] = asStated(val, (intent as Row)[k]);
+    }
+    return out;
+  }
+  return live;
+};
+
+const nestedSame = (a: unknown, b: unknown, intentOnly: boolean): boolean => {
+  const left = intentOnly ? asStated(a, b) : a;
+  return canonicalString(nestedComparable(left)) === canonicalString(nestedComparable(b));
+};
+
+const nestedDiffers = (a: Row[], b: Row[], partial: PartialSides, intentOnly = false): boolean => {
+  if (sameSet(a, b)) return false;
+  const norm = (rows: unknown) =>
+    canonicalString((nestedComparable(rows) as unknown[]).map(canonicalString).sort());
+  if (norm(intentOnly ? asStated(a, b) : a) === norm(b)) return false;
+  if (intentOnly && hasPlaceholder(b)) return false;
+  if (partial.after && b.length === 0 && a.length > 0) return false;
+  if (partial.before && a.length === 0 && b.length > 0) return false;
+  return true;
+};
+
+/** The same rule for a single nested object, such as an automation's condition. */
+const nestedObjectDiffers = (a: unknown, b: unknown, partial: PartialSides, intentOnly = false): boolean => {
+  if (canonicalString(a) === canonicalString(b)) return false;
+  if (nestedSame(a, b, intentOnly)) return false;
+  if (intentOnly && hasPlaceholder(b)) return false;
+  if (partial.after && (b === null || b === undefined) && a) return false;
+  if (partial.before && (a === null || a === undefined) && b) return false;
+  return true;
+};
+
+// ── matching ─────────────────────────────────────────────────────────────────
+
+type Matcher<T extends Row> = {
+  /** Primary key: exact, used within one repo. */
+  primary: (row: T) => string | null;
+  /** Fallback key: the recipes' rule, used across two different repos. */
+  natural: (row: T) => string;
+};
+
+const naturalKeyOf = (entity: EntityName, row: Row, ctx: { phaseName?: string } = {}): string => {
+  const spec = ENTITIES[entity];
+  if (entity === 'fields') return `${ctx.phaseName ?? row['phase_id'] ?? ''}::${String(row['label'] ?? '')}`;
+  const keys = spec.naturalKey ?? ['name'];
+  return keys.map((k) => String(row[k] ?? '')).join('::');
+};
+
+const matchRows = <T extends Row>(
+  before: T[],
+  after: T[],
+  m: Matcher<T>,
+  mode: ChangeSet['mode'],
+): { pairs: Array<[T, T]>; added: T[]; removed: T[] } => {
+  const pairs: Array<[T, T]> = [];
+  const usedAfter = new Set<T>();
+  const remainingBefore: T[] = [];
+
+  const afterByPrimary = new Map<string, T>();
+  for (const r of after) {
+    const k = m.primary(r);
+    if (k) afterByPrimary.set(k, r);
+  }
+
+  for (const b of before) {
+    const k = mode === 'same-repo' ? m.primary(b) : null;
+    const hit = k ? afterByPrimary.get(k) : undefined;
+    if (hit && !usedAfter.has(hit)) {
+      pairs.push([b, hit]);
+      usedAfter.add(hit);
+    } else {
+      remainingBefore.push(b);
+    }
+  }
+
+  // Fallback pass on the natural key. Within one repo this catches an entity
+  // whose uuid Claude dropped; across repos it is the primary mechanism.
+  const afterByNatural = new Map<string, T[]>();
+  for (const r of after) {
+    if (usedAfter.has(r)) continue;
+    const k = m.natural(r);
+    const arr = afterByNatural.get(k) ?? [];
+    arr.push(r);
+    afterByNatural.set(k, arr);
+  }
+
+  const removed: T[] = [];
+  for (const b of remainingBefore) {
+    const candidates = afterByNatural.get(m.natural(b));
+    const hit = candidates?.find((c) => !usedAfter.has(c));
+    if (hit) {
+      pairs.push([b, hit]);
+      usedAfter.add(hit);
+    } else {
+      removed.push(b);
+    }
+  }
+
+  const added = after.filter((r) => !usedAfter.has(r));
+  return { pairs, added, removed };
+};
+
+// ── entity diffs ─────────────────────────────────────────────────────────────
+
+const num = (v: unknown): number | null => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+const label = (row: Row, fallback: string) => String(row['name'] ?? row['label'] ?? fallback);
+
+/**
+ * The live condition, reduced to what the intent states, before it is summarised.
+ *
+ * `conditionSummary` canonicalises each expression into a *string* through
+ * `setOf`, so by the time the summary exists there are no keys left to reduce —
+ * a server-minted `structure_id` is already baked into the string and the two
+ * sides can never match. The reduction has to happen first.
+ */
+const statedCondition = (
+  b: { condition?: Row | null },
+  a: { condition?: Row | null },
+  intentOnly: boolean,
+): { condition: Row | null } => ({
+  condition: (intentOnly
+    ? (asStated(b.condition ?? null, a.condition ?? null) as Row | null)
+    : (b.condition ?? null)),
+});
+
+const conditionSummary = (node: { condition?: Row | null }): Row => {
+  const c = node.condition as Row | null | undefined;
+  if (!c) return {};
+  return { expressions_structure: c['expressions_structure'] ?? [], expressions: setOf((c['expressions'] as Row[]) ?? []) };
+};
+
+export type DiffOpts = {
+  mode?: ChangeSet['mode'];
+  /**
+   * Compare only the columns the target side states. Set by `pipe verify`:
+   * see deltasOf.
+   */
+  intentOnly?: boolean;
+  /**
+   * Ids this apply created. Pipefy auto-links a new phase with its neighbour in
+   * both directions, so the neighbour ends up with a jump the workspace never
+   * asked for. A jump-set difference made up only of ids created just now is the
+   * platform's doing, not a failed write.
+   */
+  createdIds?: number[];
+  /** Ignore an entity group entirely — used for coverage gaps. */
+  skipEntities?: EntityName[];
+};
+
+export const diffTrees = (before: Tree, after: Tree, opts: DiffOpts = {}): ChangeSet => {
+  const mode = opts.mode ?? 'same-repo';
+  const intentOnly = opts.intentOnly ?? false;
+  const createdIds = new Set((opts.createdIds ?? []).map(Number));
+
+  /** True when two jump sets differ only by ids this apply created. */
+  const jumpsDifferOnlyByNewIds = (x: Array<number | string>, y: Array<number | string>): boolean => {
+    if (!createdIds.size) return false;
+    const sx = new Set(x.map(Number));
+    const sy = new Set(y.map(Number));
+    const only = [...sx].filter((v) => !sy.has(v)).concat([...sy].filter((v) => !sx.has(v)));
+    return only.length > 0 && only.every((v) => createdIds.has(v));
+  };
+  const changes: Change[] = [];
+  const skipped: ChangeSet['skipped'] = [];
+  const idMap: ChangeSet['idMap'] = {};
+
+  /**
+   * An entity group neither read path could see is not diffed. This is the
+   * whole reason coverage is tracked: a reconstructed pull cannot tell "no
+   * webhooks" from "cannot read webhooks", and proposing deletions from the
+   * second would be catastrophic.
+   */
+  const skipSet = new Set<EntityName>(opts.skipEntities ?? []);
+
+  /** Which sides read this group only partially. See deltasOf. */
+  const partialSides = (entity: EntityName): PartialSides => ({
+    before: (before.meta.coverage?.[entity] ?? 'unknown') === 'partial',
+    after: (after.meta.coverage?.[entity] ?? 'unknown') === 'partial',
+  });
+
+  /**
+   * Whether a row's absence from one side is evidence of anything.
+   *
+   * The row-level counterpart of the column rule, and the more dangerous of the
+   * two. Measured on a real pipe: the internal automations list returns 13 of the
+   * 15 automations a snapshot contains. Diffed naively, the two it omits are
+   * "deletes" — and an apply would have deleted two live automations because one
+   * read path could not see them.
+   *
+   * So on a partial side, absence means unseen: a delete is suppressed when the
+   * *after* side is partial, and a create when the *before* side is partial.
+   */
+  const suppressed: Array<{ entity: EntityName; op: 'create' | 'delete'; label: string }> = [];
+  const rowAbsenceIsUnknown = (entity: EntityName, op: 'create' | 'delete', label: string): boolean => {
+    const sides = partialSides(entity);
+    const unknown = op === 'delete' ? sides.after : sides.before;
+    if (unknown) suppressed.push({ entity, op, label });
+    return unknown;
+  };
+
+  /**
+   * The repo row is not an entity group, so its partial-ness comes from the read
+   * path: a reconstruction that had to skip pipe columns records that in
+   * meta.repo_columns.
+   */
+  const repoPartial: PartialSides = {
+    before: before.meta.repo_columns === 'partial',
+    after: after.meta.repo_columns === 'partial',
+  };
+  const coverageBlocked = (entity: EntityName): boolean => {
+    if (skipSet.has(entity)) return true;
+    const a: Coverage = before.meta.coverage?.[entity] ?? 'unknown';
+    const b: Coverage = after.meta.coverage?.[entity] ?? 'unknown';
+    if (a === 'unknown' || b === 'unknown') {
+      skipped.push({
+        entity,
+        reason: `coverage is ${a === 'unknown' ? 'unknown on the baseline' : 'unknown on the edited tree'} — not diffed, so absence is never read as deletion`,
+      });
+      return true;
+    }
+    return false;
+  };
+
+  const record = (c: Omit<Change, 'deltas' | 'flags'> & Partial<Pick<Change, 'deltas' | 'flags'>>) => {
+    changes.push({ deltas: [], flags: [], ...c } as Change);
+  };
+
+  // ── repo row ───────────────────────────────────────────────────────────────
+  const repoDeltas = deltasOf(before.repo, after.repo, undefined, repoPartial, intentOnly);
+  if (repoDeltas.length) {
+    record({
+      entity: 'repo',
+      op: 'update',
+      key: `repo:${after.repo['id']}`,
+      label: String(after.repo['name'] ?? 'pipe'),
+      file: 'pipe.json',
+      before: before.repo,
+      after: after.repo,
+      deltas: repoDeltas,
+    });
+  }
+
+  // ── phases (+ fields, jumps, memberships) ──────────────────────────────────
+  const phaseMatcher: Matcher<PhaseNode> = {
+    primary: (p) => (p['uuid'] ? `uuid:${p['uuid']}` : p['id'] ? `id:${p['id']}` : null),
+    natural: (p) => naturalKeyOf('phases', p),
+  };
+  const phaseMatch = matchRows(before.phases, after.phases, phaseMatcher, mode);
+
+  const phaseIdMap: Record<string, number> = {};
+  for (const [b, a] of phaseMatch.pairs) {
+    const bid = num(b['id']);
+    const aid = num(a['id']);
+    if (bid !== null && aid !== null) phaseIdMap[String(bid)] = aid;
+  }
+  idMap.phases = phaseIdMap;
+
+  /**
+   * Field changes are collected before they are recorded.
+   *
+   * Fields are matched inside their phase, so a field moved from one phase to
+   * another looks like a delete here and a create there. Compiling that pair
+   * literally would delete the field and its data and recreate it empty —
+   * precisely the loss PLAN.md §2 says must be refused. So the pair is
+   * reconciled afterwards into one `fields.update` carrying a `phase_id` delta,
+   * which the registry then refuses by name.
+   */
+  const fieldChanges: Change[] = [];
+  const pushField = (c: Omit<Change, 'deltas' | 'flags'> & Partial<Pick<Change, 'deltas' | 'flags'>>) => {
+    fieldChanges.push({ deltas: [], flags: [], ...c } as Change);
+  };
+
+  for (const p of phaseMatch.added) {
+    if (rowAbsenceIsUnknown('phases', 'create', label(p, 'phase'))) continue;
+    record({
+      entity: 'phases',
+      op: 'create',
+      key: phaseMatcher.primary(p) ?? `new:${naturalKeyOf('phases', p)}`,
+      label: label(p, 'phase'),
+      after: p,
+      flags: ['new-phase'],
+    });
+    // A new phase's fields are created with it, as separate steps.
+    for (const f of p.fields) {
+      pushField({
+        entity: 'fields',
+        op: 'create',
+        key: f['uuid'] ? `uuid:${f['uuid']}` : `new:${naturalKeyOf('fields', f, { phaseName: label(p, '') })}`,
+        label: `${label(p, 'phase')} / ${label(f, 'field')}`,
+        after: f,
+        owner: { entity: 'phases', key: phaseMatcher.primary(p) ?? '', label: label(p, 'phase') },
+      });
+    }
+  }
+
+  for (const p of phaseMatch.removed) {
+    if (rowAbsenceIsUnknown('phases', 'delete', label(p, 'phase'))) continue;
+    record({
+      entity: 'phases',
+      op: 'delete',
+      key: phaseMatcher.primary(p) ?? `gone:${naturalKeyOf('phases', p)}`,
+      label: label(p, 'phase'),
+      before: p,
+      flags: Number(p['index']) === 0 ? ['start-form', 'destructive'] : ['destructive'],
+    });
+  }
+
+  for (const [b, a] of phaseMatch.pairs) {
+    const phaseLabel = label(a, 'phase');
+    const ownerKey = phaseMatcher.primary(a) ?? '';
+
+    const pDeltas = deltasOf(b, a, new Set(['fields', 'jump_target_ids', 'team_member_ids', 'index']), partialSides('phases'), intentOnly);
+    if (pDeltas.length) {
+      record({
+        entity: 'phases',
+        op: 'update',
+        key: ownerKey,
+        label: phaseLabel,
+        before: b,
+        after: a,
+        deltas: pDeltas,
+        // Only the name is refused (compile.ts) — everything else about the
+        // start form (description, lateness, and the like) is an ordinary
+        // update. Tagged the same way its delete already is, rather than a
+        // second mechanism, so both live in one place.
+        flags: Number(a['index']) === 0 ? ['start-form'] : [],
+      });
+    }
+
+    if (num(b['index']) !== num(a['index'])) {
+      record({
+        entity: 'phases',
+        op: 'reorder',
+        key: ownerKey,
+        label: phaseLabel,
+        before: b,
+        after: a,
+        deltas: [{ key: 'index', before: b['index'], after: a['index'] }],
+        flags: ['phase-reorder'],
+      });
+    }
+
+    /**
+     * A newly created phase gets jumps whether it asks for them or not: Pipefy
+     * auto-links a new phase with its neighbour in both directions. So an empty
+     * stated set on a new phase is an absence of instruction, not an instruction
+     * — a create path has no way to say "and nothing else" — and verification
+     * must not fail on the platform's default. A *stated* non-empty set is real
+     * intent and is written; see compile.ts.
+     */
+    const newPhaseWithoutStatedJumps =
+      intentOnly && (a['_new'] === true || a['id'] === null) && (a.jump_target_ids ?? []).length === 0;
+
+    if (
+      !coverageBlocked('phase_jumps') &&
+      !newPhaseWithoutStatedJumps &&
+      !sameIdSet(b.jump_target_ids, a.jump_target_ids) &&
+      !(intentOnly && jumpsDifferOnlyByNewIds(b.jump_target_ids, a.jump_target_ids))
+    ) {
+      record({
+        entity: 'phase_jumps',
+        op: 'update',
+        key: `jumps:${ownerKey}`,
+        label: `${phaseLabel} → jumps`,
+        // The phase's numeric id travels with the change. The matcher key is
+        // "uuid:<uuid>" for a phase, and stripping that prefix yielded a uuid
+        // where the settings endpoint wants an id — a silent 404 on write.
+        before: { phase_id: b['id'], jump_target_ids: b.jump_target_ids },
+        after: { phase_id: a['id'], jump_target_ids: a.jump_target_ids },
+        deltas: [{ key: 'jump_target_ids', before: b.jump_target_ids, after: a.jump_target_ids }],
+        owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+        flags: ['internal-api'],
+      });
+    }
+
+    if (canonicalString(b.team_member_ids) !== canonicalString(a.team_member_ids)) {
+      record({
+        entity: 'phase_team_memberships',
+        op: 'update',
+        key: `team:${ownerKey}`,
+        label: `${phaseLabel} → team`,
+        before: { phase_id: b['id'], team_member_ids: b.team_member_ids },
+        after: { phase_id: a['id'], team_member_ids: a.team_member_ids },
+        deltas: [{ key: 'team_member_ids', before: b.team_member_ids, after: a.team_member_ids }],
+        owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+      });
+    }
+
+    /**
+     * A field authored inside a phase file inherits that phase's id.
+     *
+     * Fields live nested under their phase precisely so nobody has to keep a
+     * `phase_id` in two places, so a hand-authored new field arrives with
+     * `"phase_id": null`. Filling it from the owner here is not inventing data —
+     * `pack` does exactly the same thing on the way back to the payload — and
+     * skipping it sent `createPhaseField` an empty id, which the API answered
+     * with "Phase not found with id: ".
+     *
+     * A field under a phase that is itself new keeps its null: that id does not
+     * exist yet, and the compiler substitutes a placeholder for it instead.
+     */
+    const own = (f: Row): Row => (f['phase_id'] == null && a['id'] != null ? { ...f, phase_id: a['id'] } : f);
+
+    // fields inside a matched phase
+    const fieldMatcher: Matcher<Row> = {
+      primary: (f) => (f['uuid'] ? `uuid:${f['uuid']}` : f['id'] ? `id:${f['id']}` : null),
+      natural: (f) => naturalKeyOf('fields', f, { phaseName: phaseLabel }),
+    };
+    const fm = matchRows(b.fields, a.fields, fieldMatcher, mode);
+
+    for (const f of fm.added) {
+      if (rowAbsenceIsUnknown('fields', 'create', label(f, 'field'))) continue;
+      pushField({
+        entity: 'fields',
+        op: 'create',
+        key: fieldMatcher.primary(f) ?? `new:${fieldMatcher.natural(f)}`,
+        label: `${phaseLabel} / ${label(f, 'field')}`,
+        after: own(f),
+        owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+      });
+    }
+    for (const f of fm.removed) {
+      if (rowAbsenceIsUnknown('fields', 'delete', label(f, 'field'))) continue;
+      pushField({
+        entity: 'fields',
+        op: 'delete',
+        key: fieldMatcher.primary(f) ?? `gone:${fieldMatcher.natural(f)}`,
+        label: `${phaseLabel} / ${label(f, 'field')}`,
+        before: f,
+        owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+        flags: ['destructive'],
+      });
+    }
+    for (const [fb, fa] of fm.pairs) {
+      const fid = num(fb['id']);
+      const faid = num(fa['id']);
+      if (fid !== null && faid !== null) {
+        idMap.fields = { ...(idMap.fields ?? {}), [String(fid)]: faid };
+      }
+
+      /**
+       * `phase_id` on a field is a consequence of which phase file it sits in, not
+       * a value anyone edits — and a genuine cross-phase move is detected by the
+       * reconciliation pass below, which states the delta explicitly. Comparing it
+       * here only ever reports noise, such as the `null` an author writes for a
+       * field inside a phase that does not exist yet.
+       */
+      const archivedBefore = Boolean(fb['archived_at']);
+      const archivedAfter = Boolean(fa['archived_at']);
+      /**
+       * On a database, `index` is excluded from verification but not from the diff.
+       *
+       * A database's column order is written by `setTableFieldOrder`, which
+       * **renumbers**: asking for slugs in a given order and reading back gives
+       * 1, 2, 3, 4 where the workspace wrote 0, 1, 2, 3. The order is right and
+       * every absolute index is different, so comparing the column turns a
+       * correct reorder into a verification failure — and a failed verification
+       * blocks the file sync, leaving the workspace permanently dirty for a
+       * difference nobody can fix. The order write asserts its own effect from
+       * the `table_fields` it returns, which is the stronger check anyway.
+       */
+      const fieldIgnore =
+        intentOnly && before.meta.repoKind === 'table'
+          ? new Set(['archived_at', 'phase_id', 'index'])
+          : new Set(['archived_at', 'phase_id']);
+      const deltas = deltasOf(fb, fa, fieldIgnore, partialSides('fields'), intentOnly);
+
+      if (archivedBefore !== archivedAfter) {
+        pushField({
+          entity: 'fields',
+          op: archivedAfter ? 'archive' : 'unarchive',
+          key: fieldMatcher.primary(fa) ?? '',
+          label: `${phaseLabel} / ${label(fa, 'field')}`,
+          before: fb,
+          after: fa,
+          deltas: [{ key: 'archived_at', before: fb['archived_at'] ?? null, after: fa['archived_at'] ?? null }],
+          owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+        });
+      }
+
+      if (!deltas.length) continue;
+
+      const flags: string[] = [];
+      if (deltas.some((d) => d.key === 'type_id')) flags.push('field-type-change');
+      if (deltas.some((d) => d.key === 'phase_id')) flags.push('field-phase-move');
+      if (deltas.length === 1 && deltas[0]!.key === 'index') flags.push('field-reorder');
+
+      pushField({
+        entity: 'fields',
+        op: 'update',
+        key: fieldMatcher.primary(fa) ?? '',
+        label: `${phaseLabel} / ${label(fa, 'field')}`,
+        before: fb,
+        after: fa,
+        deltas,
+        owner: { entity: 'phases', key: ownerKey, label: phaseLabel },
+        flags,
+      });
+    }
+  }
+
+  /**
+   * Reconcile field moves. A delete and a create sharing an exact identity —
+   * uuid, or numeric id — is one field that changed phase, never two fields.
+   * Matching only on exact identity is deliberate: pairing on label would turn
+   * "delete Notes from A, add Notes to B" into a move when it may genuinely be
+   * two different fields.
+   */
+  const identityOf = (c: Change): string | null => {
+    const row = c.after ?? c.before;
+    if (!row) return null;
+    if (row['uuid']) return `uuid:${row['uuid']}`;
+    if (row['id'] !== null && row['id'] !== undefined) return `id:${row['id']}`;
+    return null;
+  };
+
+  const createdById = new Map<string, Change>();
+  for (const c of fieldChanges) {
+    if (c.op !== 'create') continue;
+    const id = identityOf(c);
+    if (id) createdById.set(id, c);
+  }
+
+  const consumed = new Set<Change>();
+  for (const del of fieldChanges) {
+    if (del.op !== 'delete') continue;
+    const id = identityOf(del);
+    if (!id) continue;
+    const created = createdById.get(id);
+    if (!created || consumed.has(created)) continue;
+
+    consumed.add(created);
+    consumed.add(del);
+
+    const before = del.before ?? {};
+    const after = created.after ?? {};
+    const deltas = deltasOf(before, after, undefined, partialSides('fields'), intentOnly);
+    if (!deltas.some((d) => d.key === 'phase_id')) {
+      deltas.push({ key: 'phase_id', before: before['phase_id'] ?? null, after: after['phase_id'] ?? null });
+    }
+    record({
+      entity: 'fields',
+      op: 'update',
+      key: id,
+      label: `${del.owner?.label ?? '?'} -> ${created.owner?.label ?? '?'} / ${label(after, 'field')}`,
+      before,
+      after,
+      deltas,
+      owner: created.owner,
+      flags: ['field-phase-move'],
+    });
+  }
+
+  for (const c of fieldChanges) if (!consumed.has(c)) changes.push(c);
+
+  // ── automations (condition, field_maps, schemas fold in) ───────────────────
+  if (!coverageBlocked('automations')) {
+    const autoMatcher: Matcher<AutomationNode> = {
+      primary: (a) => (a['uuid'] ? `uuid:${a['uuid']}` : a['id'] ? `id:${a['id']}` : null),
+      natural: (a) => naturalKeyOf('automations', a),
+    };
+    /**
+     * A behavior — an automation whose `action_id` is `ai_behavior` — is
+     * excluded here, not diffed as an automation at all. `diff/agents.ts` diffs
+     * it instead, because sending one is not `createAutomation`/
+     * `updateAutomation`: this pipe's catalogue does not offer `ai_behavior` to
+     * either (confirmed live, refused), and the real write path —
+     * `createAiAgent`/`updateAiAgent` — replaces an agent's entire behaviors
+     * list in one call, which this per-automation diff has no way to express.
+     * Diffing it here too would propose a doomed `createAutomation`/
+     * `updateAutomation`/`deleteAutomation` step alongside the real one.
+     *
+     * Matched on `action_id`, not the `_agent_dir` tag: the tag is derived by
+     * `readTree` from where a file sits on disk, so it is only ever present on
+     * the *edited* side. The baseline side is `unpack()` of a stored envelope —
+     * no filesystem, no tag — so filtering on `_agent_dir` alone was one-sided:
+     * every existing behavior read as deleted on the very first diff after a
+     * fresh pull, because `before` still had it and `after` had been filtered.
+     */
+    const withoutBehaviors = (rows: AutomationNode[]) => rows.filter((a) => a['action_id'] !== 'ai_behavior');
+    const am = matchRows(withoutBehaviors(before.automations), withoutBehaviors(after.automations), autoMatcher, mode);
+
+    for (const a of am.added) {
+      if (rowAbsenceIsUnknown('automations', 'create', label(a, 'automation'))) continue;
+      record({
+        entity: 'automations',
+        op: 'create',
+        key: autoMatcher.primary(a) ?? `new:${autoMatcher.natural(a)}`,
+        label: label(a, 'automation'),
+        after: a,
+      });
+    }
+    for (const a of am.removed) {
+      if (rowAbsenceIsUnknown('automations', 'delete', label(a, 'automation'))) continue;
+      record({
+        entity: 'automations',
+        op: 'delete',
+        key: autoMatcher.primary(a) ?? `gone:${autoMatcher.natural(a)}`,
+        label: label(a, 'automation'),
+        before: a,
+        flags: ['destructive'],
+      });
+    }
+    for (const [b, a] of am.pairs) {
+      const deltas = deltasOf(b, a, new Set(['condition', 'field_maps', 'distribute_assignments', 'response_schemas']), partialSides('automations'), intentOnly);
+      const nested: FieldDelta[] = [];
+      const condPartial = partialSides('conditions');
+      const autoCond = statedCondition(b, a, intentOnly);
+      if (
+        nestedObjectDiffers(conditionSummary(autoCond), conditionSummary(a), condPartial, intentOnly) &&
+        nestedObjectDiffers(autoCond.condition, a.condition, condPartial, intentOnly)
+      ) {
+        nested.push({ key: 'condition', before: b.condition ?? null, after: a.condition ?? null });
+      }
+      if (nestedDiffers(b.field_maps, a.field_maps, partialSides('field_maps'), intentOnly)) {
+        nested.push({ key: 'field_maps', before: b.field_maps, after: a.field_maps });
+      }
+      if (nestedDiffers(b.distribute_assignments, a.distribute_assignments, partialSides('distribute_assignments'), intentOnly)) {
+        nested.push({ key: 'distribute_assignments', before: b.distribute_assignments, after: a.distribute_assignments });
+      }
+      if (nestedDiffers(b.response_schemas, a.response_schemas, partialSides('response_schemas'), intentOnly)) {
+        nested.push({ key: 'response_schemas', before: b.response_schemas, after: a.response_schemas });
+      }
+      const all = [...deltas, ...nested];
+      if (!all.length) continue;
+      record({
+        entity: 'automations',
+        op: 'update',
+        key: autoMatcher.primary(a) ?? '',
+        label: label(a, 'automation'),
+        before: b,
+        after: a,
+        deltas: all,
+        flags: nested.length ? ['nested-change'] : [],
+      });
+    }
+  }
+
+  // ── field conditions (actions + condition fold in) ─────────────────────────
+  if (!coverageBlocked('field_conditions')) {
+    /**
+     * Verification matches a condition by name alone.
+     *
+     * A field condition has no uuid, so its natural key is (phase_id, name) — and
+     * phase_id is exactly what a mis-targeted create gets wrong, which means the
+     * rows never match and the result reads as an unrelated create plus delete
+     * rather than "this landed on the wrong phase". Measured: createFieldCondition
+     * accepted phaseId 344123715 and put the condition on the start form, and
+     * this diff called it two changes instead of one wrong one.
+     */
+    const fcMatcher: Matcher<FieldConditionNode> = {
+      primary: (f) => (f['id'] ? `id:${f['id']}` : null),
+      natural: (f) => (intentOnly ? String(f['name'] ?? '') : naturalKeyOf('field_conditions', f)),
+    };
+    const fm = matchRows(before.field_conditions, after.field_conditions, fcMatcher, mode);
+
+    for (const f of fm.added) {
+      if (rowAbsenceIsUnknown('field_conditions', 'create', label(f, 'condition'))) continue;
+      record({ entity: 'field_conditions', op: 'create', key: fcMatcher.primary(f) ?? `new:${fcMatcher.natural(f)}`, label: label(f, 'condition'), after: f });
+    }
+    for (const f of fm.removed) {
+      if (rowAbsenceIsUnknown('field_conditions', 'delete', label(f, 'condition'))) continue;
+      record({ entity: 'field_conditions', op: 'delete', key: fcMatcher.primary(f) ?? `gone:${fcMatcher.natural(f)}`, label: label(f, 'condition'), before: f, flags: ['destructive'] });
+    }
+    for (const [b, a] of fm.pairs) {
+      /**
+       * `index` is excluded from verification, not from the diff.
+       *
+       * A condition's position is written by `setFieldConditionOrder`, a
+       * separate set-replacing step that reports its own success or failure. The
+       * server assigns an index on create, so a newly created condition almost
+       * never lands on the number the workspace wrote — and failing
+       * verification on that one column blocked the file sync entirely, leaving
+       * the workspace permanently dirty for a difference nobody could fix.
+       */
+      const fcIgnore = intentOnly ? ['actions', 'condition', 'index'] : ['actions', 'condition'];
+      const deltas = deltasOf(b, a, new Set(fcIgnore), partialSides('field_conditions'), intentOnly);
+      const nested: FieldDelta[] = [];
+      if (nestedDiffers(b.actions, a.actions, partialSides('field_condition_actions'), intentOnly)) {
+        nested.push({ key: 'actions', before: b.actions, after: a.actions });
+      }
+      const fcCond = statedCondition(b, a, intentOnly);
+      if (nestedObjectDiffers(conditionSummary(fcCond), conditionSummary(a), partialSides('conditions'), intentOnly)) {
+        nested.push({ key: 'condition', before: b.condition ?? null, after: a.condition ?? null });
+      }
+      const all = [...deltas, ...nested];
+      if (!all.length) continue;
+      record({ entity: 'field_conditions', op: 'update', key: fcMatcher.primary(a) ?? '', label: label(a, 'condition'), before: b, after: a, deltas: all });
+    }
+  }
+
+  // ── flat arrays ────────────────────────────────────────────────────────────
+  const flat: Array<{ entity: EntityName; before: Row[]; after: Row[] }> = [
+    { entity: 'labels', before: before.labels, after: after.labels },
+    { entity: 'webhooks', before: before.webhooks, after: after.webhooks },
+    { entity: 'pipe_relations', before: before.pipe_relations, after: after.pipe_relations },
+  ];
+  for (const group of flat) {
+    if (coverageBlocked(group.entity)) continue;
+    const spec = ENTITIES[group.entity];
+    const matcher: Matcher<Row> = {
+      primary: (r) => (spec.identity === 'uuid' && r['uuid'] ? `uuid:${r['uuid']}` : r['id'] ? `id:${r['id']}` : null),
+      natural: (r) => naturalKeyOf(group.entity, r),
+    };
+    const m = matchRows(group.before, group.after, matcher, mode);
+    for (const r of m.added) if (!rowAbsenceIsUnknown(group.entity, 'create', label(r, group.entity))) record({ entity: group.entity, op: 'create', key: matcher.primary(r) ?? `new:${matcher.natural(r)}`, label: label(r, group.entity), after: r });
+    for (const r of m.removed) if (!rowAbsenceIsUnknown(group.entity, 'delete', label(r, group.entity))) record({ entity: group.entity, op: 'delete', key: matcher.primary(r) ?? `gone:${matcher.natural(r)}`, label: label(r, group.entity), before: r, flags: ['destructive'] });
+    for (const [b, a] of m.pairs) {
+      const deltas = deltasOf(b, a, UNREADABLE_IN_PAYLOAD[group.entity], partialSides(group.entity), intentOnly);
+      if (deltas.length) record({ entity: group.entity, op: 'update', key: matcher.primary(a) ?? '', label: label(a, group.entity), before: b, after: a, deltas });
+    }
+  }
+
+  // ── singletons ─────────────────────────────────────────────────────────────
+  const singleton = (entity: EntityName, b: Row | null, a: Row | null, file: string) => {
+    if (coverageBlocked(entity)) return;
+    if (!b && !a) return;
+    if (b && !a) {
+      record({ entity, op: 'delete', key: entity, label: entity, before: b, file, flags: ['destructive'] });
+      return;
+    }
+    if (!b && a) {
+      record({ entity, op: 'create', key: entity, label: entity, after: a, file });
+      return;
+    }
+    const deltas = deltasOf(b as Row, a as Row, undefined, partialSides(entity), intentOnly);
+    if (deltas.length) record({ entity, op: 'update', key: entity, label: entity, before: b, after: a, deltas, file });
+  };
+  singleton('public_forms', before.public_form, after.public_form, 'public-form.json');
+  singleton('repo_preferences', before.preferences, after.preferences, 'preferences.json');
+
+  // ── read-only groups: any change here is a mistake, reported as such ───────
+  const ro: Array<[EntityName, Row[], Row[], string]> = [
+    ['email_templates', before.readonly.email_templates, after.readonly.email_templates, '_readonly/email-templates.json'],
+    ['email_inboxes', before.readonly.email_inboxes, after.readonly.email_inboxes, '_readonly/email-inboxes.json'],
+    ['visibilities', before.readonly.visibilities, after.readonly.visibilities, '_readonly/visibilities.json'],
+    ['field_maps', before.readonly.field_maps, after.readonly.field_maps, '_readonly/field-maps.json'],
+  ];
+  for (const [entity, b, a, file] of ro) {
+    if (sameSet(b, a) && b.length === a.length) continue;
+    /**
+     * A read path that cannot see a read-only group is not an edit to it. The
+     * reconstruction has no query for visibilities, so without this every
+     * reconstructed tree "edited" them to empty.
+     */
+    if (coverageBlocked(entity) || nestedDiffers(b, a, partialSides(entity)) === false) continue;
+    record({
+      entity,
+      op: 'update',
+      key: entity,
+      label: `${entity} (read-only)`,
+      before: { rows: b } as Row,
+      after: { rows: a } as Row,
+      deltas: [{ key: 'rows', before: b, after: a }],
+      file,
+      flags: ['readonly-edit'],
+    });
+  }
+
+  for (const s of suppressed) {
+    skipped.push({
+      entity: s.entity,
+      reason:
+        `"${s.label}" would read as a ${s.op}, but that side's coverage is partial — ` +
+        `absence there is unseen, not gone. Re-read from a snapshot to decide.`,
+    });
+  }
+
+  return {
+    mode,
+    from: { repoId: Number(before.repo['id']), name: String(before.repo['name'] ?? ''), source: before.meta.source },
+    to: { repoId: Number(after.repo['id']), name: String(after.repo['name'] ?? ''), source: after.meta.source },
+    changes,
+    skipped,
+    idMap,
+  };
+};
+
+export const isEmpty = (cs: ChangeSet) => cs.changes.length === 0;
+
+export const countByOp = (cs: ChangeSet): Record<ChangeOp, number> => {
+  const out = { create: 0, update: 0, delete: 0, reorder: 0, archive: 0, unarchive: 0 } as Record<ChangeOp, number>;
+  for (const c of cs.changes) out[c.op]++;
+  return out;
+};