@pipefy/pipefy-process-coder 0.1.0

package/src/apply/compile.ts

@@ -0,0 +1,875 @@
+import { randomUUID } from 'node:crypto';
+import { ENDPOINTS } from '../config.ts';
+import { debug } from '../util/log.ts';
+import type { EntityName, Row } from '../model/payload.ts';
+import type { Change, ChangeSet } from '../diff/diff.ts';
+import type { PipefyClient } from '../pipefy/client.ts';
+import type { Capabilities } from '../pipefy/capability.ts';
+import { checkAutomationParams, type AutomationCatalogue } from '../pipefy/automations.ts';
+import { support, type Op } from './registry.ts';
+import { placeholderFor } from './idmap.ts';
+import * as M from './mutations.ts';
+import type { Classification, Plan, PlanOptions, Step, StepRequest } from './types.ts';
+
+/**
+ * ChangeSet → ordered plan.
+ *
+ * The order is the recipes' order, which is the dependency order:
+ *
+ *   phases → start-form fields → phase fields → field conditions → automations
+ *   (`Apply Changes` steps 4, 30, 45, 65, 116)
+ *
+ * with deletes last, in reverse dependency order, because a field cannot be
+ * deleted while an automation still references it.
+ *
+ * Every change is classified against the capability registry first. An
+ * UNSUPPORTED change blocks the whole plan, naming the entity and the reason —
+ * PLAN.md §2.3, since the worst failure mode is an apply that reports success
+ * having silently ignored something.
+ */
+
+export type CompileContext = {
+  /** null when planning offline: classification and ordering need no network. */
+  client: PipefyClient | null;
+  capabilities: Capabilities | null;
+  repoId: number;
+  repoUuid: string | null;
+  workspace: string;
+  /** Present when phase deletes need somewhere to put the cards. */
+  organizationId?: string | null;
+  /**
+   * Phase ids that exist in the edited tree. Used to keep orphaned jump targets
+   * out of a set-replacing write; empty means "do not filter".
+   */
+  livePhaseIds?: number[];
+  /**
+   * Field id → uuid, for the arguments that take a uuid where the payload stores
+   * an id: `updatePipe.title_field_id` is the one that bites.
+   */
+  fieldUuidById?: Record<string, string>;
+  /**
+   * Field id -> slug, for the table arguments that take a slug where the payload
+   * stores a numeric id: `updateTable.title_field_id` refuses the internal id.
+   */
+  fieldSlugById?: Record<string, string>;
+  /**
+   * The automation event and action catalogue, read from the public API.
+   *
+   * Present so a wrong event or action parameter is refused at plan time with
+   * its name, instead of reaching the endpoint and coming back as "is invalid"
+   * — which is all either endpoint says, and it names nothing.
+   */
+  automationCatalogue?: AutomationCatalogue;
+  /**
+   * Field-condition order per phase: every condition in the phase, in the
+   * order the workspace puts them, and the order the pipe currently has.
+   *
+   * `setFieldConditionOrder` is set-replacing per phase, so it needs the whole
+   * list — and the ChangeSet only carries the conditions that changed. Ordering
+   * by whichever of those happened to be diffed first sent an arbitrary
+   * permutation and called it the intent. Both orders are supplied so a write
+   * only happens when they actually differ.
+   */
+  /**
+   * The start-form phase's id.
+   *
+   * `createFieldCondition` authorizes the `phaseId` it is given — a bogus one is
+   * refused with "Permission denied" — and then places the condition on the
+   * start form regardless. Measured: a condition asking for a mid-pipe phase,
+   * whose fields both live on that phase, landed on the start form. The UI can
+   * put conditions on any phase, so this is a limit of the mutation, not of the
+   * platform, and there is no public write path for the others.
+   */
+  startFormPhaseId?: number | string | null;
+  /**
+   * Which kind of repo this plan is for.
+   *
+   * A database's payload is a pipe's, so the ChangeSet says `fields` and `repo`
+   * for both kinds — but the mutations differ, and a database has no workflow at
+   * all. Without this the compiler would route a database's column edit through
+   * `createPhaseField` and its root edit through `updatePipe`, where every
+   * table-only column is silently dropped.
+   */
+  repoKind?: 'pipe' | 'table';
+  /**
+   * A database's columns in the order the workspace wants them, and the order
+   * the database currently has.
+   *
+   * `setTableFieldOrder` is set-replacing, so it needs the whole list, and the
+   * ChangeSet only carries the columns that changed. Both orders are supplied so
+   * the write only happens when they actually differ.
+   */
+  tableFieldOrder?: Row[];
+  baselineTableFieldOrder?: string[];
+  conditionOrder?: Record<string, Array<{ name: string; id: number | null }>>;
+  baselineConditionOrder?: Record<string, string[]>;
+};
+
+const opFor = (c: Change): Op => {
+  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 as Op;
+};
+
+const classify = (c: Change, kind: 'pipe' | 'table' = 'pipe'): Classification => {
+  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 };
+};
+
+type Emit = (partial: Omit<Step, 'id' | 'index' | 'status'>) => void;
+
+export const compile = async (cs: ChangeSet, ctx: CompileContext, options: PlanOptions): Promise<Plan> => {
+  const repoKind = ctx.repoKind ?? 'pipe';
+  const classifications = cs.changes.map((c) => classify(c, repoKind));
+  const blocked = classifications.filter((c) => c.status === 'UNSUPPORTED');
+  const warnings: string[] = [];
+
+  const steps: Step[] = [];
+  const emit: Emit = (partial) => {
+    steps.push({ id: `s${String(steps.length + 1).padStart(3, '0')}`, index: steps.length, status: 'pending', ...partial });
+  };
+
+  const supported = (key: string) => classifications.find((c) => c.changeKey === key)?.status !== 'UNSUPPORTED';
+  const byEntityOp = (entity: EntityName | 'repo', ops: Change['op'][]) =>
+    cs.changes.filter((c) => c.entity === entity && ops.includes(c.op) && supported(c.key));
+
+  const missing = (mutation: string) => 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: unknown): string[] => {
+    const found = new Set<string>();
+    const walk = (v: unknown) => {
+      if (typeof v === 'string') {
+        for (const m of v.matchAll(/%\{(_new:[^}]+)\}/g)) found.add(m[1] as string);
+        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 as Row).forEach(walk);
+    };
+    walk(value);
+    return [...found];
+  };
+
+  const graphqlStep = async (
+    c: Change,
+    op: Op,
+    request: Promise<StepRequest> | StepRequest,
+    extra: Partial<Step> = {},
+  ) => {
+    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: Change): boolean => {
+    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 as 'create' | 'update',
+      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'] as number[] | undefined) ?? [];
+
+    /**
+     * 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: unknown) => typeof t === 'string' && t.includes('_new:');
+    const targets = requested.filter(
+      (t) => isPlaceholder(t) || livePhaseIdSet.size === 0 || livePhaseIdSet.has(Number(t)),
+    );
+    const dropped = requested.filter((t) => !targets.includes(t));
+    if (dropped.length) {
+      warnings.push(
+        `phase "${c.owner?.label ?? phaseId}": jump target(s) ${dropped.join(', ')} are not phases of this pipe and were left out of the set`,
+      );
+    }
+    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 targets = ((c.after?.['jump_target_ids'] as unknown[]) ?? []).filter((t) => t !== null);
+    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 as string[];
+
+    /**
+     * 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) as string);
+    /**
+     * 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: Record<string, number> = {};
+  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',
+  };
+};