@pipefy/pipefy-process-coder 0.1.0

package/src/apply/flowops.ts

@@ -0,0 +1,399 @@
+import { linkFlow, type FlowNode, type FlowTree } from '../codec/flow.ts';
+import type { FlowChange, FlowChangeSet } from '../diff/flow.ts';
+import type { FlowOperation } from '../pipefy/ipaas.ts';
+import type { Row } from '../model/payload.ts';
+
+/**
+ * Compiling flow changes into iPaaS operations.
+ *
+ * The operation set was probed against the live endpoint, and two facts shape
+ * everything here.
+ *
+ * **`IMPORT_FLOW` is never used.** It replaces the whole tree and runs the schema
+ * migration an old export needs, so a flow already in live form comes back with
+ * every datapill doubled — `{{step_1['output'].x}}` → `{{step_1['output']['output'].x}}` —
+ * and then resolves nothing at runtime while every validator still calls it valid.
+ * The granular operations do not migrate.
+ *
+ * **Four operations act on an empty request** instead of rejecting it:
+ * `CHANGE_STATUS`, `LOCK_AND_PUBLISH`, `LOCK_FLOW`, `CHANGE_FOLDER`,
+ * `UPDATE_METADATA`. Probing the enum by sending each with `request: {}`
+ * published and enabled a draft flow. Every request built here is complete and
+ * explicit; the client refuses an empty one for those types.
+ *
+ * Shapes, as the endpoint validated them:
+ *
+ *   UPDATE_TRIGGER   { name, type, displayName, valid, settings }   — the whole node
+ *   UPDATE_ACTION    { name, type, displayName, valid, settings }   — the whole node
+ *   ADD_ACTION       { parentStep, action: {...whole node...}, stepLocationRelativeToParent? }
+ *   DELETE_ACTION    { names: [ ... ] }                             — an array
+ *   CHANGE_NAME      { displayName }
+ *   CHANGE_STATUS    { status: 'ENABLED' | 'DISABLED' }
+ *
+ * A router's branches live in `settings.branches`, so editing them is an
+ * `UPDATE_ACTION` on the router. There is no `UPDATE_BRANCH` in the enum.
+ *
+ * **`stepLocationRelativeToParent` is optional only when the parent is not a
+ * loop.** Omitting it to add a step after a `LOOP_ON_ITEMS` — exiting the
+ * loop, as opposed to entering it — is refused with `Loop step parent
+ * undefined not found`; `'AFTER'` sent explicitly is what the same add needs.
+ * `'INSIDE_LOOP'` (entering) and `'INSIDE_BRANCH'` + `branchIndex` (a router
+ * child) both already required the field and both already worked. Measured
+ * on a throwaway flow (`research/ipaas/probe-loop-shape-3.ts`) after this
+ * exact shape failed live building the first flow this tool ever wrote with
+ * a loop in it — every flow before had none.
+ */
+
+export type FlowStep = {
+  id: string;
+  index: number;
+  changeKey: string;
+  /** Which flow this acts on. Null when the flow is created by an earlier step. */
+  flowId: string | null;
+  /** For a create: the display name to create the flow with. */
+  createFlow?: { displayName: string; tree: FlowTree };
+  /** For a delete of the whole flow. */
+  deleteFlow?: boolean;
+  /**
+   * A connection a flow references that the project does not have.
+   *
+   * Created with a placeholder credential so the flow can be built: the
+   * structure is what is being authored and it does not depend on the
+   * credential working. The flow stays DISABLED, and the apply reports which
+   * connections still need reconnecting.
+   */
+  createConnection?: { pieceName: string; displayName: string; externalId: string };
+  operation?: { type: FlowOperation; request: Record<string, unknown> };
+  description: string;
+  destructive?: boolean;
+  /** Set when the step would arm a flow against live traffic. */
+  arms?: boolean;
+  status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+  error?: string;
+  result?: unknown;
+};
+
+export type FlowPlan = {
+  steps: FlowStep[];
+  /** Changes that cannot be applied, with the reason. */
+  blocked: Array<{ key: string; label: string; reason: string }>;
+  warnings: string[];
+};
+
+/** The node as an operation request: the whole node, minus link and volatile keys. */
+const nodeRequest = (node: FlowNode): Record<string, unknown> => {
+  const { _nextAction, _firstLoopAction, _children, ...rest } = node;
+  const out: Record<string, unknown> = {
+    name: rest['name'],
+    type: rest['type'],
+    valid: rest['valid'] ?? true,
+    settings: rest['settings'] ?? {},
+  };
+  if (rest['displayName'] !== undefined) out['displayName'] = rest['displayName'];
+  if (rest['skip'] !== undefined) out['skip'] = rest['skip'];
+  return out;
+};
+
+/**
+ * Where a new node hangs. `ADD_ACTION` takes the parent it follows, plus a
+ * location for the cases where "after" is ambiguous.
+ *
+ * A bare `{ parentStep }` with no location is only unambiguous when the
+ * parent is a plain step. When the parent is itself a `LOOP_ON_ITEMS`,
+ * "after it" could mean *inside* the loop or *exiting* it, and the endpoint
+ * refuses to guess: measured live (`research/ipaas/probe-loop-shape-3.ts`),
+ * the identical omitted-location request answers `Loop step parent undefined
+ * not found`, and adding `stepLocationRelativeToParent: 'AFTER'` is what
+ * makes the same add succeed. Every flow this tool wrote before had no loop
+ * at all, so this was never exercised.
+ */
+const parentOf = (tree: FlowTree, nodeName: string): { parentStep: string; location?: string; branchIndex?: number } | null => {
+  for (const candidate of tree.nodes) {
+    if (candidate['_nextAction'] === nodeName) {
+      return { parentStep: candidate.name, ...(candidate['type'] === 'LOOP_ON_ITEMS' ? { location: 'AFTER' } : {}) };
+    }
+    if (candidate['_firstLoopAction'] === nodeName) {
+      return { parentStep: candidate.name, location: 'INSIDE_LOOP' };
+    }
+    const children = (candidate['_children'] as Array<string | null> | undefined) ?? [];
+    const at = children.indexOf(nodeName);
+    if (at >= 0) return { parentStep: candidate.name, location: 'INSIDE_BRANCH', branchIndex: at };
+  }
+  return null;
+};
+
+/** Every `{{connections['x']}}` a flow references, with the piece that needs it. */
+export const connectionsUsedBy = (tree: FlowTree): Array<{ externalId: string; pieceName: string }> => {
+  const out = new Map<string, string>();
+  const CONN = /connections\['([^']+)'\]/g;
+  for (const node of tree.nodes) {
+    const settings = (node['settings'] ?? {}) as Record<string, unknown>;
+    const piece = String(settings['pieceName'] ?? '');
+    const text = JSON.stringify(settings['input'] ?? {});
+    for (const m of text.matchAll(CONN)) {
+      const id = m[1] as string;
+      if (!out.has(id)) out.set(id, piece);
+    }
+  }
+  return [...out].map(([externalId, pieceName]) => ({ externalId, pieceName }));
+};
+
+export const compileFlows = (
+  cs: FlowChangeSet,
+  opts: {
+    allowArm?: boolean;
+    /** externalId -> the connection the project already has. */
+    connections?: Map<string, { pieceName: string; status: string }>;
+  } = {},
+): FlowPlan => {
+  const steps: FlowStep[] = [];
+  const blocked: FlowPlan['blocked'] = [];
+  const warnings: string[] = [];
+
+  const emit = (partial: Omit<FlowStep, 'id' | 'index' | 'status'>) => {
+    steps.push({ id: `f${String(steps.length + 1).padStart(3, '0')}`, index: steps.length, status: 'pending', ...partial });
+  };
+
+  /**
+   * Order matters and is not the diff's order.
+   *
+   * Creates before the changes that reference them; node deletes before node
+   * adds, so a rename that is really a delete-plus-add does not collide on a
+   * name; and status last, because arming a flow should be the final thing that
+   * happens to it, after its contents are what they should be.
+   */
+  const order: Record<FlowChange['op'], number> = {
+    'flow.create': 0,
+    'flow.rename': 1,
+    'node.delete': 2,
+    'trigger.update': 3,
+    'node.create': 4,
+    'node.update': 5,
+    'flow.delete': 6,
+    'flow.status': 7,
+  };
+  const sorted = [...cs.changes].sort((a, b) => order[a.op] - order[b.op]);
+
+  /**
+   * Connections first: a flow cannot be created referencing one the project does
+   * not have. A missing connection used to be a refusal, which stalled the whole
+   * build for something the flow structure does not depend on.
+   */
+  if (opts.connections) {
+    const needed = new Map<string, string>();
+    for (const c of cs.changes) {
+      const tree = (c.afterFlow ?? null) as FlowTree | null;
+      if (!tree) continue;
+      for (const use of connectionsUsedBy(tree)) {
+        if (opts.connections.has(use.externalId)) continue;
+        if (!needed.has(use.externalId)) needed.set(use.externalId, use.pieceName);
+      }
+    }
+    for (const [externalId, pieceName] of needed) {
+      emit({
+        changeKey: `connection:${externalId}`,
+        flowId: null,
+        createConnection: {
+          pieceName,
+          externalId,
+          displayName: `${pieceName.split('/').pop()} (placeholder, reconnect me)`,
+        },
+        description: `create placeholder connection ${externalId} for ${pieceName}`,
+      });
+      warnings.push(
+        `connection ${externalId} does not exist in this project and will be created with a ` +
+          'placeholder credential — reconnect it in the product before enabling any flow that uses it',
+      );
+    }
+  }
+
+  for (const c of sorted) {
+    switch (c.op) {
+      case 'flow.create': {
+        const tree = c.afterFlow as FlowTree;
+        emit({
+          changeKey: c.key,
+          flowId: null,
+          createFlow: { displayName: c.flowName, tree },
+          description: `create flow "${c.flowName}" and add its ${tree.nodes.length} nodes`,
+        });
+        break;
+      }
+
+      case 'flow.delete': {
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          deleteFlow: true,
+          description: `delete flow "${c.flowName}"`,
+          destructive: true,
+        });
+        break;
+      }
+
+      case 'flow.rename': {
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          operation: { type: 'CHANGE_NAME', request: { displayName: c.flowName } },
+          description: `CHANGE_NAME — "${c.flowName}"`,
+        });
+        break;
+      }
+
+      case 'flow.status': {
+        const status = String(c.deltas[0]?.after ?? '');
+        if (status !== 'ENABLED' && status !== 'DISABLED') {
+          blocked.push({ key: c.key, label: c.label, reason: `status ${JSON.stringify(status)} is not ENABLED or DISABLED` });
+          break;
+        }
+        /**
+         * Enabling a flow points it at live traffic. It is refused unless asked
+         * for explicitly, the same way a phase delete needs --allow-card-moves:
+         * the cost of a wrong one is paid by the client, not by the person running
+         * the apply.
+         */
+        const usesPlaceholder = [...(opts.connections ?? new Map())].some(
+          ([, c]) => (c as { status: string })['status'] === 'PLACEHOLDER',
+        );
+        if (status === 'ENABLED' && usesPlaceholder) {
+          blocked.push({
+            key: c.key,
+            label: c.label,
+            reason:
+              'this project has a placeholder connection — reconnect it before enabling a flow, ' +
+              'or the flow will run and fail on every trigger',
+          });
+          break;
+        }
+        if (status === 'ENABLED' && !opts.allowArm) {
+          blocked.push({
+            key: c.key,
+            label: c.label,
+            reason:
+              'enabling a flow arms it against live traffic — re-run with --allow-flow-enable to do it deliberately',
+          });
+          break;
+        }
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          operation: { type: 'CHANGE_STATUS', request: { status } },
+          description: `CHANGE_STATUS — ${status}`,
+          arms: status === 'ENABLED',
+        });
+        break;
+      }
+
+      case 'trigger.update': {
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          operation: { type: 'UPDATE_TRIGGER', request: nodeRequest(c.after as FlowNode) },
+          description: `UPDATE_TRIGGER — flow "${c.flowName}"`,
+        });
+        break;
+      }
+
+      case 'node.update': {
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          operation: { type: 'UPDATE_ACTION', request: nodeRequest(c.after as FlowNode) },
+          description: `UPDATE_ACTION — ${c.nodeName} in "${c.flowName}"`,
+        });
+        break;
+      }
+
+      case 'node.delete': {
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          // `names` is an array — a single `name` is rejected.
+          operation: { type: 'DELETE_ACTION', request: { names: [c.nodeName] } },
+          description: `DELETE_ACTION — ${c.nodeName} in "${c.flowName}"`,
+          destructive: true,
+        });
+        break;
+      }
+
+      case 'node.create': {
+        const tree = c.afterFlow as FlowTree | undefined;
+        const where = tree ? parentOf(tree, c.nodeName as string) : null;
+        if (!where) {
+          // Unreachable from the chain — nothing points `_nextAction` /
+          // `_firstLoopAction` / a branch's `_children` at this node, so there is
+          // no parent to hang it from. The same case `buildFlowOperations` skips
+          // for a brand-new flow.
+          blocked.push({
+            key: c.key,
+            label: c.label,
+            reason:
+              `${c.nodeName} is not reachable from the trigger — nothing in the authored flow ` +
+              'points to it, so there is no parent to add it after.',
+          });
+          break;
+        }
+        emit({
+          changeKey: c.key,
+          flowId: c.flowId,
+          operation: {
+            type: 'ADD_ACTION',
+            request: {
+              parentStep: where.parentStep,
+              ...(where.location ? { stepLocationRelativeToParent: where.location } : {}),
+              ...(where.branchIndex !== undefined ? { branchIndex: where.branchIndex } : {}),
+              action: nodeRequest(c.after as FlowNode),
+            },
+          },
+          description: `ADD_ACTION — ${c.nodeName} [${(c.after as FlowNode).type}] after ${where.parentStep}${where.location ? ` (${where.location})` : ''} in "${c.flowName}"`,
+        });
+        break;
+      }
+    }
+  }
+
+  if (blocked.length) {
+    warnings.push(`${blocked.length} flow change(s) have no write path yet`);
+  }
+  return { steps, blocked, warnings };
+};
+
+/**
+ * The operations that build a brand-new flow's contents.
+ *
+ * A created flow arrives with an `EMPTY` trigger and nothing else, so the tree is
+ * laid down trigger-first and then each node in execution order — every node's
+ * parent already exists by the time it is added, because execution order is a
+ * topological order of the chain.
+ */
+export const buildFlowOperations = (tree: FlowTree): Array<{ type: FlowOperation; request: Record<string, unknown>; describe: string }> => {
+  const ops: Array<{ type: FlowOperation; request: Record<string, unknown>; describe: string }> = [];
+  const trigger = tree.nodes[0];
+  if (!trigger) return ops;
+
+  ops.push({ type: 'UPDATE_TRIGGER', request: nodeRequest(trigger), describe: `trigger [${trigger.type}]` });
+
+  for (const node of tree.nodes.slice(1)) {
+    const where = parentOf(tree, node.name);
+    if (!where) {
+      // Unreachable from the chain: the codec would have dropped it anyway, and
+      // adding it with a guessed parent would put it somewhere nobody asked for.
+      continue;
+    }
+    ops.push({
+      type: 'ADD_ACTION',
+      request: {
+        parentStep: where.parentStep,
+        ...(where.location ? { stepLocationRelativeToParent: where.location } : {}),
+        ...(where.branchIndex !== undefined ? { branchIndex: where.branchIndex } : {}),
+        action: nodeRequest(node),
+      },
+      describe: `${node.name} [${node.type}] after ${where.parentStep}${where.location ? ` (${where.location})` : ''}`,
+    });
+  }
+  return ops;
+};
+
+/** The API flow row a tree would produce, for verification after an apply. */
+export const intendedFlow = (tree: FlowTree): Row => linkFlow(tree);

