chainlesschain 0.166.0 → 0.166.2

package/src/lib/graph-kernel/compiler.js

@@ -10,7 +10,10 @@ const graphProtocolSchema = JSON.parse(
 );
 
 export const GRAPH_DEFINITION_VERSION = 1;
-export const GRAPH_DEFINITION_MIN_VERSION = 1;
+export const GRAPH_DEFINITION_MIN_VERSION = Math.max(
+  0,
+  GRAPH_DEFINITION_VERSION - 1,
+);
 export const GRAPH_COMPILE_ERROR = "CC_GRAPH_COMPILE_FAILED";
 
 const compiledGraphs = new WeakSet();
@@ -272,7 +275,14 @@ export function writeScopesOverlap(left, right) {
   return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
 }
 
-function loopMultipliers(definition, diagnostics, nodeIds) {
+function loopMultipliers(
+  definition,
+  diagnostics,
+  nodeIds,
+  nodes,
+  dependencies,
+  compensationByNode,
+) {
   const multiplier = new Map([...nodeIds].map((id) => [id, 1]));
   const membership = new Map();
   for (const [index, loop] of definition.loops.entries()) {
@@ -300,6 +310,27 @@ function loopMultipliers(definition, diagnostics, nodeIds) {
       owners.push(loop.id);
       membership.set(nodeId, owners);
       multiplier.set(nodeId, multiplier.get(nodeId) * loop.maxIterations);
+      const node = nodes.get(nodeId);
+      if (
+        node &&
+        !["none", "read"].includes(node.effectClass || "none") &&
+        !compensationByNode.has(nodeId)
+      ) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_LOOP_EFFECT_COMPENSATION_REQUIRED",
+          `#/loops/${index}/nodeIds`,
+          `effectful loop node requires an isolated compensation handler: ${nodeId}`,
+        );
+      }
+      if (node?.kind === "subgraph") {
+        diagnostic(
+          diagnostics,
+          "GRAPH_LOOP_SUBGRAPH_UNSUPPORTED",
+          `#/loops/${index}/nodeIds`,
+          `subgraph calls cannot be nested inside a loop region: ${nodeId}`,
+        );
+      }
     }
     if (
       !loop.nodeIds.includes(loop.entryNodeId) ||
@@ -312,6 +343,67 @@ function loopMultipliers(definition, diagnostics, nodeIds) {
         "loop entry and exit must be members of the region",
       );
     }
+    const regionNodeIds = new Set(loop.nodeIds);
+    const regionOutgoing = new Map(
+      loop.nodeIds.map((nodeId) => [nodeId, new Set()]),
+    );
+    for (const nodeId of loop.nodeIds) {
+      for (const dependency of dependencies.get(nodeId) || []) {
+        if (regionNodeIds.has(dependency)) {
+          regionOutgoing.get(dependency).add(nodeId);
+        } else if (nodeId !== loop.entryNodeId) {
+          diagnostic(
+            diagnostics,
+            "GRAPH_LOOP_ENTRY_LEAK",
+            `#/loops/${index}/entryNodeId`,
+            `external dependencies may only enter a loop through its entry node: ${nodeId} depends on ${dependency}`,
+          );
+        }
+      }
+    }
+    const canReach = (source, target) => {
+      const pending = [source];
+      const seen = new Set();
+      while (pending.length) {
+        const current = pending.pop();
+        if (current === target) return true;
+        if (seen.has(current)) continue;
+        seen.add(current);
+        pending.push(...(regionOutgoing.get(current) || []));
+      }
+      return false;
+    };
+    for (const nodeId of loop.nodeIds) {
+      if (!canReach(loop.entryNodeId, nodeId)) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_LOOP_NODE_UNREACHABLE_FROM_ENTRY",
+          `#/loops/${index}/nodeIds`,
+          `loop node is unreachable from its entry: ${nodeId}`,
+        );
+      }
+      if (!canReach(nodeId, loop.exitNodeId)) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_LOOP_NODE_CANNOT_REACH_EXIT",
+          `#/loops/${index}/nodeIds`,
+          `loop node cannot reach its exit: ${nodeId}`,
+        );
+      }
+    }
+    for (const node of definition.nodes) {
+      if (regionNodeIds.has(node.id)) continue;
+      for (const dependency of dependencies.get(node.id) || []) {
+        if (regionNodeIds.has(dependency) && dependency !== loop.exitNodeId) {
+          diagnostic(
+            diagnostics,
+            "GRAPH_LOOP_EXIT_LEAK",
+            `#/loops/${index}/exitNodeId`,
+            `nodes outside a loop may only depend on its exit node: ${node.id} depends on ${dependency}`,
+          );
+        }
+      }
+    }
   }
   for (const [nodeId, owners] of membership) {
     if (owners.length > 1) {
@@ -327,12 +419,19 @@ function loopMultipliers(definition, diagnostics, nodeIds) {
   return multiplier;
 }
 
-function budgetUpperBound(definition, multiplier, diagnostics) {
+function budgetUpperBound(
+  definition,
+  multiplier,
+  diagnostics,
+  subgraphCalls = new Map(),
+) {
   const total = Object.fromEntries(BUDGET_FIELDS.map((field) => [field, 0]));
   for (const node of definition.nodes) {
+    const subgraphBudget = subgraphCalls.get(node.id)?.budget;
     for (const field of BUDGET_FIELDS) {
       total[field] +=
-        Number(node.budget?.[field] || 0) * multiplier.get(node.id);
+        Number(subgraphBudget?.[field] ?? node.budget?.[field] ?? 0) *
+        multiplier.get(node.id);
     }
   }
   for (const field of BUDGET_FIELDS) {
@@ -350,9 +449,172 @@ function budgetUpperBound(definition, multiplier, diagnostics) {
   return total;
 }
 
+function subgraphTarget(registry, definitionId) {
+  return registry instanceof Map
+    ? registry.get(definitionId)
+    : registry[definitionId];
+}
+
+function requiredPortNames(ports) {
+  return (ports || [])
+    .filter((port) => port.required !== false)
+    .map((port) => port.name);
+}
+
+function validateSubgraphPortBindings(
+  call,
+  callNode,
+  targetDefinition,
+  callIndex,
+  diagnostics,
+) {
+  const parentInputs = new Map(
+    (callNode?.inputs || []).map((port) => [port.name, port]),
+  );
+  const parentOutputs = new Map(
+    (callNode?.outputs || []).map((port) => [port.name, port]),
+  );
+  const childNodes = new Map(
+    (targetDefinition?.nodes || []).map((node) => [node.id, node]),
+  );
+  const mappedInputs = new Set();
+  const mappedChildInputs = new Set();
+  const mappedOutputs = new Set();
+
+  const validateBindings = (direction) => {
+    const bindings = call[`${direction}Bindings`] || [];
+    for (const [bindingIndex, binding] of bindings.entries()) {
+      const path = `#/subgraphCalls/${callIndex}/${direction}Bindings/${bindingIndex}`;
+      const parentPorts = direction === "input" ? parentInputs : parentOutputs;
+      const parentPort = parentPorts.get(binding.parentPort);
+      const childNode = childNodes.get(binding.childNodeId);
+      const childPorts = new Map(
+        (childNode?.[direction === "input" ? "inputs" : "outputs"] || []).map(
+          (port) => [port.name, port],
+        ),
+      );
+      const childPort = childPorts.get(binding.childPort);
+      const parentSet = direction === "input" ? mappedInputs : mappedOutputs;
+      if (parentSet.has(binding.parentPort)) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_DUPLICATE_PARENT_PORT",
+          `${path}/parentPort`,
+          `subgraph ${direction} port is mapped more than once: ${binding.parentPort}`,
+        );
+      }
+      parentSet.add(binding.parentPort);
+      if (!parentPort) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_UNKNOWN_PARENT_PORT",
+          `${path}/parentPort`,
+          `unknown parent ${direction} port: ${binding.parentPort}`,
+        );
+      }
+      if (!childNode) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_UNKNOWN_CHILD_NODE",
+          `${path}/childNodeId`,
+          `unknown child node: ${binding.childNodeId}`,
+        );
+      } else if (!childPort) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_UNKNOWN_CHILD_PORT",
+          `${path}/childPort`,
+          `unknown child ${direction} port: ${binding.childNodeId}.${binding.childPort}`,
+        );
+      }
+      if (direction === "input") {
+        const childKey = `${binding.childNodeId}\0${binding.childPort}`;
+        if (mappedChildInputs.has(childKey)) {
+          diagnostic(
+            diagnostics,
+            "GRAPH_SUBGRAPH_DUPLICATE_CHILD_INPUT",
+            path,
+            `child input is mapped more than once: ${binding.childNodeId}.${binding.childPort}`,
+          );
+        }
+        mappedChildInputs.add(childKey);
+      }
+      const producer = direction === "input" ? parentPort : childPort;
+      const consumer = direction === "input" ? childPort : parentPort;
+      if (
+        producer &&
+        consumer &&
+        !isPortSchemaAssignable(producer.schema, consumer.schema)
+      ) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_PORT_TYPE_MISMATCH",
+          path,
+          direction === "input"
+            ? `${callNode.id}.${binding.parentPort} is not assignable to ${binding.childNodeId}.${binding.childPort}`
+            : `${binding.childNodeId}.${binding.childPort} is not assignable to ${callNode.id}.${binding.parentPort}`,
+        );
+      }
+    }
+  };
+
+  validateBindings("input");
+  validateBindings("output");
+
+  for (const portName of requiredPortNames(callNode?.inputs)) {
+    if (!mappedInputs.has(portName)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_SUBGRAPH_REQUIRED_INPUT_UNMAPPED",
+        `#/subgraphCalls/${callIndex}/inputBindings`,
+        `required parent input is not mapped into the child graph: ${portName}`,
+      );
+    }
+  }
+  for (const portName of requiredPortNames(callNode?.outputs)) {
+    if (!mappedOutputs.has(portName)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_SUBGRAPH_REQUIRED_OUTPUT_UNMAPPED",
+        `#/subgraphCalls/${callIndex}/outputBindings`,
+        `required parent output is not mapped from the child graph: ${portName}`,
+      );
+    }
+  }
+
+  const internallyBoundInputs = new Set(
+    (targetDefinition?.edges || [])
+      .filter((edge) => edge.kind === "data")
+      .map((edge) => `${edge.to}\0${edge.toPort}`),
+  );
+  for (const childNode of childNodes.values()) {
+    for (const portName of requiredPortNames(childNode.inputs)) {
+      const key = `${childNode.id}\0${portName}`;
+      if (
+        !mappedChildInputs.has(key) &&
+        !internallyBoundInputs.has(key) &&
+        !Object.hasOwn(childNode.inputBindings || {}, portName)
+      ) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_REQUIRED_CHILD_INPUT_UNBOUND",
+          `#/subgraphCalls/${callIndex}/inputBindings`,
+          `required child input has no internal or parent binding: ${childNode.id}.${portName}`,
+        );
+      }
+    }
+  }
+}
+
 function validateSubgraphs(definition, nodeIds, options, diagnostics) {
   const registry = options.subgraphs || new Map();
   const calls = new Map();
+  const registryDefinitions = new Map();
+  const registryEntries =
+    registry instanceof Map ? registry.entries() : Object.entries(registry);
+  for (const [id, value] of registryEntries) {
+    registryDefinitions.set(id, stableValue(value?.definition || value));
+  }
   for (const [index, call] of definition.subgraphCalls.entries()) {
     if (!nodeIds.has(call.nodeId)) {
       diagnostic(
@@ -362,10 +624,24 @@ function validateSubgraphs(definition, nodeIds, options, diagnostics) {
         `subgraph call node does not exist: ${call.nodeId}`,
       );
     }
-    const target =
-      registry instanceof Map
-        ? registry.get(call.definitionId)
-        : registry[call.definitionId];
+    const callNode = definition.nodes.find((node) => node.id === call.nodeId);
+    if (callNode && callNode.kind !== "subgraph") {
+      diagnostic(
+        diagnostics,
+        "GRAPH_SUBGRAPH_NODE_KIND_INVALID",
+        `#/subgraphCalls/${index}/nodeId`,
+        `subgraph call must target a node with kind=subgraph: ${call.nodeId}`,
+      );
+    }
+    const target = subgraphTarget(registry, call.definitionId);
+    if (!target && options.allowUnresolvedSubgraphs !== true) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_SUBGRAPH_DEFINITION_REQUIRED",
+        `#/subgraphCalls/${index}/definitionId`,
+        `subgraph definition must be available during compilation: ${call.definitionId}`,
+      );
+    }
     if (target && target.revisionDigest !== call.revisionDigest) {
       diagnostic(
         diagnostics,
@@ -374,7 +650,44 @@ function validateSubgraphs(definition, nodeIds, options, diagnostics) {
         `subgraph digest does not match pinned revision: ${call.definitionId}`,
       );
     }
-    calls.set(call.nodeId, call);
+    const targetDefinition = target?.definition || target;
+    if (targetDefinition) {
+      validateSubgraphPortBindings(
+        call,
+        callNode,
+        targetDefinition,
+        index,
+        diagnostics,
+      );
+    }
+    const targetBudget = target?.budgetUpperBound || targetDefinition?.budget;
+    const budget = stableValue(
+      call.budget || callNode?.budget || targetDefinition?.budget || {},
+    );
+    for (const field of BUDGET_FIELDS) {
+      const required = Number(targetBudget?.[field] || 0);
+      const cap = budget[field];
+      if (required > 0 && (cap == null || Number(cap) < required)) {
+        diagnostic(
+          diagnostics,
+          "GRAPH_SUBGRAPH_BUDGET_SLICE_TOO_SMALL",
+          `#/subgraphCalls/${index}/budget/${field}`,
+          `subgraph ${field} budget slice ${cap ?? "unbounded"} is below the child upper bound ${required}`,
+          { field, required, cap: cap ?? null },
+        );
+      }
+    }
+    calls.set(call.nodeId, { ...call, budget });
+  }
+  for (const [index, node] of definition.nodes.entries()) {
+    if (node.kind === "subgraph" && !calls.has(node.id)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_SUBGRAPH_CALL_REQUIRED",
+        `#/nodes/${index}`,
+        `subgraph node requires a pinned SubgraphCall: ${node.id}`,
+      );
+    }
   }
 
   const definitions = new Map();
