chainlesschain 0.166.0 → 0.166.2

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import {
   assertCompiledGraph,
   compileGraphDefinition,
+  executionAttemptId,
   graphDigest,
   writeScopesOverlap,
 } from "./compiler.js";
@@ -77,6 +78,13 @@ const TRUST_RANK = Object.freeze({
   authenticated_user: 2,
   trusted_host: 3,
 });
+const BUDGET_FIELDS = Object.freeze([
+  "turns",
+  "tokens",
+  "costUsd",
+  "wallMs",
+  "spawnCount",
+]);
 
 function kernelError(code, message, details = {}) {
   const error = new Error(message);
@@ -98,6 +106,95 @@ function mapRestore(entries) {
   return new Map((entries || []).map(([key, value]) => [key, clone(value)]));
 }
 
+function emptyBudgetUsage() {
+  return Object.fromEntries(BUDGET_FIELDS.map((field) => [field, 0]));
+}
+
+function budgetValue(budget, field) {
+  return Number(budget?.[field] || 0);
+}
+
+function persistedSubgraphRegistry(definitions = {}) {
+  return new Map(
+    Object.entries(definitions).map(([id, definition]) => [
+      id,
+      {
+        definition,
+        revisionDigest: graphDigest(
+          definition,
+          `cc.graph.definition/${definition.schemaVersion}`,
+        ),
+      },
+    ]),
+  );
+}
+
+function idleCompensationState() {
+  return {
+    status: "idle",
+    triggerNodeId: null,
+    reason: null,
+    terminalStatus: null,
+    plan: [],
+    currentIndex: 0,
+    completedNodeIds: [],
+    completedEntries: [],
+    failure: null,
+    startedAt: null,
+    completedAt: null,
+  };
+}
+
+function iterationFrameId(runId, regionId, iterationPath) {
+  const digest = graphDigest(
+    { runId, regionId, iterationPath },
+    "cc.graph.iteration-frame/v1",
+  );
+  return `iteration-${digest.slice(7, 39)}`;
+}
+
+function deterministicSubgraphRunId(parentRunId, nodeId, revisionDigest) {
+  const digest = graphDigest(
+    { parentRunId, nodeId, revisionDigest },
+    "cc.graph.subgraph-run/v1",
+  );
+  return `subgraph-${digest.slice(7, 39)}`;
+}
+
+export function iterationEffectIdempotencyKey(
+  baseIdempotencyKey,
+  iterationPath = [],
+) {
+  const base = String(baseIdempotencyKey || "").trim();
+  if (!base) {
+    throw kernelError(
+      "CC_GRAPH_EFFECT_IDEMPOTENCY_REQUIRED",
+      "effect idempotency key is required",
+    );
+  }
+  if (!Array.isArray(iterationPath)) {
+    throw kernelError(
+      "CC_GRAPH_INVALID_ARGUMENT",
+      "iterationPath must be an array",
+    );
+  }
+  const path = iterationPath.map((value) => {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 0) {
+      throw kernelError(
+        "CC_GRAPH_INVALID_ARGUMENT",
+        "iterationPath must contain non-negative integers",
+      );
+    }
+    return number;
+  });
+  if (path.length === 0) return base;
+  return graphDigest(
+    { baseIdempotencyKey: base, iterationPath: path },
+    "cc.graph.iteration-effect-idempotency/v1",
+  );
+}
+
 function finitePositive(value, fallback) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? number : fallback;
