@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/apply/compile.js

@@ -0,0 +1,722 @@
+import { randomUUID } from 'node:crypto';
+import { ENDPOINTS } from "../config.js";
+import { debug } from "../util/log.js";
+import { checkAutomationParams } from "../pipefy/automations.js";
+import { support } from "./registry.js";
+import { placeholderFor } from "./idmap.js";
+import * as M from "./mutations.js";
+const opFor = (c) => {
+    if (c.entity === 'fields') {
+        if (c.flags.includes('field-type-change'))
+            return 'change_type';
+        if (c.flags.includes('field-phase-move'))
+            return 'move_phase';
+        if (c.op === 'archive' || c.op === 'unarchive')
+            return 'archive';
+        if (c.flags.includes('field-reorder'))
+            return 'reorder';
+    }
+    if (c.op === 'reorder')
+        return 'reorder';
+    if (c.op === 'archive' || c.op === 'unarchive')
+        return 'archive';
+    return c.op;
+};
+const classify = (c, kind = 'pipe') => {
+    const op = opFor(c);
+    // A path-based refusal, checked before the registry: an edit under _readonly/
+    // is rejected on the basis of the path alone (PLAN.md §4).
+    if (c.flags.includes('readonly-edit')) {
+        return {
+            changeKey: c.key,
+            entity: c.entity,
+            op,
+            status: 'UNSUPPORTED',
+            reason: `${c.entity} lives under _readonly/ — it has no public write path and must not be edited`,
+            label: c.label,
+        };
+    }
+    if (c.flags.includes('start-form') && c.op === 'delete') {
+        return {
+            changeKey: c.key,
+            entity: c.entity,
+            op,
+            status: 'UNSUPPORTED',
+            reason: 'the start form is a real phase at index 0; deleting it would destroy the pipe entrance',
+            label: c.label,
+        };
+    }
+    /**
+     * Same flag, one more field: the start form's name is widely referenced by
+     * name rather than by id or index — the public form, automations, a
+     * client's own documentation — none of which this tool can see to check
+     * for breakage. Renaming it is not destructive the way deleting it is, so
+     * it is refused rather than reported UNSUPPORTED for a missing write path
+     * (`updatePhase` happily accepts `name`); every *other* field on the start
+     * form still updates normally.
+     */
+    if (c.flags.includes('start-form') && c.op === 'update' && c.deltas.some((d) => d.key === 'name')) {
+        return {
+            changeKey: c.key,
+            entity: c.entity,
+            op,
+            status: 'UNSUPPORTED',
+            reason: 'the start form’s name is refused on purpose — it is widely referenced by name (the public form, automations, a client’s own docs) in places this tool cannot check for breakage',
+            label: c.label,
+        };
+    }
+    const s = support(c.entity, op, kind);
+    /**
+     * Column-level refusal. A path can exist for the entity and still have no
+     * input for the column being changed, and a mutation that succeeds while
+     * ignoring the change is the one outcome this tool must never produce.
+     */
+    if (s.settableColumns && c.deltas.length) {
+        const settable = new Set(s.settableColumns);
+        const unsettable = c.deltas.map((d) => d.key).filter((k) => !settable.has(k));
+        if (unsettable.length) {
+            return {
+                changeKey: c.key,
+                entity: c.entity,
+                op,
+                status: 'UNSUPPORTED',
+                reason: `${unsettable.join(', ')} ${unsettable.length === 1 ? 'has' : 'have'} no input on this endpoint. ` +
+                    `${s.via ?? 'the write path'} accepts only: ${s.settableColumns.join(', ')}`,
+                ask: s.ask,
+                label: c.label,
+            };
+        }
+    }
+    return { changeKey: c.key, entity: c.entity, op, status: s.status, via: s.via, reason: s.reason, ask: s.ask, label: c.label };
+};
+export const compile = async (cs, ctx, options) => {
+    const repoKind = ctx.repoKind ?? 'pipe';
+    const classifications = cs.changes.map((c) => classify(c, repoKind));
+    const blocked = classifications.filter((c) => c.status === 'UNSUPPORTED');
+    const warnings = [];
+    const steps = [];
+    const emit = (partial) => {
+        steps.push({ id: `s${String(steps.length + 1).padStart(3, '0')}`, index: steps.length, status: 'pending', ...partial });
+    };
+    const supported = (key) => classifications.find((c) => c.changeKey === key)?.status !== 'UNSUPPORTED';
+    const byEntityOp = (entity, ops) => cs.changes.filter((c) => c.entity === entity && ops.includes(c.op) && supported(c.key));
+    const missing = (mutation) => Boolean(ctx.capabilities && ctx.capabilities.mutations[mutation] === false);
+    const offline = ctx.client === null;
+    if (offline)
+        warnings.push('planned offline: request shapes were not checked against the schema, so every step is marked unverified. pipe apply re-compiles with a connection.');
+    const livePhaseIdSet = new Set((ctx.livePhaseIds ?? []).map(Number));
+    const placeholdersIn = (value) => {
+        const found = new Set();
+        const walk = (v) => {
+            if (typeof v === 'string') {
+                for (const m of v.matchAll(/%\{(_new:[^}]+)\}/g))
+                    found.add(m[1]);
+                if (v.startsWith('_new:'))
+                    found.add(v);
+                return;
+            }
+            if (Array.isArray(v))
+                return void v.forEach(walk);
+            if (v && typeof v === 'object')
+                Object.values(v).forEach(walk);
+        };
+        walk(value);
+        return [...found];
+    };
+    const graphqlStep = async (c, op, request, extra = {}) => {
+        const req = await request;
+        if (req.mutation && missing(req.mutation)) {
+            warnings.push(`${req.mutation} is not present on this endpoint — "${c.label}" cannot be applied`);
+            return;
+        }
+        if (req.missingRequired?.length) {
+            warnings.push(`${req.mutation} requires ${req.missingRequired.join(', ')}, which "${c.label}" does not supply — ` +
+                'no step was emitted, because the request would be rejected');
+            return;
+        }
+        emit({
+            changeKey: c.key,
+            entity: c.entity,
+            op,
+            kind: 'graphql',
+            description: `${req.mutation ?? 'graphql'} — ${c.label}`,
+            request: req,
+            /**
+             * Derived rather than empty. A step whose request carries a placeholder
+             * depends on the step that mints it, and `setFieldConditionOrder` names a
+             * condition created in the same plan.
+             */
+            needs: placeholdersIn(req.variables),
+            ...(offline ? { unverified: true } : {}),
+            ...extra,
+        });
+    };
+    // ── 1. repo root ───────────────────────────────────────────────────────────
+    for (const c of byEntityOp('repo', ['update'])) {
+        /**
+         * A database's root row goes through `updateTable`, a different mutation with
+         * a different settable set. Routed through `updatePipe` instead, every
+         * table-only column would be dropped by the argument filter and the mutation
+         * would report success having changed nothing.
+         */
+        await graphqlStep(c, 'update', repoKind === 'table'
+            ? M.updateTable(ctx.client, c.after ?? {}, ctx.fieldSlugById ?? {})
+            : M.updatePipe(ctx.client, c.after ?? {}, ctx.fieldUuidById ?? {}));
+    }
+    // ── 2. phases: create, then update ─────────────────────────────────────────
+    for (const c of byEntityOp('phases', ['create'])) {
+        const req = await M.createPhase(ctx.client, ctx.repoId, c.after ?? {});
+        const placeholder = placeholderFor('phases', c.key);
+        emit({
+            changeKey: c.key,
+            entity: 'phases',
+            op: 'create',
+            kind: 'graphql',
+            unverified: offline,
+            description: `createPhase — ${c.label}`,
+            request: req,
+            needs: [],
+            produces: {
+                placeholder,
+                path: ['createPhase', 'phase', 'id'],
+                aliases: [`_new:${String(c.after?.['uuid'] ?? '')}`, `_new:${c.label}`].filter((a) => a !== '_new:'),
+            },
+        });
+    }
+    for (const c of byEntityOp('phases', ['update'])) {
+        await graphqlStep(c, 'update', M.updatePhase(ctx.client, c.after ?? {}));
+    }
+    // ── 3. fields: create (start form first), then update / reorder / archive ──
+    const fieldCreates = byEntityOp('fields', ['create']);
+    // The start form is index 0, and the recipes handle it before phase fields
+    // (steps 30 then 45) because it is where connector and title fields live.
+    const startFormFirst = [...fieldCreates].sort((a, b) => {
+        const ai = Number((a.owner?.label ?? '').toLowerCase().includes('start form') ? 0 : 1);
+        const bi = Number((b.owner?.label ?? '').toLowerCase().includes('start form') ? 0 : 1);
+        return ai - bi;
+    });
+    for (const c of startFormFirst) {
+        const field = c.after ?? {};
+        // The phase may itself be new, in which case its id arrives as a placeholder.
+        const phaseChange = cs.changes.find((x) => x.entity === 'phases' && x.op === 'create' && x.key === c.owner?.key);
+        const phaseId = phaseChange ? placeholderFor('phases', phaseChange.key) : String(field['phase_id'] ?? '');
+        /**
+         * No phase, no step. `createPhaseField` with an empty `phase_id` is answered
+         * with "Phase not found with id: " — an error that names neither the field
+         * nor the phase, in the middle of an apply that has already created things.
+         * Refusing here says which field, before anything is sent.
+         */
+        if (!phaseId) {
+            warnings.push(`${c.label} has no phase to be created in: its row carries no phase_id and no phase in this plan owns it. ` +
+                'No step was emitted.');
+            continue;
+        }
+        /**
+         * A database's column is created by `createTableField`, which takes the
+         * database rather than a phase — a database has one form and no other place
+         * for a column to live.
+         */
+        const isTable = repoKind === 'table';
+        const req = isTable
+            ? await M.createTableField(ctx.client, ctx.repoId, field)
+            : await M.createPhaseField(ctx.client, phaseId, field);
+        const placeholder = placeholderFor('fields', c.key);
+        emit({
+            changeKey: c.key,
+            entity: 'fields',
+            op: 'create',
+            kind: 'graphql',
+            unverified: offline,
+            description: `${isTable ? 'createTableField' : 'createPhaseField'} — ${c.label}`,
+            request: req,
+            needs: phaseChange && !isTable ? [placeholderFor('phases', phaseChange.key)] : [],
+            produces: {
+                placeholder,
+                path: isTable
+                    ? ['createTableField', 'table_field', 'internal_id']
+                    : ['createPhaseField', 'phase_field', 'internal_id'],
+                aliases: [`_new:${String(field['uuid'] ?? '')}`, `_new:${String(field['label'] ?? '')}`].filter((a) => a !== '_new:'),
+            },
+        });
+    }
+    for (const c of byEntityOp('fields', ['update'])) {
+        /**
+         * A database's column order is not a column.
+         *
+         * `UpdateTableFieldInput` has no `index`, so routing a reorder through
+         * `updateTableField` would send a request with nothing to do and get a
+         * success back — the one outcome this tool must never produce. The order is a
+         * separate set-replacing call, emitted once below, so a reorder-only change
+         * contributes no per-field step at all.
+         */
+        if (repoKind === 'table' && c.flags.includes('field-reorder') && !c.deltas.some((d) => d.key !== 'index')) {
+            continue;
+        }
+        /**
+         * `updateTableField` addresses a column by its slug and needs the database id
+         * alongside it — measured, and the opposite of `updatePhaseField`, whose `id`
+         * is the numeric internal id.
+         */
+        await graphqlStep(c, c.flags.includes('field-reorder') ? 'reorder' : 'update', repoKind === 'table'
+            ? M.updateTableField(ctx.client, ctx.repoId, c.after ?? {})
+            : M.updatePhaseField(ctx.client, c.after ?? {}));
+    }
+    /**
+     * The database's column order, as one set-replacing write, placed after the
+     * creates so a new column can be positioned in the same plan.
+     *
+     * Emitted only when the order actually differs from the order the database will
+     * already have: the baseline order, minus anything this plan deletes, plus this
+     * plan's creates in the order they are applied — since `createTableField` has
+     * no `index` and a new column lands at the end. So appending a column, the
+     * ordinary case, needs no reorder at all.
+     *
+     * A no-op `setTableFieldOrder` is accepted by the API rather than answered with
+     * "Something went wrong" the way `setFieldConditionOrder` is, so this guard is
+     * an optimisation rather than a correctness requirement. It is still worth
+     * having: a step that does nothing is a step someone has to read.
+     */
+    if (repoKind === 'table' && ctx.tableFieldOrder?.length) {
+        const stated = ctx.tableFieldOrder.map((f) => f['slug'] ? String(f['slug']) : placeholderFor('fields', `new:${String(f['uuid'] ?? f['label'] ?? '')}`));
+        const deleted = new Set(cs.changes
+            .filter((c) => c.entity === 'fields' && c.op === 'delete')
+            .map((c) => String(c.before?.['slug'] ?? '')));
+        const appended = cs.changes
+            .filter((c) => c.entity === 'fields' && c.op === 'create' && supported(c.key))
+            .map((c) => placeholderFor('fields', `new:${String(c.after?.['uuid'] ?? c.after?.['label'] ?? '')}`));
+        const natural = [...(ctx.baselineTableFieldOrder ?? []).filter((s) => !deleted.has(s)), ...appended];
+        const unchanged = natural.length === stated.length && stated.every((s, i) => s === natural[i]);
+        if (!unchanged) {
+            const anchor = cs.changes.find((c) => c.entity === 'fields');
+            if (anchor) {
+                await graphqlStep({ ...anchor, label: `column order in ${ctx.repoId}` }, 'reorder', M.setTableFieldOrder(ctx.client, ctx.repoId, ctx.tableFieldOrder));
+            }
+        }
+    }
+    for (const c of byEntityOp('fields', ['archive', 'unarchive'])) {
+        await graphqlStep(c, 'archive', M.archiveField(ctx.client, c.after ?? {}, c.op === 'archive'));
+    }
+    // ── 4. labels, webhooks, relations ─────────────────────────────────────────
+    /**
+     * `produces` on all three creates below, even though nothing in the same
+     * plan ever references a label/webhook/relation by placeholder — that was
+     * the only reason it existed before. `apply.ts`'s post-apply id adoption
+     * (adopt.ts) reuses the same IdMap for a second job: writing the real id
+     * into the file the entity was authored in, with no read-back. Without a
+     * `produces` entry the create still succeeds, but the id it returned is
+     * never captured anywhere, and the file keeps reading `"id": null, "_new":
+     * true"` until the next live read adopts it some other way.
+     */
+    for (const c of byEntityOp('labels', ['create'])) {
+        await graphqlStep(c, 'create', M.createLabel(ctx.client, ctx.repoId, c.after ?? {}, repoKind), {
+            produces: { placeholder: placeholderFor('labels', c.key), path: ['createLabel', 'label', 'id'] },
+        });
+    }
+    for (const c of byEntityOp('labels', ['update'])) {
+        await graphqlStep(c, 'update', M.updateLabel(ctx.client, c.after ?? {}));
+    }
+    for (const c of byEntityOp('webhooks', ['create'])) {
+        await graphqlStep(c, 'create', M.createWebhook(ctx.client, ctx.repoId, c.after ?? {}), {
+            produces: { placeholder: placeholderFor('webhooks', c.key), path: ['createWebhook', 'webhook', 'id'] },
+        });
+    }
+    for (const c of byEntityOp('webhooks', ['update'])) {
+        await graphqlStep(c, 'update', M.updateWebhook(ctx.client, c.after ?? {}));
+    }
+    for (const c of byEntityOp('pipe_relations', ['create'])) {
+        await graphqlStep(c, 'create', M.createPipeRelation(ctx.client, c.after ?? {}), {
+            produces: { placeholder: placeholderFor('pipe_relations', c.key), path: ['createPipeRelation', 'pipeRelation', 'id'] },
+        });
+    }
+    for (const c of byEntityOp('pipe_relations', ['update'])) {
+        await graphqlStep(c, 'update', M.updatePipeRelation(ctx.client, c.after ?? {}));
+    }
+    // ── 5. field conditions (need field ids) ───────────────────────────────────
+    /**
+     * Which placeholders a request still names, so the plan can say so before it
+     * runs. A field condition is the case that needs it: unlike a field, it lives
+     * in its own file and must name its phase, so a condition on a phase created
+     * in the same edit reaches here as `"phase_id": "%{_new:<uuid>}"`.
+     */
+    for (const c of byEntityOp('field_conditions', ['create'])) {
+        /**
+         * Refused rather than created somewhere else. The mutation ignores the
+         * phase it is given, so applying this would put the condition on the start
+         * form and verification would then report a phase_id difference nothing can
+         * fix — the shape that leaves a workspace permanently dirty.
+         */
+        const wanted = String(c.after?.['phase_id'] ?? '');
+        const startForm = ctx.startFormPhaseId === null || ctx.startFormPhaseId === undefined
+            ? ''
+            : String(ctx.startFormPhaseId);
+        if (startForm && wanted && wanted !== startForm) {
+            blocked.push({
+                changeKey: c.key,
+                entity: 'field_conditions',
+                op: 'create',
+                status: 'UNSUPPORTED',
+                reason: `createFieldCondition ignores phaseId and always creates on the start form (${startForm}), ` +
+                    `so a condition on phase ${wanted} cannot be created through the API — build it in the UI`,
+                label: c.label,
+            });
+            continue;
+        }
+        const req = await M.createFieldCondition(ctx.client, c.after ?? {});
+        emit({
+            changeKey: c.key,
+            entity: 'field_conditions',
+            op: 'create',
+            kind: 'graphql',
+            unverified: offline,
+            description: `createFieldCondition — ${c.label}`,
+            request: req,
+            needs: placeholdersIn(req.variables),
+            produces: { placeholder: placeholderFor('field_conditions', c.key), path: ['createFieldCondition', 'fieldCondition', 'id'] },
+        });
+    }
+    for (const c of byEntityOp('field_conditions', ['update'])) {
+        await graphqlStep(c, 'update', M.updateFieldCondition(ctx.client, c.after ?? {}));
+    }
+    // ── 6. automations (need field and phase ids) ──────────────────────────────
+    /**
+     * Every automation is checked against the catalogue before a step is emitted.
+     *
+     * A parameter the event or action does not accept is rejected by the API with
+     * the words "is invalid" and nothing else — no parameter name, no event name.
+     * The catalogue says exactly what each accepts, so the refusal can name it.
+     *
+     * Real case: `event_id: card_moved` with `event_params.inPhaseId`. `inPhaseId`
+     * is a real parameter — of `card_inbox_received_email`. `card_moved` accepts
+     * only `to_phase_id`.
+     */
+    const checkAuto = (c) => {
+        if (!ctx.automationCatalogue)
+            return true;
+        const findings = checkAutomationParams(c.after ?? {}, ctx.automationCatalogue);
+        const errors = findings.filter((f) => f.severity === 'error');
+        if (!errors.length)
+            return true;
+        for (const f of errors) {
+            warnings.push(`${c.label}: ${f.message}${f.fix ? ` — ${f.fix}` : ''}`);
+        }
+        blocked.push({
+            changeKey: c.key,
+            entity: c.entity,
+            // The change's own op — an update refused by the catalogue is still an
+            // update. This was hardcoded to 'create' regardless of which loop called
+            // it, so a blocked update reported "automations.create", naming the
+            // wrong operation for the one thing an FDE most needs right: whether
+            // reverting means undoing an edit or deleting something new.
+            // checkAuto is only ever called from the automations create/update
+            // loops below, so c.op is always one of these two in practice.
+            op: c.op,
+            status: 'UNSUPPORTED',
+            reason: errors.map((f) => f.message).join('; '),
+            label: c.label,
+        });
+        return false;
+    };
+    for (const c of byEntityOp('automations', ['create'])) {
+        if (!checkAuto(c))
+            continue;
+        emit({
+            changeKey: c.key,
+            entity: 'automations',
+            op: 'create',
+            kind: 'graphql',
+            unverified: offline,
+            description: `createAutomation — ${c.label}`,
+            request: await M.createAutomation(ctx.client, c.after ?? {}),
+            needs: placeholdersIn(M.automationVariables(c.after ?? {})),
+            produces: { placeholder: placeholderFor('automations', c.key), path: ['createAutomation', 'automation', 'id'] },
+        });
+    }
+    for (const c of byEntityOp('automations', ['update'])) {
+        if (!checkAuto(c))
+            continue;
+        if (options.automationStrategy === 'recreate') {
+            /**
+             * Delete and recreate, only when asked for.
+             *
+             * This was the default, inherited from the Change Migrator recipes on the
+             * grounds that `action_params` does not round-trip through the update
+             * path. Measured against the live API and it does: name, field map value,
+             * switching the mapped field, several field maps at once, `input_mode`,
+             * `action_id`, `event_id` and removing a condition all round-trip through
+             * `updateAutomation`. `UpdateAutomationInput` also accepts every field
+             * `CreateAutomationInput` does, so nothing forces a recreate.
+             *
+             * Recreating costs the automation's id, its uuid and its run history, and
+             * leaves a window where the automation does not exist. It stays available
+             * for the case where an update is refused and starting clean is the
+             * intent.
+             */
+            emit({
+                changeKey: c.key,
+                entity: 'automations',
+                op: 'delete',
+                kind: 'graphql',
+                description: `deleteAutomation (recreate strategy) — ${c.label}`,
+                request: await M.deleteAutomation(ctx.client, String(c.before?.['id'] ?? '')),
+                needs: [],
+                destructive: true,
+            });
+            emit({
+                changeKey: c.key,
+                entity: 'automations',
+                op: 'create',
+                kind: 'graphql',
+                description: `createAutomation (recreate strategy) — ${c.label}`,
+                request: await M.createAutomation(ctx.client, c.after ?? {}),
+                needs: placeholdersIn(M.automationVariables(c.after ?? {})),
+                produces: { placeholder: placeholderFor('automations', c.key), path: ['createAutomation', 'automation', 'id'] },
+            });
+        }
+        else {
+            emit({
+                changeKey: c.key,
+                entity: 'automations',
+                op: 'update',
+                kind: 'graphql',
+                description: `updateAutomation — ${c.label}`,
+                request: await M.updateAutomation(ctx.client, c.after ?? {}),
+                needs: [],
+            });
+        }
+    }
+    // ── 7. phase jumps and team settings (need phase ids) ──────────────────────
+    for (const c of byEntityOp('phase_jumps', ['update'])) {
+        const phaseChange = cs.changes.find((x) => x.entity === 'phases' && x.op === 'create' && x.key === c.owner?.key);
+        const phaseId = phaseChange
+            ? placeholderFor('phases', phaseChange.key)
+            : String(c.after?.['phase_id'] ?? c.before?.['phase_id'] ?? '');
+        const requested = c.after?.['jump_target_ids'] ?? [];
+        /**
+         * The endpoint is set-replacing, so a jump set is sent whole. A real pipe
+         * carries five jumps pointing at phases that no longer exist — real data
+         * from a real pipe. Those orphans are pre-existing and harmless while
+         * nothing touches the phase, but resending them as part of an unrelated
+         * change would either fail or recreate garbage, so they are dropped here and
+         * the drop is reported rather than silent.
+         */
+        /**
+         * A target naming a phase created in this same plan is kept: it has no id to
+         * check against yet, and the executor substitutes one before the request
+         * goes out. Without this the orphan filter below dropped it as "not a phase
+         * of this pipe" — which was true, and beside the point.
+         */
+        const isPlaceholder = (t) => typeof t === 'string' && t.includes('_new:');
+        // A null target is a real state — a jump slot enabled with no destination
+        // phase chosen — not an orphan pointing at a deleted phase. Kept out of
+        // the orphan check (`Number(null)` is 0, which would otherwise coincide
+        // with no real phase id but is still the wrong reason) and left out of
+        // the outgoing set on its own: there is no confirmed way to tell this
+        // set-replacing endpoint "and one slot with no target", so guessing one
+        // (sending the literal string "null") risks writing garbage to a live
+        // pipe rather than just dropping a slot nothing here can express yet.
+        const targets = requested.filter((t) => t !== null && (isPlaceholder(t) || livePhaseIdSet.size === 0 || livePhaseIdSet.has(Number(t))));
+        const droppedOrphans = requested.filter((t) => t !== null && !targets.includes(t));
+        const droppedNullCount = requested.filter((t) => t === null).length;
+        if (droppedOrphans.length) {
+            warnings.push(`phase "${c.owner?.label ?? phaseId}": jump target(s) ${droppedOrphans.join(', ')} are not phases of this pipe and were left out of the set`);
+        }
+        if (droppedNullCount) {
+            warnings.push(`phase "${c.owner?.label ?? phaseId}": ${droppedNullCount} jump target(s) with no destination phase chosen were left out of the set — there is no confirmed way to send "no target" to this endpoint`);
+        }
+        emit({
+            changeKey: c.key,
+            entity: 'phase_jumps',
+            op: 'update',
+            kind: 'internal-rest',
+            description: `PUT settings/phases/:id — ${c.label} → [${targets.join(', ')}]`,
+            request: {
+                method: 'PUT',
+                path: `${ENDPOINTS.internalSettings}/phases/${phaseId}`,
+                form: { 'phase[jump_target_ids][]': targets.map(String) },
+            },
+            needs: [
+                ...(phaseChange ? [placeholderFor('phases', phaseChange.key)] : []),
+                ...placeholdersIn(targets),
+            ],
+            unverified: true,
+        });
+    }
+    /**
+     * A created phase's stated jump set has no diff of its own — there is no
+     * baseline row to compare against — so it would never be written, and Pipefy's
+     * auto-link would stand instead. Emitted only when the author stated targets:
+     * an empty set is silence, and forcing it would leave the phase unreachable.
+     */
+    for (const c of byEntityOp('phases', ['create'])) {
+        const stated = c.after?.['jump_target_ids'] ?? [];
+        const targets = stated.filter((t) => t !== null);
+        const droppedNullCount = stated.length - targets.length;
+        if (droppedNullCount) {
+            warnings.push(`phase "${c.label}": ${droppedNullCount} jump target(s) with no destination phase chosen were left out of the set — there is no confirmed way to send "no target" to this endpoint`);
+        }
+        if (!targets.length)
+            continue;
+        const phasePlaceholder = placeholderFor('phases', c.key);
+        const resolved = targets.map((t) => String(t));
+        emit({
+            changeKey: c.key,
+            entity: 'phase_jumps',
+            op: 'update',
+            kind: 'internal-rest',
+            description: `PUT settings/phases/:id — ${c.label} → [${resolved.join(', ')}] (new phase)`,
+            request: {
+                method: 'PUT',
+                path: `${ENDPOINTS.internalSettings}/phases/${phasePlaceholder}`,
+                form: { 'phase[jump_target_ids][]': resolved },
+            },
+            needs: [phasePlaceholder],
+            unverified: true,
+        });
+    }
+    for (const c of byEntityOp('phase_team_memberships', ['update'])) {
+        const phaseId = String(c.after?.['phase_id'] ?? c.before?.['phase_id'] ?? '');
+        await graphqlStep(c, 'update', M.phaseSettings(ctx.client, phaseId, { team_member_ids: c.after?.['team_member_ids'] }));
+    }
+    // ── 8. preferences and public form ─────────────────────────────────────────
+    for (const c of byEntityOp('repo_preferences', ['update', 'create'])) {
+        /**
+         * Two mutations, because the preference surface is split: the hidden-attribute
+         * arrays go to updateRepoPreferences (keyed on the repo uuid), and findable /
+         * inboxEmailEnabled / mainTabViews go through updatePipe.preferences. Anything
+         * else in the payload's repo_preferences row has no input at all.
+         */
+        await graphqlStep(c, 'update', M.updateRepoPreferences(ctx.client, ctx.repoUuid, c.after ?? {}));
+        await graphqlStep(c, 'update', M.updatePipePreferences(ctx.client, ctx.repoId, c.after ?? {}));
+    }
+    for (const c of byEntityOp('public_forms', ['update', 'create'])) {
+        await graphqlStep(c, 'update', M.updatePublicForm(ctx.client, ctx.repoId, c.after ?? {}));
+    }
+    // ── 9. deletes, in reverse dependency order ────────────────────────────────
+    for (const c of byEntityOp('automations', ['delete'])) {
+        emit({
+            changeKey: c.key,
+            entity: 'automations',
+            op: 'delete',
+            kind: 'graphql',
+            description: `deleteAutomation — ${c.label}`,
+            request: await M.deleteAutomation(ctx.client, String(c.before?.['id'] ?? '')),
+            needs: [],
+            destructive: true,
+        });
+    }
+    for (const c of byEntityOp('field_conditions', ['delete'])) {
+        await graphqlStep(c, 'delete', M.deleteFieldCondition(ctx.client, String(c.before?.['id'] ?? '')), { destructive: true });
+    }
+    for (const c of byEntityOp('fields', ['delete'])) {
+        await graphqlStep(c, 'delete', repoKind === 'table'
+            ? M.deleteTableField(ctx.client, ctx.repoId, c.before ?? {})
+            : M.deletePhaseField(ctx.client, c.before ?? {}, ctx.repoUuid), {
+            destructive: true,
+        });
+    }
+    for (const c of byEntityOp('phases', ['delete'])) {
+        if (!options.allowCardMoves) {
+            warnings.push(`deleting phase "${c.label}" can only proceed with --allow-card-moves: any cards in it must be moved first ` +
+                `(the recipes create an "Archive(Migration)" phase and move them)`);
+            continue;
+        }
+        await graphqlStep(c, 'delete', M.deletePhase(ctx.client, String(c.before?.['id'] ?? '')), { destructive: true });
+    }
+    for (const c of byEntityOp('labels', ['delete'])) {
+        await graphqlStep(c, 'delete', M.deleteLabel(ctx.client, String(c.before?.['id'] ?? '')), { destructive: true });
+    }
+    for (const c of byEntityOp('webhooks', ['delete'])) {
+        await graphqlStep(c, 'delete', M.deleteWebhook(ctx.client, String(c.before?.['id'] ?? '')), { destructive: true });
+    }
+    for (const c of byEntityOp('pipe_relations', ['delete'])) {
+        await graphqlStep(c, 'delete', M.deletePipeRelation(ctx.client, String(c.before?.['id'] ?? '')), { destructive: true });
+    }
+    // ── 10. field condition order, last: it references ids created above ───────
+    /**
+     * The order the workspace states, for every condition in the phase.
+     *
+     * A condition the workspace creates has no id yet, so it goes in as the
+     * placeholder its create step produces — matched by name, which is what the
+     * diff identifies a condition by too, since the payload row has no uuid.
+     */
+    const fcCreates = cs.changes.filter((c) => c.entity === 'field_conditions' && c.op === 'create' && supported(c.key));
+    for (const [phaseId, rows] of Object.entries(ctx.conditionOrder ?? {})) {
+        if (rows.length < 2)
+            continue;
+        const ids = rows.map((r) => {
+            if (r.id)
+                return String(r.id);
+            const created = fcCreates.find((c) => String(c.after?.['name'] ?? '') === r.name);
+            return created ? placeholderFor('field_conditions', created.key) : null;
+        });
+        /**
+         * An order containing something this plan cannot name is not written at
+         * all. A partial list would drop the unnamed condition out of the phase
+         * order, which is a change nobody asked for.
+         */
+        if (ids.some((id) => id === null)) {
+            warnings.push(`field condition order in phase ${phaseId} was left alone: ` +
+                `${ids.filter((id) => id === null).length} condition(s) in it are neither live nor created here`);
+            continue;
+        }
+        const baseline = ctx.baselineConditionOrder?.[phaseId] ?? [];
+        const stated = ids;
+        /**
+         * Only when the order differs from the one the pipe will already have.
+         *
+         * Re-sending an order the pipe already has is answered with "Something went
+         * wrong" — a failed step, and a failed apply, for a write with nothing to do.
+         *
+         * The previous guard compared against the baseline and gave up whenever a
+         * placeholder was present, on the grounds that a placeholder cannot be
+         * compared to a live id. But the server's placement is predictable: a newly
+         * created condition is appended after the ones already there. So the order to
+         * compare against is the baseline followed by this phase's creates in the
+         * order they are applied — which means appending a condition, the ordinary
+         * case, needs no reorder at all. Authoring it anywhere else still differs and
+         * is still written.
+         */
+        const appended = fcCreates
+            .filter((c) => String(c.after?.['phase_id'] ?? '') === String(phaseId))
+            .map((c) => placeholderFor('field_conditions', c.key));
+        /**
+         * Deletes shift the order too. Removing a condition leaves the rest in the
+         * order they were already in, so a delete on its own needs no reorder — and
+         * asking for the order that remains was answered with "Something went wrong",
+         * failing an apply whose real work had already succeeded.
+         */
+        const removed = new Set(cs.changes
+            .filter((c) => c.entity === 'field_conditions' && c.op === 'delete')
+            .map((c) => String(c.before?.['id'] ?? '')));
+        const natural = [...baseline.filter((id) => !removed.has(String(id))), ...appended];
+        const unchanged = natural.length === stated.length && stated.every((id, i) => id === natural[i]);
+        if (unchanged)
+            continue;
+        const anchor = fcCreates[0] ?? cs.changes.find((c) => c.entity === 'field_conditions');
+        if (!anchor)
+            continue;
+        await graphqlStep({ ...anchor, label: `field condition order in phase ${phaseId}` }, 'reorder', M.setFieldConditionOrder(ctx.client, phaseId, stated), { unverified: true });
+    }
+    debug(`compiled ${steps.length} steps from ${cs.changes.length} changes (${blocked.length} blocked)`);
+    const idMap = {};
+    for (const map of Object.values(cs.idMap)) {
+        for (const [k, v] of Object.entries(map ?? {}))
+            if (String(k) !== String(v))
+                idMap[k] = v;
+    }
+    return {
+        id: `${new Date().toISOString().replace(/[:.]/g, '-')}--${randomUUID().slice(0, 8)}`,
+        createdAt: new Date().toISOString(),
+        workspace: ctx.workspace,
+        repoId: ctx.repoId,
+        repoUuid: ctx.repoUuid,
+        mode: cs.mode,
+        options,
+        steps,
+        classifications,
+        blocked,
+        warnings,
+        idMap,
+        status: 'planned',
+    };
+};