@@ -411,15 +724,51 @@ function validateSubgraphs(definition, nodeIds, options, diagnostics) {
     visited.add(id);
   };
   visit(definition.id);
-  return calls;
+  return { calls, definitions: registryDefinitions };
+}
+
+function upcastGraphDefinitionV0(input) {
+  const definition = stableValue(input);
+  return {
+    schemaVersion: 1,
+    id: definition.id,
+    revision: definition.revision ?? 1,
+    triggers: definition.triggers || [],
+    regions: definition.regions || [],
+    nodes: (definition.nodes || []).map((node) => ({
+      ...node,
+      kind: node.kind || "task",
+      dependsOn: node.dependsOn || [],
+      inputs: node.inputs || [],
+      outputs: node.outputs || [],
+      effectClass: node.effectClass || "none",
+    })),
+    edges: (definition.edges || []).map((edge, index) => ({
+      ...edge,
+      id: edge.id || `edge-${index + 1}`,
+      kind: edge.kind || "control",
+      when: edge.when || "success",
+    })),
+    loops: definition.loops || [],
+    subgraphCalls: definition.subgraphCalls || [],
+    budget: definition.budget || {},
+    allowedCapabilities: definition.allowedCapabilities || [],
+    metadata: definition.metadata || {},
+  };
 }
 