@@ -254,6 +351,7 @@ function stateSnapshot(run) {
     version: 1,
     id: run.id,
     definition: run.compiled.definition,
+    subgraphDefinitions: run.compiled.subgraphDefinitions,
     phase: run.phase,
     status: run.status,
     graphRevision: run.graphRevision,
@@ -262,10 +360,19 @@ function stateSnapshot(run) {
     authorityDigest: run.authorityDigest,
     budget: run.budget,
     budgetUsed: run.budgetUsed,
+    budgetReserved: run.budgetReserved,
     createdAt: run.createdAt,
     completedAt: run.completedAt,
     cancellationRequested: run.cancellationRequested,
     progressEpoch: run.progressEpoch,
+    compensation: clone(run.compensation),
+    parentRunRef: clone(run.parentRunRef),
+    subgraphDepth: run.subgraphDepth,
+    definitionPath: clone(run.definitionPath),
+    loopStates: mapSnapshot(run.loopStates),
+    iterationFrames: mapSnapshot(run.iterationFrames),
+    loopDecisionCache: mapSnapshot(run.loopDecisionCache),
+    subgraphRuns: mapSnapshot(run.subgraphRuns),
     nodeStates: mapSnapshot(run.nodeStates),
     attempts: mapSnapshot(run.attempts),
     agents: mapSnapshot(run.agents),
@@ -285,7 +392,12 @@ function stateSnapshot(run) {
 }
 
 function restoreState(run, snapshot, compiled = null) {
-  run.compiled = compiled || compileGraphDefinition(snapshot.definition);
+  run.compiled =
+    compiled ||
+    compileGraphDefinition(snapshot.definition, {
+      subgraphs: persistedSubgraphRegistry(snapshot.subgraphDefinitions),
+      allowUnresolvedSubgraphs: snapshot.subgraphDefinitions == null,
+    });
   run.phase = snapshot.phase;
   run.status = snapshot.status;
   run.graphRevision = snapshot.graphRevision;
@@ -294,11 +406,23 @@ function restoreState(run, snapshot, compiled = null) {
   run.authorityDigest = snapshot.authorityDigest;
   run.budget = clone(snapshot.budget);
   run.budgetUsed = clone(snapshot.budgetUsed);
+  run.budgetReserved = clone(snapshot.budgetReserved || emptyBudgetUsage());
   run.createdAt = snapshot.createdAt;
   run.completedAt = snapshot.completedAt;
   run.cancellationRequested = snapshot.cancellationRequested === true;
   run.progressEpoch = snapshot.progressEpoch;
+  run.compensation = clone(snapshot.compensation || idleCompensationState());
+  run.compensation.completedEntries ||= [];
+  run.parentRunRef = clone(snapshot.parentRunRef || null);
+  run.subgraphDepth = Number(snapshot.subgraphDepth || 0);
+  run.definitionPath = clone(
+    snapshot.definitionPath || [run.compiled.definitionId],
+  );
   for (const field of [
+    "loopStates",
+    "iterationFrames",
+    "loopDecisionCache",
+    "subgraphRuns",
     "nodeStates",
     "attempts",
     "agents",
@@ -328,6 +452,7 @@ function nodeProjection(run, nodeId) {
     attemptIds: Object.freeze([...state.attemptIds]),
     acceptedAttemptId: state.acceptedAttemptId,
     blockedRoot: state.blockedRoot,
+    iterationPath: Object.freeze([...(state.iterationPath || [])]),
     createdAt: state.createdAt,
     updatedAt: state.updatedAt,
   });
@@ -350,9 +475,33 @@ function runProjection(run) {
     authorityDigest: run.authorityDigest,
     budget: clone(run.budget),
     budgetUsed: clone(run.budgetUsed),
+    budgetReserved: clone(run.budgetReserved),
     createdAt: run.createdAt,
     completedAt: run.completedAt,
     progressEpoch: run.progressEpoch,
+    compensation: Object.freeze(clone(run.compensation)),
+    parentRunRef: Object.freeze(clone(run.parentRunRef)),
+    subgraphDepth: run.subgraphDepth,
+    definitionPath: Object.freeze([...run.definitionPath]),
+    loops: Object.freeze(
+      [...run.loopStates.values()]
+        .sort((left, right) => left.regionId.localeCompare(right.regionId))
+        .map((state) => Object.freeze(clone(state))),
+    ),
+    iterationFrames: Object.freeze(
+      [...run.iterationFrames.values()]
+        .sort((left, right) =>
+          left.iterationPath
+            .join(".")
+            .localeCompare(right.iterationPath.join(".")),
+        )
+        .map((frame) => Object.freeze(clone(frame))),
+    ),
+    subgraphRuns: Object.freeze(
+      [...run.subgraphRuns.values()]
+        .sort((left, right) => left.nodeId.localeCompare(right.nodeId))
+        .map((relation) => Object.freeze(clone(relation))),
+    ),
     nodes: Object.freeze(
       run.compiled.topologicalOrder.map((id) => nodeProjection(run, id)),
     ),
@@ -399,17 +548,20 @@ function buildRun(compiled, options, now) {
         "cc.graph.authority/v1",
       ),
     budget: clone(options.budget || compiled.definition.budget || {}),
-    budgetUsed: {
-      turns: 0,
-      tokens: 0,
-      costUsd: 0,
-      wallMs: 0,
-      spawnCount: 0,
-    },
+    budgetUsed: emptyBudgetUsage(),
+    budgetReserved: emptyBudgetUsage(),
     createdAt,
     completedAt: null,
     cancellationRequested: false,
     progressEpoch: 0,
+    compensation: idleCompensationState(),
+    parentRunRef: clone(options.parentRunRef || null),
+    subgraphDepth: Number(options.subgraphDepth || 0),
+    definitionPath: clone(options.definitionPath || [compiled.definitionId]),
+    loopStates: new Map(),
+    iterationFrames: new Map(),
+    loopDecisionCache: new Map(),
+    subgraphRuns: new Map(),
     nodeStates: new Map(),
     attempts: new Map(),
     agents: new Map(),
@@ -427,12 +579,41 @@ function buildRun(compiled, options, now) {
     fenceCounters: new Map(),
     lastEvent: null,
   };
+  for (const loop of compiled.definition.loops || []) {
+    const iterationPath = [0];
+    const frameId = iterationFrameId(run.id, loop.id, iterationPath);
+    run.loopStates.set(loop.id, {
+      regionId: loop.id,
+      status: "active",
+      iteration: 0,
+      iterationPath,
+      frameId,
+      maxIterations: loop.maxIterations,
+      condition: loop.condition || null,
+      conditionEvidenceDigest: null,
+    });
+    run.iterationFrames.set(frameId, {
+      id: frameId,
+      runId: run.id,
+      regionId: loop.id,
+      parentFrameId: null,
+      iterationPath,
+      status: "active",
+      startedAt: createdAt,
+      completedAt: null,
+    });
+  }
+  const compensationNodeIds = new Set(compiled.compensationNodeIds || []);
   for (const nodeId of compiled.topologicalOrder) {
+    const loopId = compiled.loopByNode?.[nodeId];
     run.nodeStates.set(nodeId, {
-      status: "pending",
+      status: compensationNodeIds.has(nodeId) ? "skipped" : "pending",
       attemptIds: [],
       acceptedAttemptId: null,
       blockedRoot: null,
+      iterationPath: loopId
+        ? [...run.loopStates.get(loopId).iterationPath]
+        : [],
       createdAt,
       updatedAt: createdAt,
     });
@@ -447,7 +628,7 @@ function eventDetails(value) {
 }
 
 function checkBudget(run, usage) {
-  for (const field of ["turns", "tokens", "costUsd", "wallMs", "spawnCount"]) {
+  for (const field of BUDGET_FIELDS) {
     const delta = Number(usage?.[field] || 0);
     if (!Number.isFinite(delta) || delta < 0) {
       throw kernelError(
@@ -456,11 +637,18 @@ function checkBudget(run, usage) {
       );
     }
     const cap = run.budget?.[field];
-    if (cap != null && run.budgetUsed[field] + delta > cap) {
+    const reserved = budgetValue(run.budgetReserved, field);
+    if (cap != null && run.budgetUsed[field] + reserved + delta > cap) {
       throw kernelError(
         "CC_GRAPH_BUDGET_EXHAUSTED",
         `GraphRun ${field} budget would be exceeded`,
-        { field, cap, used: run.budgetUsed[field], requested: delta },
+        {
+          field,
+          cap,
+          used: run.budgetUsed[field],
+          reserved,
+          requested: delta,
+        },
       );
     }
   }
@@ -468,18 +656,92 @@ function checkBudget(run, usage) {
 
 function addUsage(run, usage) {
   checkBudget(run, usage);
-  for (const field of Object.keys(run.budgetUsed)) {
+  for (const field of BUDGET_FIELDS) {
     run.budgetUsed[field] += Number(usage?.[field] || 0);
   }
 }
 
+function reserveBudget(run, budget) {
+  checkBudget(run, budget);
+  for (const field of BUDGET_FIELDS) {
+    run.budgetReserved[field] += budgetValue(budget, field);
+  }
+}
+
+function settleSubgraphBudget(run, relation, usage) {
+  if (relation.budgetSettled === true) return;
+  for (const field of BUDGET_FIELDS) {
+    const reserved = budgetValue(relation.budgetSlice, field);
+    const actual = budgetValue(usage, field);
+    if (actual > reserved) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_BUDGET_INVARIANT",
+        `child ${field} usage exceeds its reserved budget slice`,
+        { field, reserved, actual, childRunId: relation.childRunId },
+      );
+    }
+    run.budgetReserved[field] = Math.max(
+      0,
+      budgetValue(run.budgetReserved, field) - reserved,
+    );
+  }
+  addUsage(run, usage);
+  relation.budgetUsed = Object.fromEntries(
+    BUDGET_FIELDS.map((field) => [field, budgetValue(usage, field)]),
+  );
+  relation.budgetSettled = true;
+}
+
+function effectiveDependencyStatus(run, dependency) {
+  const status = run.nodeStates.get(dependency).status;
+  const loopId = run.compiled.loopByExitNode?.[dependency];
+  const loopState = loopId ? run.loopStates.get(loopId) : null;
+  if (loopState && ["active", "waiting_condition"].includes(loopState.status)) {
+    return "running";
+  }
+  if (loopState?.status === "failed") return "failed";
+  if (loopState?.status === "cancelled") return "cancelled";
+  if (loopState?.status === "exhausted") return "budget_exhausted";
+  return status;
+}
+
+function refreshLoopStates(run, now) {
+  let changed = false;
+  for (const loop of run.compiled.definition.loops || []) {
+    const loopState = run.loopStates.get(loop.id);
+    if (!loopState || loopState.status !== "active") continue;
+    const statuses = loop.nodeIds.map(
+      (nodeId) => run.nodeStates.get(nodeId).status,
+    );
+    const failure = statuses.find((status) => FAILURE_NODE.has(status));
+    const cancelled = statuses.find((status) => status === "cancelled");
+    const frame = run.iterationFrames.get(loopState.frameId);
+    if (failure || cancelled) {
+      loopState.status = failure ? "failed" : "cancelled";
+      if (frame) {
+        frame.status = failure ? "failed" : "cancelled";
+        frame.completedAt = nowIso(now);
+      }
+      changed = true;
+    } else if (statuses.every((status) => status === "succeeded")) {
+      loopState.status = "waiting_condition";
+      if (frame) {
+        frame.status = "succeeded";
+        frame.completedAt = nowIso(now);
+      }
+      changed = true;
+    }
+  }
+  return changed;
+}
+
 function nodeReadiness(run, nodeId) {
   const node = run.compiled.nodes[nodeId];
   const dependencies = run.compiled.dependencies[nodeId] || [];
   if (!dependencies.length) return { ready: true };
   const policies = run.compiled.dependencyPolicies[nodeId] || {};
   const observations = dependencies.map((dependency) => {
-    const status = run.nodeStates.get(dependency).status;
+    const status = effectiveDependencyStatus(run, dependency);
     const policy = policies[dependency] || "success";
     return {
       dependency,
@@ -702,6 +964,121 @@ function waitGraphCycles(run) {
   return components.sort((left, right) => left[0].localeCompare(right[0]));
 }
 
+function currentCompensationEntry(run) {
+  if (run.compensation?.status !== "running") return null;
+  return run.compensation.plan[run.compensation.currentIndex] || null;
+}
+
+function compensationAssignment(run, nodeId) {
+  const entry = currentCompensationEntry(run);
+  return entry?.compensationNodeId === nodeId ? entry : null;
+}
+
+function sameIterationPath(left, right) {
+  return JSON.stringify(left || []) === JSON.stringify(right || []);
+}
+
+function compareIterationPath(left, right) {
+  const a = left || [];
+  const b = right || [];
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] == null) return -1;
+    if (b[index] == null) return 1;
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return 0;
+}
+
+function committedEffectsForNode(run, nodeId, iterationPath = null) {
+  return [...run.effects.values()]
+    .filter(
+      (effect) =>
+        effect.nodeId === nodeId &&
+        effect.status === "committed" &&
+        (iterationPath == null ||
+          sameIterationPath(effect.iterationPath, iterationPath)),
+    )
+    .sort(
+      (left, right) =>
+        compareIterationPath(left.iterationPath, right.iterationPath) ||
+        left.createdAt.localeCompare(right.createdAt) ||
+        left.id.localeCompare(right.id),
+    );
+}
+
+function completeCompensationStep(run, entry, now) {
+  const compensationEffects = committedEffectsForNode(
+    run,
+    entry.compensationNodeId,
+    entry.iterationPath,
+  );
+  if (compensationEffects.length === 0) {
+    throw kernelError(
+      "CC_GRAPH_COMPENSATION_RECEIPT_REQUIRED",
+      `compensation node requires a committed effect receipt: ${entry.compensationNodeId}`,
+    );
+  }
+  const compensationEffect = compensationEffects.at(-1);
+  const sourceEffects = entry.effectIds.map((effectId) =>
+    run.effects.get(effectId),
+  );
+  if (
+    sourceEffects.some(
+      (effect) =>
+        !effect ||
+        effect.status !== "committed" ||
+        !sameIterationPath(effect.iterationPath, entry.iterationPath),
+    )
+  ) {
+    throw kernelError(
+      "CC_GRAPH_COMPENSATION_SOURCE_RECEIPT_INVALID",
+      `compensation source receipts changed for ${entry.nodeId}`,
+    );
+  }
+  for (const effect of sourceEffects) {
+    effect.status = "compensated";
+    effect.compensationEffectId = compensationEffect.id;
+    effect.updatedAt = nowIso(() => now);
+  }
+  run.compensation.completedNodeIds.push(entry.nodeId);
+  run.compensation.completedEntries.push({
+    nodeId: entry.nodeId,
+    iterationPath: [...entry.iterationPath],
+    effectIds: [...entry.effectIds],
+    compensationEffectId: compensationEffect.id,
+  });
+  run.compensation.currentIndex += 1;
+  if (run.compensation.currentIndex >= run.compensation.plan.length) {
+    run.compensation.status = "completed";
+    run.compensation.completedAt = nowIso(() => now);
+    run.status = run.compensation.terminalStatus;
+    run.completedAt = nowIso(() => now);
+  } else {
+    const next = run.compensation.plan[run.compensation.currentIndex];
+    const state = run.nodeStates.get(next.compensationNodeId);
+    state.status = "pending";
+    state.acceptedAttemptId = null;
+    state.blockedRoot = null;
+    state.iterationPath = [...next.iterationPath];
+    state.updatedAt = nowIso(() => now);
+    run.status = "running";
+  }
+}
+
+function failCompensation(run, entry, error, now) {
+  run.compensation.status = "failed";
+  run.compensation.failure = {
+    nodeId: entry.nodeId,
+    compensationNodeId: entry.compensationNodeId,
+    iterationPath: [...entry.iterationPath],
+    effectIds: [...entry.effectIds],
+    error: String(error || "compensation_failed").slice(0, 4096),
+  };
+  run.compensation.completedAt = nowIso(() => now);
+  run.status = "reconciliation_required";
+  run.completedAt = null;
+}
+
 function terminalAlgebra(run) {
   const statuses = [...run.nodeStates.values()].map((state) => state.status);
   const successes = statuses.filter((status) => status === "succeeded").length;
@@ -719,6 +1096,12 @@ function terminalAlgebra(run) {
 }
 
 function classifyQuiescence(run, now) {
+  if (run.compensation?.status === "failed") {
+    return "reconciliation_required";
+  }
+  if (run.compensation?.status === "completed") {
+    return run.compensation.terminalStatus || "failed";
+  }
   if (TERMINAL_RUN.has(run.status)) return run.status;
   if (run.phase === "open") return "running";
   if (
@@ -762,6 +1145,16 @@ function classifyQuiescence(run, now) {
   ) {
     return "waiting_external";
   }
+  if (
+    [...run.loopStates.values()].some(
+      (loopState) => loopState.status === "waiting_condition",
+    ) ||
+    [...run.subgraphRuns.values()].some((relation) =>
+      ["starting", "running"].includes(relation.status),
+    )
+  ) {
+    return "waiting_external";
+  }
   const cycles = waitGraphCycles(run);
   if (cycles.length) return "deadlocked";
   const pending = [...run.nodeStates.entries()].filter(
@@ -819,6 +1212,20 @@ export class GraphKernel {
     return run;
   }
 
+  _loadRun(runId) {
+    const id = safeIdentifier(runId, "runId");
+    if (this.runs.has(id)) return this.runs.get(id);
+    try {
+      if (this.eventStore.read(id).length > 0) {
+        this.recoverRun(id);
+        return this.runs.get(id);
+      }
+    } catch (error) {
+      if (error?.code !== "CC_ROLLOUT_THREAD_NOT_FOUND") throw error;
+    }
+    return null;
+  }
+
   _transaction(run, type, details, mutator, options = {}) {
     if (TERMINAL_RUN.has(run.status) && options.allowTerminal !== true) {
       throw kernelError(
@@ -884,6 +1291,9 @@ export class GraphKernel {
           definitionId: compiled.definitionId,
           revisionDigest: compiled.revisionDigest,
           occurrenceRef: occurrence,
+          parentRunRef: run.parentRunRef,
+          subgraphDepth: run.subgraphDepth,
+          definitionPath: run.definitionPath,
         },
         () => {},
         { idempotencyKey: `run-start:${run.id}` },
@@ -1129,19 +1539,72 @@ export class GraphKernel {
             ...clone(subgraphCalls),
           ],
         };
-        const compiled = compileGraphDefinition(definition);
+        const compiled = compileGraphDefinition(definition, {
+          subgraphs: persistedSubgraphRegistry(
+            run.compiled.subgraphDefinitions,
+          ),
+        });
         const createdAt = nowIso(() => now);
+        const compensationNodeIds = new Set(compiled.compensationNodeIds || []);
+        const addedNodeIds = new Set(nodes.map((node) => node.id));
+        for (const loop of loops) {
+          if (loop.nodeIds.some((nodeId) => !addedNodeIds.has(nodeId))) {
+            throw kernelError(
+              "CC_GRAPH_DYNAMIC_LOOP_BOUNDARY",
+              "a dynamic loop must be added atomically with all of its nodes",
+              { loopId: loop.id },
+            );
+          }
+          const iterationPath = [0];
+          const frameId = iterationFrameId(run.id, loop.id, iterationPath);
+          run.loopStates.set(loop.id, {
+            regionId: loop.id,
+            status: "active",
+            iteration: 0,
+            iterationPath,
+            frameId,
+            maxIterations: loop.maxIterations,
+            condition: loop.condition || null,
+            conditionEvidenceDigest: null,
+          });
+          run.iterationFrames.set(frameId, {
+            id: frameId,
+            runId: run.id,
+            regionId: loop.id,
+            parentFrameId: null,
+            iterationPath,
+            status: "active",
+            startedAt: createdAt,
+            completedAt: null,
+          });
+        }
         for (const node of nodes) {
+          const loopId = compiled.loopByNode?.[node.id];
           run.nodeStates.set(node.id, {
-            status: "pending",
+            status: compensationNodeIds.has(node.id) ? "skipped" : "pending",
             attemptIds: [],
             acceptedAttemptId: null,
             blockedRoot: null,
+            iterationPath: loopId
+              ? [...run.loopStates.get(loopId).iterationPath]
+              : [],
             createdAt,
             updatedAt: createdAt,
           });
           run.fenceCounters.set(node.id, 0);
         }
+        for (const compensationNodeId of compensationNodeIds) {
+          const state = run.nodeStates.get(compensationNodeId);
+          if (!state || state.status === "skipped") continue;
+          if (state.status !== "pending" || state.attemptIds.length > 0) {
+            throw kernelError(
+              "CC_GRAPH_COMPENSATION_TARGET_ACTIVE",
+              `dynamic revision cannot convert an active node into a compensation target: ${compensationNodeId}`,
+            );
+          }
+          state.status = "skipped";
+          state.updatedAt = createdAt;
+        }
         run.compiled = compiled;
         run.graphRevision += 1;
         run.revisionDigest = compiled.revisionDigest;
@@ -1179,6 +1642,7 @@ export class GraphKernel {
         }
         run.phase = "sealed";
         propagate(run, () => now);
+        if (refreshLoopStates(run, () => now)) propagate(run, () => now);
         run.status = classifyQuiescence(run, now);
         if (TERMINAL_RUN.has(run.status)) run.completedAt = nowIso(() => now);
         return runProjection(run);
@@ -1193,15 +1657,423 @@ export class GraphKernel {
       const now = this.now();
       sweepExpirations(run, now);
       propagate(run, () => now);
+      if (refreshLoopStates(run, () => now)) propagate(run, () => now);
       run.status = classifyQuiescence(run, now);
       if (TERMINAL_RUN.has(run.status)) run.completedAt ||= nowIso(() => now);
       return runProjection(run);
     });
   }
 
+  advanceLoop(
+    runId,
+    { regionId, continueLoop, conditionEvidenceDigest, requestId = null } = {},
+  ) {
+    const run = this._run(runId);
+    const safeRegionId = safeIdentifier(regionId, "regionId");
+    const evidenceDigest = String(conditionEvidenceDigest || "");
+    if (!/^sha256:[a-f0-9]{64}$/u.test(evidenceDigest)) {
+      throw kernelError(
+        "CC_GRAPH_LOOP_EVIDENCE_REQUIRED",
+        "loop advancement requires a sha256 condition evidence digest",
+      );
+    }
+    if (typeof continueLoop !== "boolean") {
+      throw kernelError(
+        "CC_GRAPH_LOOP_DECISION_INVALID",
+        "continueLoop must be a boolean",
+      );
+    }
+    const loop = run.compiled.loops?.[safeRegionId];
+    const loopState = run.loopStates.get(safeRegionId);
+    if (!loop || !loopState) {
+      throw kernelError(
+        "CC_GRAPH_LOOP_NOT_FOUND",
+        `loop region not found: ${safeRegionId}`,
+      );
+    }
+    if (requestId == null) {
+      throw kernelError(
+        "CC_GRAPH_LOOP_REQUEST_ID_REQUIRED",
+        "loop advancement requires a stable requestId for crash-safe replay",
+      );
+    }
+    const decisionKey = safeIdentifier(requestId, "requestId");
+    const decisionDigest = graphDigest(
+      {
+        regionId: safeRegionId,
+        continueLoop,
+        conditionEvidenceDigest: evidenceDigest,
+      },
+      "cc.graph.loop-decision/v1",
+    );
+    const replay = run.loopDecisionCache.get(decisionKey);
+    if (replay) {
+      if (replay.digest !== decisionDigest) {
+        throw kernelError(
+          "CC_GRAPH_REQUEST_ID_CONFLICT",
+          "loop requestId was reused with a different decision",
+        );
+      }
+      return runProjection(run);
+    }
+    this._transaction(
+      run,
+      continueLoop ? "loop.continued" : "loop.exited",
+      {
+        regionId: safeRegionId,
+        iteration: loopState.iteration,
+        continueLoop,
+        conditionEvidenceDigest: evidenceDigest,
+        requestId: decisionKey,
+      },
+      () => {
+        if (loopState.status !== "waiting_condition") {
+          throw kernelError(
+            "CC_GRAPH_LOOP_NOT_WAITING",
+            `loop body is not awaiting a condition decision: ${safeRegionId}`,
+          );
+        }
+        const now = this.now();
+        loopState.conditionEvidenceDigest = evidenceDigest;
+        if (!continueLoop) {
+          loopState.status = "succeeded";
+          run.loopDecisionCache.set(decisionKey, {
+            digest: decisionDigest,
+            result: "exited",
+          });
+          propagate(run, () => now);
+          refreshLoopStates(run, () => now);
+          run.status = classifyQuiescence(run, now);
+          if (TERMINAL_RUN.has(run.status)) {
+            run.completedAt = nowIso(() => now);
+          }
+          return runProjection(run);
+        }
+
+        const nextIteration = loopState.iteration + 1;
+        if (nextIteration >= loop.maxIterations) {
+          loopState.status = "exhausted";
+          const frame = run.iterationFrames.get(loopState.frameId);
+          if (frame) frame.status = "exhausted";
+          const exitState = run.nodeStates.get(loop.exitNodeId);
+          exitState.status = "budget_exhausted";
+          exitState.blockedRoot = loop.id;
+          exitState.updatedAt = nowIso(() => now);
+          run.loopDecisionCache.set(decisionKey, {
+            digest: decisionDigest,
+            result: "exhausted",
+          });
+          propagate(run, () => now);
+          run.status = "budget_exhausted";
+          run.completedAt = nowIso(() => now);
+          return runProjection(run);
+        }
+
+        const iterationPath = [nextIteration];
+        const frameId = iterationFrameId(run.id, safeRegionId, iterationPath);
+        loopState.status = "active";
+        loopState.iteration = nextIteration;
+        loopState.iterationPath = iterationPath;
+        loopState.frameId = frameId;
+        loopState.conditionEvidenceDigest = null;
+        run.iterationFrames.set(frameId, {
+          id: frameId,
+          runId: run.id,
+          regionId: safeRegionId,
+          parentFrameId: null,
+          iterationPath,
+          status: "active",
+          startedAt: nowIso(() => now),
+          completedAt: null,
+        });
+        for (const nodeId of loop.nodeIds) {
+          const state = run.nodeStates.get(nodeId);
+          state.status = "pending";
+          state.acceptedAttemptId = null;
+          state.blockedRoot = null;
+          state.iterationPath = [...iterationPath];
+          state.updatedAt = nowIso(() => now);
+        }
+        run.loopDecisionCache.set(decisionKey, {
+          digest: decisionDigest,
+          result: "continued",
+        });
+        run.status = "running";
+        run.completedAt = null;
+        return runProjection(run);
+      },
+      { idempotencyKey: `loop-decision:${decisionKey}` },
+    );
+    return runProjection(run);
+  }
+
+  startSubgraph(
+    parentRunId,
+    nodeId,
+    compiledGraph,
+    { childRunId = null, seal = true } = {},
+  ) {
+    const childCompiled = assertCompiledGraph(compiledGraph);
+    const parent = this._run(parentRunId);
+    const safeNodeId = safeIdentifier(nodeId, "nodeId");
+    const call = parent.compiled.subgraphCalls?.[safeNodeId];
+    const state = parent.nodeStates.get(safeNodeId);
+    if (!call || !state) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_CALL_NOT_FOUND",
+        `subgraph call not found: ${safeNodeId}`,
+      );
+    }
+    if (
+      call.definitionId !== childCompiled.definitionId ||
+      call.revisionDigest !== childCompiled.revisionDigest
+    ) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_DIGEST_MISMATCH",
+        `subgraph definition does not match the pinned call: ${safeNodeId}`,
+      );
+    }
+    const childDepth = parent.subgraphDepth + 1;
+    if (childDepth > call.maxDepth) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_DEPTH_EXCEEDED",
+        `subgraph depth ${childDepth} exceeds maxDepth ${call.maxDepth}`,
+      );
+    }
+    if (parent.definitionPath.includes(childCompiled.definitionId)) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_RECURSION",
+        `recursive subgraph call rejected: ${[
+          ...parent.definitionPath,
+          childCompiled.definitionId,
+        ].join(" -> ")}`,
+      );
+    }
+    const id = safeIdentifier(
+      childRunId ||
+        deterministicSubgraphRunId(
+          parent.id,
+          safeNodeId,
+          childCompiled.revisionDigest,
+        ),
+      "childRunId",
+    );
+    let relation = parent.subgraphRuns.get(safeNodeId);
+    if (relation) {
+      if (
+        relation.childRunId !== id ||
+        relation.revisionDigest !== childCompiled.revisionDigest
+      ) {
+        throw kernelError(
+          "CC_GRAPH_SUBGRAPH_CALL_CONFLICT",
+          "subgraph call was already bound to a different child run",
+        );
+      }
+    } else {
+      if (parent.phase !== "sealed") {
+        throw kernelError(
+          "CC_GRAPH_SUBGRAPH_REQUIRES_SEALED_PARENT",
+          "subgraph calls require a sealed parent GraphRun",
+        );
+      }
+      if (
+        state.status !== "pending" ||
+        !nodeReadiness(parent, safeNodeId).ready
+      ) {
+        throw kernelError(
+          "CC_GRAPH_NODE_NOT_READY",
+          `Graph node is not ready: ${safeNodeId}`,
+        );
+      }
+      relation = this._transaction(
+        parent,
+        "subgraph.starting",
+        {
+          nodeId: safeNodeId,
+          childRunId: id,
+          definitionId: childCompiled.definitionId,
+          revisionDigest: childCompiled.revisionDigest,
+          depth: childDepth,
+          budgetSlice: call.budget,
+          inputBindings: call.inputBindings || [],
+          outputBindings: call.outputBindings || [],
+        },
+        () => {
+          const createdAt = nowIso(this.now);
+          reserveBudget(parent, call.budget || {});
+          const value = {
+            nodeId: safeNodeId,
+            childRunId: id,
+            definitionId: childCompiled.definitionId,
+            revisionDigest: childCompiled.revisionDigest,
+            depth: childDepth,
+            inputBindings: clone(call.inputBindings || []),
+            outputBindings: clone(call.outputBindings || []),
+            budgetSlice: clone(call.budget || {}),
+            budgetUsed: null,
+            budgetSettled: false,
+            status: "starting",
+            createdAt,
+            updatedAt: createdAt,
+            completedAt: null,
+          };
+          parent.subgraphRuns.set(safeNodeId, value);
+          state.status = "running";
+          state.updatedAt = createdAt;
+          parent.status = "waiting_external";
+          return clone(value);
+        },
+        { idempotencyKey: `subgraph-starting:${safeNodeId}:${id}` },
+      );
+    }
+
+    let child = this._loadRun(id);
+    if (child) {
+      if (
+        child.revisionDigest !== childCompiled.revisionDigest ||
+        child.parentRunRef?.runId !== parent.id ||
+        child.parentRunRef?.nodeId !== safeNodeId
+      ) {
+        throw kernelError(
+          "CC_GRAPH_SUBGRAPH_RUN_CONFLICT",
+          `child run id is already bound to another call: ${id}`,
+        );
+      }
+    } else {
+      this.startRun(childCompiled, {
+        runId: id,
+        parentRunRef: {
+          runId: parent.id,
+          nodeId: safeNodeId,
+          revisionDigest: parent.revisionDigest,
+        },
+        subgraphDepth: childDepth,
+        definitionPath: [...parent.definitionPath, childCompiled.definitionId],
+        budget: call.budget || {},
+      });
+      child = this._run(id);
+    }
+    if (seal !== false && child.phase === "open") this.sealRun(id);
+
+    relation = parent.subgraphRuns.get(safeNodeId);
+    if (relation.status === "starting") {
+      this._transaction(
+        parent,
+        "subgraph.started",
+        { nodeId: safeNodeId, childRunId: id },
+        () => {
+          relation.status = "running";
+          relation.updatedAt = nowIso(this.now);
+          parent.status = "waiting_external";
+        },
+        { idempotencyKey: `subgraph-started:${safeNodeId}:${id}` },
+      );
+    }
+    return Object.freeze({
+      relation: Object.freeze(clone(parent.subgraphRuns.get(safeNodeId))),
+      parentRun: runProjection(parent),
+      childRun: runProjection(child),
+    });
+  }
+
+  settleSubgraph(parentRunId, nodeId) {
+    const parent = this._run(parentRunId);
+    const safeNodeId = safeIdentifier(nodeId, "nodeId");
+    const relation = parent.subgraphRuns.get(safeNodeId);
+    if (!relation) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_NOT_STARTED",
+        `subgraph has not been started: ${safeNodeId}`,
+      );
+    }
+    if (["succeeded", "failed", "cancelled"].includes(relation.status)) {
+      return runProjection(parent);
+    }
+    const child = this._loadRun(relation.childRunId);
+    if (!child) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_RUN_NOT_FOUND",
+        `subgraph child run not found: ${relation.childRunId}`,
+      );
+    }
+    if (!TERMINAL_RUN.has(child.status)) {
+      throw kernelError(
+        "CC_GRAPH_SUBGRAPH_ACTIVE",
+        `subgraph child run is not terminal: ${child.status}`,
+      );
+    }
+    return this._transaction(
+      parent,
+      "subgraph.settled",
+      {
+        nodeId: safeNodeId,
+        childRunId: child.id,
+        childStatus: child.status,
+      },
+      () => {
+        const now = this.now();
+        const state = parent.nodeStates.get(safeNodeId);
+        const succeeded = child.status === "succeeded";
+        relation.status = succeeded
+          ? "succeeded"
+          : child.status === "cancelled"
+            ? "cancelled"
+            : "failed";
+        relation.updatedAt = nowIso(() => now);
+        relation.completedAt = nowIso(() => now);
+        relation.childStatus = child.status;
+        settleSubgraphBudget(parent, relation, child.budgetUsed);
+        state.status = succeeded
+          ? "succeeded"
+          : child.status === "cancelled"
+            ? "cancelled"
+            : child.status === "budget_exhausted"
+              ? "budget_exhausted"
+              : "failed";
+        state.blockedRoot = succeeded ? null : child.id;
+        state.updatedAt = nowIso(() => now);
+        propagate(parent, () => now);
+        refreshLoopStates(parent, () => now);
+        parent.status = classifyQuiescence(parent, now);
+        if (TERMINAL_RUN.has(parent.status)) {
+          parent.completedAt = nowIso(() => now);
+        }
+        return runProjection(parent);
+      },
+      {
+        idempotencyKey: `subgraph-settle:${safeNodeId}:${child.id}:${child.status}`,
+      },
+    );
+  }
+
   readyNodes(runId) {
     const run = this._run(runId);
     const now = this.now();
+    const compensationEntry = currentCompensationEntry(run);
+    if (compensationEntry) {
+      const state = run.nodeStates.get(compensationEntry.compensationNodeId);
+      if (state?.status !== "pending") return [];
+      return [
+        Object.freeze({
+          nodeId: compensationEntry.compensationNodeId,
+          compensationForNodeId: compensationEntry.nodeId,
+          iterationPath: Object.freeze([...compensationEntry.iterationPath]),
+          effectIdempotencyKey: iterationEffectIdempotencyKey(
+            run.compiled.nodes[compensationEntry.compensationNodeId]
+              .idempotencyKey,
+            compensationEntry.iterationPath,
+          ),
+          priority: Object.freeze({
+            base: 1000,
+            donation: 0,
+            aging: 0,
+            criticalPathBoost: 0,
+            total: 1000,
+            queueWaitMs: 0,
+          }),
+        }),
+      ];
+    }
     return run.compiled.topologicalOrder
       .filter((nodeId) => {
         const state = run.nodeStates.get(nodeId);
@@ -1209,6 +2081,32 @@ export class GraphKernel {
       })
       .map((nodeId) => ({
         nodeId,
+        iterationPath: Object.freeze([
+          ...(run.nodeStates.get(nodeId)?.iterationPath || []),
+        ]),
+        ...(["workspace_write", "external"].includes(
+          run.compiled.nodes[nodeId].effectClass,
+        )
+          ? {
+              effectIdempotencyKey: iterationEffectIdempotencyKey(
+                run.compiled.nodes[nodeId].idempotencyKey,
+                run.nodeStates.get(nodeId)?.iterationPath || [],
+              ),
+            }
+          : {}),
+        ...(run.compiled.subgraphCalls?.[nodeId]
+          ? {
+              dispatch: "subgraph",
+              definitionId: run.compiled.subgraphCalls[nodeId].definitionId,
+              revisionDigest: run.compiled.subgraphCalls[nodeId].revisionDigest,
+              maxDepth: run.compiled.subgraphCalls[nodeId].maxDepth,
+              inputBindings:
+                run.compiled.subgraphCalls[nodeId].inputBindings || [],
+              outputBindings:
+                run.compiled.subgraphCalls[nodeId].outputBindings || [],
+              budget: run.compiled.subgraphCalls[nodeId].budget || {},
+            }
+          : {}),
         priority: effectivePriority(run, nodeId, now, this.agingWindowMs),
       }))
       .sort(
@@ -1224,6 +2122,7 @@ export class GraphKernel {
     if (!ready.length) return null;
     let lastConflict = null;
     for (const candidate of ready) {
+      if (candidate.dispatch === "subgraph") continue;
       try {
         return this.assignNode(runId, candidate.nodeId, agentId, options);
       } catch (error) {
@@ -1250,13 +2149,30 @@ export class GraphKernel {
       role = "executor",
       ttlMs = 60_000,
       leaseId = this.createId(),
-      attemptId = this.createId(),
+      attemptId = null,
       grant = {},
     } = {},
   ) {
     const run = this._run(runId);
     const safeNodeId = safeIdentifier(nodeId, "nodeId");
     const safeAgentId = safeIdentifier(agentId, "agentId");
+    const plannedCompensation = compensationAssignment(run, safeNodeId);
+    const iterationPath = [
+      ...(plannedCompensation?.iterationPath ||
+        run.nodeStates.get(safeNodeId)?.iterationPath ||
+        []),
+    ];
+    const attemptNumber =
+      [...run.attempts.values()].filter(
+        (candidate) =>
+          candidate.nodeId === safeNodeId &&
+          JSON.stringify(candidate.iterationPath || []) ===
+            JSON.stringify(iterationPath),
+      ).length + 1;
+    const requestedAttemptId = safeIdentifier(
+      attemptId || executionAttemptId(safeNodeId, iterationPath, attemptNumber),
+      "attemptId",
+    );
     return this._transaction(
       run,
       "assignment.started",
@@ -1265,6 +2181,7 @@ export class GraphKernel {
         const now = this.now();
         sweepExpirations(run, now);
         propagate(run, () => now);
+        refreshLoopStates(run, () => now);
         const node = run.compiled.nodes[safeNodeId];
         const state = run.nodeStates.get(safeNodeId);
         if (!node || !state) {
@@ -1273,10 +2190,19 @@ export class GraphKernel {
             `Graph node not found: ${safeNodeId}`,
           );
         }
-        if (
-          state.status !== "pending" ||
-          !nodeReadiness(run, safeNodeId).ready
-        ) {
+        if (run.compiled.subgraphCalls?.[safeNodeId]) {
+          throw kernelError(
+            "CC_GRAPH_SUBGRAPH_DISPATCH_REQUIRED",
+            `subgraph nodes must be started through startSubgraph(): ${safeNodeId}`,
+          );
+        }
+        const compensationEntry = compensationAssignment(run, safeNodeId);
+        const ready = compensationEntry
+          ? state.status === "pending"
+          : run.compensation.status !== "running" &&
+            state.status === "pending" &&
+            nodeReadiness(run, safeNodeId).ready;
+        if (!ready) {
           throw kernelError(
             "CC_GRAPH_NODE_NOT_READY",
             `Graph node is not ready: ${safeNodeId}`,
@@ -1314,13 +2240,21 @@ export class GraphKernel {
         }
         const fence = (run.fenceCounters.get(safeNodeId) || 0) + 1;
         run.fenceCounters.set(safeNodeId, fence);
-        const id = safeIdentifier(attemptId, "attemptId");
+        const id = requestedAttemptId;
         const attempt = {
           id,
           runId: run.id,
           nodeId: safeNodeId,
+          iterationPath,
+          attempt: attemptNumber,
           agentId: safeAgentId,
-          role,
+          role: compensationEntry ? "executor" : role,
+          compensationForNodeId: compensationEntry?.nodeId || null,
+          effectIdempotencyKey: ["workspace_write", "external"].includes(
+            node.effectClass,
+          )
+            ? iterationEffectIdempotencyKey(node.idempotencyKey, iterationPath)
+            : null,
           leaseId: safeIdentifier(leaseId, "leaseId"),
           fence,
           status: "active",
@@ -1341,7 +2275,7 @@ export class GraphKernel {
         agent.updatedAt = nowIso(() => now);
         return attemptProjection(attempt);
       },
-      { idempotencyKey: `assignment:${attemptId}` },
+      { idempotencyKey: `assignment:${requestedAttemptId}` },
     );
   }
 
@@ -1423,7 +2357,11 @@ export class GraphKernel {
             "node did not declare an effectful execution class",
           );
         }
-        if (!key || key !== node.idempotencyKey) {
+        const authenticatedKey = iterationEffectIdempotencyKey(
+          node.idempotencyKey,
+          attempt.iterationPath,
+        );
+        if (!key || key !== authenticatedKey) {
           throw kernelError(
             "CC_GRAPH_EFFECT_IDEMPOTENCY_REQUIRED",
             "effect must use the idempotency key authenticated by Graph Compiler",
@@ -1440,9 +2378,11 @@ export class GraphKernel {
           runId: run.id,
           nodeId: attempt.nodeId,
           attemptId: attempt.id,
+          iterationPath: [...attempt.iterationPath],
           leaseId: attempt.leaseId,
           fence: attempt.fence,
           idempotencyKey: key,
+          baseIdempotencyKey: node.idempotencyKey,
           operationDigest,
           status: "started",
           receipt: null,
@@ -1683,6 +2623,7 @@ export class GraphKernel {
         );
         const state = run.nodeStates.get(attempt.nodeId);
         const node = run.compiled.nodes[attempt.nodeId];
+        const compensationEntry = compensationAssignment(run, attempt.nodeId);
         if (state.acceptedAttemptId && state.acceptedAttemptId !== attempt.id) {
           attempt.status = "rejected";
           attempt.participationStatus = "loser";
@@ -1701,7 +2642,16 @@ export class GraphKernel {
           attempt.terminalEvidence = clone(evidence);
           state.status = "reconciliation_required";
           state.updatedAt = nowIso(this.now);
-          run.status = "reconciliation_required";
+          if (compensationEntry) {
+            failCompensation(
+              run,
+              compensationEntry,
+              error || "compensation outcome is unknown",
+              this.now(),
+            );
+          } else {
+            run.status = "reconciliation_required";
+          }
           return attemptProjection(attempt);
         }
         if (outcome === "succeeded") {
@@ -1757,8 +2707,7 @@ export class GraphKernel {
           attempt.participationStatus = "failed";
           attempt.error = error == null ? null : String(error).slice(0, 4096);
           attempt.terminalEvidence = clone(evidence);
-          const attemptNumber = state.attemptIds.length;
-          if (attemptNumber <= Number(node.retryLimit || 0)) {
+          if (attempt.attempt <= Number(node.retryLimit || 0)) {
             state.status = "pending";
           } else {
             state.status = outcome === "timed_out" ? "timed_out" : "failed";
@@ -1781,8 +2730,22 @@ export class GraphKernel {
           agent.status = "idle";
           agent.updatedAt = nowIso(this.now);
         }
-        propagate(run, this.now);
-        run.status = classifyQuiescence(run, this.now());
+        if (compensationEntry) {
+          if (outcome === "succeeded") {
+            completeCompensationStep(run, compensationEntry, this.now());
+          } else if (state.status !== "pending") {
+            failCompensation(
+              run,
+              compensationEntry,
+              error || outcome,
+              this.now(),
+            );
+          }
+        } else {
+          propagate(run, this.now);
+          if (refreshLoopStates(run, this.now)) propagate(run, this.now);
+          run.status = classifyQuiescence(run, this.now());
+        }
         if (TERMINAL_RUN.has(run.status)) run.completedAt = nowIso(this.now);
         return attemptProjection(attempt);
       },
@@ -1832,6 +2795,20 @@ export class GraphKernel {
         }
       }),
     );
+    for (const relation of run.subgraphRuns.values()) {
+      if (!["starting", "running"].includes(relation.status)) continue;
+      try {
+        const child = this._loadRun(relation.childRunId);
+        if (child && !TERMINAL_RUN.has(child.status)) {
+          await this.cancelRun(child.id, { reason, interrupt });
+        }
+      } catch (error) {
+        failures.push({
+          subgraphRunId: relation.childRunId,
+          error: String(error?.message || error).slice(0, 4096),
+        });
+      }
+    }
     return this._transaction(
       run,
       failures.length ? "run.cancel_reconciliation" : "run.cancelled",
@@ -1851,6 +2828,27 @@ export class GraphKernel {
           state.status = failure ? "reconciliation_required" : "cancelled";
           state.updatedAt = nowIso(this.now);
         }
+        for (const relation of run.subgraphRuns.values()) {
+          if (!["starting", "running"].includes(relation.status)) continue;
+          const failure = failures.find(
+            (entry) => entry.subgraphRunId === relation.childRunId,
+          );
+          const child = this._loadRun(relation.childRunId);
+          if (!failure) {
+            settleSubgraphBudget(
+              run,
+              relation,
+              child?.budgetUsed || emptyBudgetUsage(),
+            );
+          }
+          relation.status = failure ? "failed" : "cancelled";
+          relation.updatedAt = nowIso(this.now);
+          relation.completedAt = failure ? null : nowIso(this.now);
+          const state = run.nodeStates.get(relation.nodeId);
+          state.status = failure ? "reconciliation_required" : "cancelled";
+          state.blockedRoot = relation.childRunId;
+          state.updatedAt = nowIso(this.now);
+        }
         const unsettledEffects = [...run.effects.values()].filter(
           (effect) => effect.status === "started",
         );
@@ -1861,6 +2859,7 @@ export class GraphKernel {
           state.status = "reconciliation_required";
           state.updatedAt = nowIso(this.now);
         }
+        refreshLoopStates(run, this.now);
         const requiresReconciliation =
           failures.length > 0 || unsettledEffects.length > 0;
         run.status = requiresReconciliation
@@ -1872,6 +2871,125 @@ export class GraphKernel {
     );
   }
 
+  beginCompensation(
+    runId,
+    { triggerNodeId = null, reason = "forward_failure" } = {},
+  ) {
+    const run = this._run(runId);
+    const trigger =
+      triggerNodeId == null
+        ? null
+        : safeIdentifier(triggerNodeId, "triggerNodeId");
+    if (run.compensation.status !== "idle") {
+      if (
+        run.compensation.triggerNodeId === trigger &&
+        run.compensation.reason === String(reason)
+      ) {
+        return runProjection(run);
+      }
+      throw kernelError(
+        "CC_GRAPH_COMPENSATION_ALREADY_STARTED",
+        "compensation has already been started for this run",
+      );
+    }
+    return this._transaction(
+      run,
+      "compensation.started",
+      { triggerNodeId: trigger, reason },
+      () => {
+        if (
+          !["failed", "partial", "cancelled", "budget_exhausted"].includes(
+            run.status,
+          )
+        ) {
+          throw kernelError(
+            "CC_GRAPH_COMPENSATION_NOT_AVAILABLE",
+            "compensation requires a failed, partial, cancelled, or budget-exhausted terminal run",
+          );
+        }
+        if (trigger && !run.compiled.nodes[trigger]) {
+          throw kernelError(
+            "CC_GRAPH_NODE_NOT_FOUND",
+            `Graph node not found: ${trigger}`,
+          );
+        }
+        const activeAttempts = [...run.attempts.values()].filter((attempt) =>
+          ACTIVE_ATTEMPT.has(attempt.status),
+        );
+        const unsettledEffects = [...run.effects.values()].filter((effect) =>
+          ["started", "unknown"].includes(effect.status),
+        );
+        if (activeAttempts.length || unsettledEffects.length) {
+          throw kernelError(
+            "CC_GRAPH_COMPENSATION_UNSETTLED",
+            "compensation cannot start before attempts and effects are settled",
+            {
+              attemptIds: activeAttempts.map((attempt) => attempt.id).sort(),
+              effectIds: unsettledEffects.map((effect) => effect.id).sort(),
+            },
+          );
+        }
+        const plan = (run.compiled.forwardTopologicalOrder || [])
+          .filter((nodeId) => run.compiled.compensationByNode?.[nodeId])
+          .reverse()
+          .flatMap((nodeId) =>
+            committedEffectsForNode(run, nodeId)
+              .reverse()
+              .map((effect) => ({
+                nodeId,
+                compensationNodeId: run.compiled.compensationByNode[nodeId],
+                iterationPath: [...(effect.iterationPath || [])],
+                effectIds: [effect.id],
+              })),
+          );
+        if (plan.length === 0) {
+          throw kernelError(
+            "CC_GRAPH_COMPENSATION_NOT_REQUIRED",
+            "run has no committed compensatable effects",
+          );
+        }
+        const now = this.now();
+        const preparedTargets = new Set();
+        for (const entry of plan) {
+          if (preparedTargets.has(entry.compensationNodeId)) continue;
+          const state = run.nodeStates.get(entry.compensationNodeId);
+          if (!state || state.status !== "skipped") {
+            throw kernelError(
+              "CC_GRAPH_COMPENSATION_TARGET_INVALID",
+              `compensation target is not isolated and idle: ${entry.compensationNodeId}`,
+            );
+          }
+          state.status = "pending";
+          state.blockedRoot = null;
+          state.iterationPath = [...entry.iterationPath];
+          state.updatedAt = nowIso(() => now);
+          preparedTargets.add(entry.compensationNodeId);
+        }
+        run.compensation = {
+          status: "running",
+          triggerNodeId: trigger,
+          reason: String(reason),
+          terminalStatus: run.status,
+          plan,
+          currentIndex: 0,
+          completedNodeIds: [],
+          completedEntries: [],
+          failure: null,
+          startedAt: nowIso(() => now),
+          completedAt: null,
+        };
+        run.status = "running";
+        run.completedAt = null;
+        run.phase = "sealed";
+        return runProjection(run);
+      },
+      {
+        allowTerminal: true,
+        idempotencyKey: `compensation-start:${run.id}:${trigger || "terminal"}`,
+      },
+    );
+  }
+
   sendMessage(
     runId,
     {
@@ -2273,10 +3391,20 @@ export class GraphKernel {
         sender.updatedAt = nowIso(() => now);
         const fence = (run.fenceCounters.get(sender.nodeId) || 0) + 1;
         run.fenceCounters.set(sender.nodeId, fence);
+        const iterationPath = [...(sender.iterationPath || [])];
+        const attemptNumber =
+          [...run.attempts.values()].filter(
+            (candidate) =>
+              candidate.nodeId === sender.nodeId &&
+              JSON.stringify(candidate.iterationPath || []) ===
+                JSON.stringify(iterationPath),
+          ).length + 1;
         const newAttempt = {
           id: safeIdentifier(attemptId, "attemptId"),
           runId: run.id,
           nodeId: sender.nodeId,
+          iterationPath,
+          attempt: attemptNumber,
           agentId: handoff.toAgentId,
           role: "executor",
           leaseId: safeIdentifier(leaseId, "leaseId"),