package/src/apply/idmap.ts

@@ -0,0 +1,241 @@
+import { debug } from '../util/log.ts';
+import type { Placeholder } from './types.ts';
+
+/**
+ * Id substitution — the single subtlest thing in the write path.
+ *
+ * Two jobs, both learned from the Change Migrator recipes:
+ *
+ *  1. **Placeholders.** A new field has no id until it is created, so an
+ *     automation created in the same plan references `%{_new:<key>}` and the
+ *     executor swaps in the real id once the field exists. PLAN.md §9 flags
+ *     that this "fails only on the combination create field + reference it in
+ *     the same plan" — i.e. constantly.
+ *
+ *  2. **Cross-repo remapping.** Recipe step 120 rewrites every dev field id
+ *     inside an automation's JSON to its prod equivalent, looking each one up
+ *     through a Pipefy table with one API call per id. Same transformation
+ *     here, from the map the diff already built, with no API calls.
+ *
+ * Ids hide inside opaque JSON: `"%{<fieldId>}"`, `"field_address": "<fieldId>"`,
+ * `"trigger_field_ids": ["<fieldId>"]`. So substitution walks the whole
+ * structure. `%{...}` is rewritten anywhere it appears; a bare id is rewritten
+ * only under a key known to hold one, because rewriting every number that
+ * happens to match an id would corrupt values that merely look like ids.
+ */
+
+/** Keys whose values are ids, and may therefore be remapped when bare. */
+export const ID_BEARING_KEYS = new Set([
+  'field_address',
+  'field_id',
+  'fieldId',
+  'field_ids',
+  'fieldIds',
+  'phase_id',
+  'phaseId',
+  'phaseFieldId',
+  'to_phase_id',
+  'toPhaseId',
+  'from_phase_id',
+  'fromPhaseId',
+  'in_phase_id',
+  'inPhaseId',
+  'trigger_field_ids',
+  'triggerFieldIds',
+  'trigger_automation_id',
+  'triggerAutomationId',
+  'card_id',
+  'cardId',
+  'title_field_id',
+  'connected_pipe_id',
+  'connected_repo_id',
+  'submitter_email_field_id',
+  'email_template_id',
+  'source_id',
+  'owner_id',
+  'skills_ids',
+  'skillsIds',
+  'jump_target_ids',
+  'target_phase_id',
+  'source_phase_id',
+  // Id *lists* count too. Omitting fieldConditionIds meant a placeholder inside
+  // the array was never substituted and went to the API verbatim, which came
+  // back as "Invalid input: fieldConditionIds ([0])" — an error that says
+  // nothing about the real cause.
+  'fieldConditionIds',
+  'field_condition_ids',
+  /**
+   * The field ids an `update_card_field` automation writes, in order.
+   *
+   * Fourth omission from this list, and the most quietly damaging: nothing
+   * rejected it. `fields_map_order: ["%{433584976}"]` was stored by the API
+   * verbatim, braces and all. The automation was created, reported valid,
+   * verified clean, and selected **no fields to update** — because the UI and the
+   * engine read this list to know which fields the automation writes, and
+   * `"%{433584976}"` is not a field id. Every working automation in the org
+   * stores bare ids here.
+   *
+   * `field_map[].field_id` was substituted correctly the whole time, so the
+   * automation looked right in the workspace and did nothing on the pipe.
+   */
+  'fields_map_order',
+  'fieldsMapOrder',
+  /**
+   * The internal settings endpoint's form key, brackets and all.
+   *
+   * Substitution is keyed on the *key name*, and this one is
+   * `phase[jump_target_ids][]` — nothing like the camel or snake spellings above.
+   * Without it a target naming a phase created in the same plan was rewritten to
+   * `%{344123894}` instead of `344123894`, and the endpoint answered 404 with no
+   * hint about which value it disliked. Third time this list has been the cause;
+   * `runInternalRestStep` now asserts on the value shape as well, so a fourth
+   * omission fails loudly instead.
+   */
+  'phase[jump_target_ids][]',
+  'teamMemberIds',
+  'team_member_ids',
+  'phaseFieldIds',
+]);
+
+/**
+ * Captures the whole token including the `_new:` prefix, because that is the key
+ * placeholders are *stored* under (`placeholderFor` emits `_new:fields:<key>`).
+ * Capturing only the tail silently makes every lookup miss.
+ */
+const PLACEHOLDER_RE = /%\{(_new:[^}]+)\}/g;
+const REFERENCE_RE = /%\{(\d+)\}/g;
+
+export const placeholderFor = (entity: string, key: string): Placeholder => `_new:${entity}:${key}`;
+
+export const placeholderToken = (p: Placeholder): string => `%{${p}}`;
+
+export class IdMap {
+  /** placeholder → real id, filled in as creating steps succeed. */
+  private placeholders = new Map<string, number>();
+  /** old id → new id, for cross-repo migration. */
+  private remap = new Map<string, number>();
+
+  constructor(seed: Record<string, number> = {}) {
+    for (const [k, v] of Object.entries(seed)) this.remap.set(String(k), Number(v));
+  }
+
+  resolvePlaceholder(p: Placeholder, id: number, aliases: Placeholder[] = []) {
+    this.placeholders.set(p, id);
+    for (const a of aliases) if (a) this.placeholders.set(a, id);
+    debug(`resolved placeholder ${p}${aliases.length ? ` (+${aliases.length} alias)` : ''} -> ${id}`);
+  }
+
+  hasPlaceholder(p: Placeholder) {
+    return this.placeholders.has(p);
+  }
+
+  placeholderValue(p: Placeholder): number | undefined {
+    return this.placeholders.get(p);
+  }
+
+  addRemap(oldId: string | number, newId: number) {
+    this.remap.set(String(oldId), newId);
+  }
+
+  lookup(id: string | number): number | undefined {
+    return this.remap.get(String(id));
+  }
+
+  /** Which placeholders a value still depends on. Empty means it is ready to send. */
+  unresolved(value: unknown): Placeholder[] {
+    const out = new Set<string>();
+    const walk = (v: unknown) => {
+      if (typeof v === 'string') {
+        for (const m of v.matchAll(PLACEHOLDER_RE)) {
+          const key = m[1] as string;
+          if (!this.placeholders.has(key)) out.add(key);
+        }
+        // A bare placeholder, as compile.ts emits for phase_id on a new field.
+        if (v.startsWith('_new:') && !this.placeholders.has(v)) out.add(v);
+        return;
+      }
+      if (Array.isArray(v)) {
+        v.forEach(walk);
+        return;
+      }
+      if (v && typeof v === 'object') Object.values(v as Record<string, unknown>).forEach(walk);
+    };
+    walk(value);
+    return [...out];
+  }
+
+  private rewriteString(s: string): string {
+    let out = s.replace(PLACEHOLDER_RE, (whole, key: string) => {
+      const id = this.placeholders.get(key);
+      return id === undefined ? whole : `%{${id}}`;
+    });
+    out = out.replace(REFERENCE_RE, (whole, id: string) => {
+      const mapped = this.remap.get(id);
+      return mapped === undefined ? whole : `%{${mapped}}`;
+    });
+    return out;
+  }
+
+  /** A bare id value, remapped if it is under an id-bearing key. */
+  private rewriteBare(v: unknown): unknown {
+    if (typeof v === 'number') {
+      const mapped = this.remap.get(String(v));
+      return mapped ?? v;
+    }
+    if (typeof v === 'string') {
+      if (/^_new:/.test(v)) {
+        const id = this.placeholders.get(v);
+        return id === undefined ? v : String(id);
+      }
+      if (/^\d+$/.test(v)) {
+        const mapped = this.remap.get(v);
+        return mapped === undefined ? v : String(mapped);
+      }
+
+      /**
+       * A value under an id-bearing key that is *entirely* one reference is an
+       * id, not a template: `"phase_id": "%{_new:<uuid>}"` must become `"344…"`,
+       * not `"%{344…}"`. Only `createFieldCondition` and friends care, but they
+       * care absolutely — a braced id is rejected as a malformed ID.
+       */
+      const whole = /^%\{(_new:[^}]+|\d+)\}$/.exec(v);
+      if (whole) {
+        const key = whole[1] as string;
+        const resolved = key.startsWith('_new:') ? this.placeholders.get(key) : this.remap.get(key);
+        if (resolved !== undefined) return String(resolved);
+        // A numeric reference with no remapping is already the id it names.
+        if (!key.startsWith('_new:')) return key;
+        return v;
+      }
+
+      return this.rewriteString(v);
+    }
+    if (Array.isArray(v)) return v.map((x) => this.rewriteBare(x));
+    return v;
+  }
+
+  /** Deep-rewrite a request payload. Returns a new value; the input is untouched. */
+  rewrite<T>(value: T): T {
+    const walk = (v: unknown, keyIsIdBearing: boolean): unknown => {
+      if (typeof v === 'string') return keyIsIdBearing ? this.rewriteBare(v) : this.rewriteString(v);
+      if (typeof v === 'number') return keyIsIdBearing ? this.rewriteBare(v) : v;
+      if (Array.isArray(v)) return v.map((x) => walk(x, keyIsIdBearing));
+      if (v && typeof v === 'object') {
+        const out: Record<string, unknown> = {};
+        for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+          out[k] = walk(val, ID_BEARING_KEYS.has(k));
+        }
+        return out;
+      }
+      return v;
+    };
+    return walk(value, false) as T;
+  }
+
+  snapshot() {
+    return {
+      placeholders: Object.fromEntries(this.placeholders),
+      remap: Object.fromEntries(this.remap),
+    };
+  }
+}