+const BUILTIN_GRAPH_UPCASTERS = Object.freeze({
+  0: upcastGraphDefinitionV0,
+});
+
 function migrateDefinition(input, options) {
   const sourceVersion = Number(input?.schemaVersion);
   if (sourceVersion === GRAPH_DEFINITION_VERSION) {
     return { definition: stableValue(input), migratedFrom: null };
   }
-  const upcaster = options.upcasters?.[sourceVersion];
+  const upcaster =
+    options.upcasters?.[sourceVersion] ||
+    BUILTIN_GRAPH_UPCASTERS[sourceVersion];
   if (
     sourceVersion === GRAPH_DEFINITION_VERSION - 1 &&
     typeof upcaster === "function"
@@ -518,6 +867,118 @@ export function compileGraphDefinition(input, options = {}) {
   }
   const nodes = new Map(definition.nodes.map((node) => [node.id, node]));
   const nodeIds = new Set(nodes.keys());
+  const compensationTargets = new Map();
+  const declareCompensation = (sourceId, targetId) => {
+    if (!sourceId || !targetId) return;
+    const targets = compensationTargets.get(sourceId) || new Set();
+    targets.add(targetId);
+    compensationTargets.set(sourceId, targets);
+  };
+  for (const node of definition.nodes) {
+    if (node.compensationNodeId) {
+      declareCompensation(node.id, node.compensationNodeId);
+    }
+  }
+  for (const edge of definition.edges) {
+    if (edge.kind === "compensation") {
+      declareCompensation(edge.from, edge.to);
+    }
+  }
+  const compensationByNode = new Map();
+  const compensationOwners = new Map();
+  for (const [sourceId, targets] of compensationTargets) {
+    if (targets.size !== 1) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_TARGET_CONFLICT",
+        "#/nodes",
+        `effect node declares multiple compensation targets: ${sourceId}`,
+        { sourceId, targetIds: [...targets].sort() },
+      );
+      continue;
+    }
+    const [targetId] = targets;
+    const source = nodes.get(sourceId);
+    const target = nodes.get(targetId);
+    if (!target) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_UNKNOWN_COMPENSATION_TARGET",
+        "#/nodes",
+        `unknown compensation target ${targetId} for ${sourceId}`,
+        { sourceId, targetId },
+      );
+    }
+    if (!source || !target) continue;
+    if (sourceId === targetId) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_SELF_REFERENCE",
+        "#/nodes",
+        `node cannot compensate itself: ${sourceId}`,
+      );
+    }
+    if (!["workspace_write", "external"].includes(source.effectClass)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_SOURCE_NOT_EFFECTFUL",
+        "#/nodes",
+        `compensation source must be effectful: ${sourceId}`,
+      );
+    }
+    if (!["workspace_write", "external"].includes(target.effectClass)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_TARGET_NOT_EFFECTFUL",
+        "#/nodes",
+        `compensation target must be effectful: ${targetId}`,
+      );
+    }
+    const priorOwner = compensationOwners.get(targetId);
+    if (priorOwner && priorOwner !== sourceId) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_TARGET_REUSED",
+        "#/nodes",
+        `compensation target ${targetId} is already owned by ${priorOwner}`,
+      );
+    } else {
+      compensationOwners.set(targetId, sourceId);
+      compensationByNode.set(sourceId, targetId);
+    }
+  }
+  const compensationNodeIds = new Set(compensationOwners.keys());
+  for (const targetId of compensationNodeIds) {
+    const target = nodes.get(targetId);
+    const usedAsForwardDependency = definition.nodes.some((node) =>
+      node.dependsOn.includes(targetId),
+    );
+    const usedByForwardEdge = definition.edges.some(
+      (edge) =>
+        edge.kind !== "compensation" &&
+        (edge.from === targetId || edge.to === targetId),
+    );
+    if (
+      target.dependsOn.length > 0 ||
+      usedAsForwardDependency ||
+      usedByForwardEdge
+    ) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_TARGET_IN_FORWARD_GRAPH",
+        "#/nodes",
+        `compensation target must be isolated from the forward dependency graph: ${targetId}`,
+      );
+    }
+    if (compensationTargets.has(targetId)) {
+      diagnostic(
+        diagnostics,
+        "GRAPH_COMPENSATION_RECURSIVE",
+        "#/nodes",
+        `compensation target cannot declare another compensation target: ${targetId}`,
+      );
+    }
+  }
   for (const [index, trigger] of (definition.triggers || []).entries()) {
     if (!nodeIds.has(trigger.targetNodeId)) {
       diagnostic(
@@ -761,6 +1222,7 @@ export function compileGraphDefinition(input, options = {}) {
 
   for (let leftIndex = 0; leftIndex < definition.nodes.length; leftIndex += 1) {
     const left = definition.nodes[leftIndex];
+    if (compensationNodeIds.has(left.id)) continue;
     if (!["workspace_write", "external"].includes(left.effectClass)) continue;
     for (
       let rightIndex = leftIndex + 1;
@@ -768,6 +1230,7 @@ export function compileGraphDefinition(input, options = {}) {
       rightIndex += 1
     ) {
       const right = definition.nodes[rightIndex];
+      if (compensationNodeIds.has(right.id)) continue;
       if (!["workspace_write", "external"].includes(right.effectClass))
         continue;
       if (
@@ -803,14 +1266,26 @@ export function compileGraphDefinition(input, options = {}) {
     }
   }
 
-  const multiplier = loopMultipliers(definition, diagnostics, nodeIds);
-  const budget = budgetUpperBound(definition, multiplier, diagnostics);
-  const subgraphCalls = validateSubgraphs(
+  const multiplier = loopMultipliers(
+    definition,
+    diagnostics,
+    nodeIds,
+    nodes,
+    dependencies,
+    compensationByNode,
+  );
+  const subgraphs = validateSubgraphs(
     definition,
     nodeIds,
     options,
     diagnostics,
   );
+  const budget = budgetUpperBound(
+    definition,
+    multiplier,
+    diagnostics,
+    subgraphs.calls,
+  );
   if (diagnostics.length) throw new GraphCompileError(diagnostics);
 
   const revisionDigest = graphDigest(
@@ -829,6 +1304,11 @@ export function compileGraphDefinition(input, options = {}) {
       Object.fromEntries([...nodes].map(([id, value]) => [id, value])),
     ),
     topologicalOrder: Object.freeze(order),
+    forwardTopologicalOrder: Object.freeze(
+      order.filter((nodeId) => !compensationNodeIds.has(nodeId)),
+    ),
+    compensationByNode: deepFreeze(Object.fromEntries(compensationByNode)),
+    compensationNodeIds: Object.freeze([...compensationNodeIds].sort()),
     dependencies: deepFreeze(
       Object.fromEntries(
         [...dependencies].map(([id, values]) => [id, [...values].sort()]),
@@ -853,8 +1333,24 @@ export function compileGraphDefinition(input, options = {}) {
       ),
     ),
     loopMultipliers: deepFreeze(Object.fromEntries(multiplier)),
+    loops: deepFreeze(
+      Object.fromEntries(definition.loops.map((loop) => [loop.id, loop])),
+    ),
+    loopByNode: deepFreeze(
+      Object.fromEntries(
+        definition.loops.flatMap((loop) =>
+          loop.nodeIds.map((nodeId) => [nodeId, loop.id]),
+        ),
+      ),
+    ),
+    loopByExitNode: deepFreeze(
+      Object.fromEntries(
+        definition.loops.map((loop) => [loop.exitNodeId, loop.id]),
+      ),
+    ),
     budgetUpperBound: deepFreeze(budget),
-    subgraphCalls: deepFreeze(Object.fromEntries(subgraphCalls)),
+    subgraphCalls: deepFreeze(Object.fromEntries(subgraphs.calls)),
+    subgraphDefinitions: deepFreeze(Object.fromEntries(subgraphs.definitions)),
     triggers: deepFreeze([...(definition.triggers || [])]),
     regions: deepFreeze([...(definition.regions || [])]),
   };
@@ -882,6 +1378,8 @@ export function assertCompiledGraph(value) {
 export function migrateGraphDefinition(input, options = {}) {
   const { definition, migratedFrom } = migrateDefinition(input, options);
   const compiled = compileGraphDefinition(definition, options);
+  const backupDefinition =
+    migratedFrom == null ? null : deepFreeze(stableValue(input));
   return Object.freeze({
     dryRun: options.dryRun !== false,
     fromVersion: migratedFrom ?? definition.schemaVersion,
@@ -889,9 +1387,39 @@ export function migrateGraphDefinition(input, options = {}) {
     definition: compiled.definition,
     revisionDigest: compiled.revisionDigest,
     backupRequired: migratedFrom != null,
+    backupDefinition,
+    rollbackDigest:
+      backupDefinition == null
+        ? null
+        : graphDigest(
+            backupDefinition,
+            `cc.graph.definition-backup/${migratedFrom}`,
+          ),
   });
 }
 
+export function restoreGraphDefinitionBackup(
+  backupDefinition,
+  expectedRollbackDigest,
+) {
+  const backup = stableValue(backupDefinition);
+  const version = Number(backup.schemaVersion);
+  if (version !== GRAPH_DEFINITION_VERSION - 1) {
+    const error = new TypeError(
+      `backup must use GraphDefinition version ${GRAPH_DEFINITION_VERSION - 1}`,
+    );
+    error.code = "CC_GRAPH_MIGRATION_BACKUP_INVALID";
+    throw error;
+  }
+  const digest = graphDigest(backup, `cc.graph.definition-backup/${version}`);
+  if (digest !== expectedRollbackDigest) {
+    const error = new TypeError("graph migration backup digest does not match");
+    error.code = "CC_GRAPH_MIGRATION_BACKUP_TAMPERED";
+    throw error;
+  }
+  return deepFreeze(backup);
+}
+
 export function executionAttemptId(nodeId, iterationPath = [], attempt = 1) {
   if (!Number.isSafeInteger(attempt) || attempt < 1) {
     throw new TypeError("attempt must be a positive integer");
@@ -907,5 +1435,9 @@ export function executionAttemptId(nodeId, iterationPath = [], attempt = 1) {
         return number;
       })
     : [];
-  return `${nodeId}@${path.length ? path.join(".") : "root"}#${attempt}`;
+  const digest = graphDigest(
+    { nodeId: String(nodeId), iterationPath: path, attempt },
+    "cc.graph.execution-attempt/v1",
+  );
+  return `attempt-${digest.slice(7, 47)}`;
 }