@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/diff/diff.js

@@ -0,0 +1,983 @@
+import { canonicalString } from "../util/json.js";
+import { VOLATILE_KEYS } from "../model/volatile.js";
+import { ENTITIES } from "../model/payload.js";
+// ── 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) => 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) => v === null || v === undefined || v === '';
+const comparable = (row, extraIgnore = new Set()) => {
+    const out = {};
+    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;
+};
+const NO_PARTIAL = { 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 = {
+    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, y) => {
+    const norm = (v) => 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, after, extraIgnore, partial = NO_PARTIAL, intentOnly = false) => {
+    const a = comparable(before, extraIgnore);
+    const b = comparable(after, extraIgnore);
+    const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+    const out = [];
+    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) => rows.map((r) => canonicalString(comparable(r))).sort();
+const sameSet = (a, b) => 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) => 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) => {
+    if (Array.isArray(v))
+        return v.map(nestedComparable);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            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, intent) => {
+    if (Array.isArray(live)) {
+        const peers = Array.isArray(intent) ? intent : [];
+        const merged = peers.reduce((acc, e) => (e && typeof e === 'object' && !Array.isArray(e) ? { ...acc, ...e } : 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 = {};
+        for (const [k, val] of Object.entries(live)) {
+            if (!(k in intent))
+                continue;
+            out[k] = asStated(val, intent[k]);
+        }
+        return out;
+    }
+    return live;
+};
+const nestedSame = (a, b, intentOnly) => {
+    const left = intentOnly ? asStated(a, b) : a;
+    return canonicalString(nestedComparable(left)) === canonicalString(nestedComparable(b));
+};
+const nestedDiffers = (a, b, partial, intentOnly = false) => {
+    if (sameSet(a, b))
+        return false;
+    const norm = (rows) => canonicalString(nestedComparable(rows).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, b, partial, intentOnly = false) => {
+    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;
+};
+const naturalKeyOf = (entity, row, ctx = {}) => {
+    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 = (before, after, m, mode) => {
+    const pairs = [];
+    const usedAfter = new Set();
+    const remainingBefore = [];
+    const afterByPrimary = new Map();
+    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();
+    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 = [];
+    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) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+const label = (row, fallback) => 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, a, intentOnly) => ({
+    condition: (intentOnly
+        ? asStated(b.condition ?? null, a.condition ?? null)
+        : (b.condition ?? null)),
+});
+const conditionSummary = (node) => {
+    const c = node.condition;
+    if (!c)
+        return {};
+    return { expressions_structure: c['expressions_structure'] ?? [], expressions: setOf(c['expressions'] ?? []) };
+};
+export const diffTrees = (before, after, opts = {}) => {
+    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, y) => {
+        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 = [];
+    const skipped = [];
+    const 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(opts.skipEntities ?? []);
+    /** Which sides read this group only partially. See deltasOf. */
+    const partialSides = (entity) => ({
+        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 = [];
+    const rowAbsenceIsUnknown = (entity, op, label) => {
+        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 = {
+        before: before.meta.repo_columns === 'partial',
+        after: after.meta.repo_columns === 'partial',
+    };
+    const coverageBlocked = (entity) => {
+        if (skipSet.has(entity))
+            return true;
+        const a = before.meta.coverage?.[entity] ?? 'unknown';
+        const b = 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) => {
+        changes.push({ deltas: [], flags: [], ...c });
+    };
+    // ── 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 = {
+        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 = {};
+    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 = [];
+    const pushField = (c) => {
+        fieldChanges.push({ deltas: [], flags: [], ...c });
+    };
+    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) => (f['phase_id'] == null && a['id'] != null ? { ...f, phase_id: a['id'] } : f);
+        // fields inside a matched phase
+        const fieldMatcher = {
+            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 = [];
+            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) => {
+        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();
+    for (const c of fieldChanges) {
+        if (c.op !== 'create')
+            continue;
+        const id = identityOf(c);
+        if (id)
+            createdById.set(id, c);
+    }
+    const consumed = new Set();
+    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 = {
+            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) => 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 = [];
+            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 = {
+            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 = [];
+            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 = [
+        { 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 = {
+            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, b, a, file) => {
+        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, a, 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 = [
+        ['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 },
+            after: { rows: a },
+            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) => cs.changes.length === 0;
+export const countByOp = (cs) => {
+    const out = { create: 0, update: 0, delete: 0, reorder: 0, archive: 0, unarchive: 0 };
+    for (const c of cs.changes)
+        out[c.op]++;
+    return out;
+};