supipowers 1.5.3 → 2.0.0

package/src/ultraplan/runtime/reducer.ts

@@ -0,0 +1,416 @@
+import type {
+  UltraPlanAttemptRecord,
+  UltraPlanBlockerCandidate,
+  UltraPlanCursor,
+  UltraPlanHookObservation,
+  UltraPlanMutationPlan,
+  UltraPlanProofCandidate,
+  UltraPlanReducerAction,
+  UltraPlanRuntimeTracker,
+  UltraPlanScenarioStatus,
+} from "../../types.js";
+import {
+  buildConflictingEvidenceBlocker,
+  buildInterruptedAttemptBlocker,
+  buildProofMissingBlocker,
+  buildUnsafeRepairRequiredBlocker,
+} from "./blockers.js";
+
+/**
+ * Slice-2 pure reducer.
+ *
+ * Decides, given the current state and a validated action, what the persisted mutation should
+ * be. The reducer performs no I/O; its output is consumed by the hook bridge's
+ * `applyMutationPlan` seam which runs the durability order. See approved spec §reducer outcome
+ * precedence (lines 562–572) and §transition rules.
+ */
+
+export interface ReducerState {
+  tracker: UltraPlanRuntimeTracker;
+  cursor: UltraPlanCursor | null;
+}
+
+export function reduce(state: ReducerState, action: UltraPlanReducerAction): UltraPlanMutationPlan {
+  if (state.cursor?.targetType === "session" && state.cursor.status === "complete") {
+    return buildPlan({
+      kind: "complete",
+      rationale: "cursor already resolved to session complete",
+      cursorUpdate: state.cursor,
+      sessionStateUpdate: "complete",
+    });
+  }
+
+  switch (action.kind) {
+    case "session_started":
+      return buildPlan({ kind: "noop", rationale: "session_started observed; repair runs separately" });
+    case "attempt_started":
+      return reduceAttemptStarted(state, action);
+    case "observation_staged":
+      return reduceObservationStaged(state, action);
+    case "attempt_finalized":
+      return reduceAttemptFinalized(state, action);
+    case "session_shutdown":
+      return reduceSessionShutdown(state, action);
+    case "repair_applied":
+      return buildPlan({
+        kind: "repair",
+        rationale: action.details.reason,
+        repairActions: action.details.actions,
+      });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// attempt_started
+// ---------------------------------------------------------------------------
+
+function reduceAttemptStarted(
+  state: ReducerState,
+  action: Extract<UltraPlanReducerAction, { kind: "attempt_started" }>,
+): UltraPlanMutationPlan {
+  const { observation } = action;
+
+  if (alreadyApplied(state.tracker, observation.fingerprint)) {
+    return buildPlan({
+      kind: "noop",
+      rationale: `attempt_started observation ${observation.fingerprint} already applied`,
+    });
+  }
+
+  if (state.tracker.activeAttempt) {
+    return buildPlan({
+      kind: "block",
+      rationale: `nested before_agent_start observed while attempt ${state.tracker.activeAttempt.attemptId} is still active`,
+      blockerUpdate: {
+        scope: "session",
+        nextValue: buildUnsafeRepairRequiredBlocker({
+          detectedAt: observation.occurredAt,
+          scope: "session",
+          reason: `active attempt ${state.tracker.activeAttempt.attemptId} must finalize before a new attempt starts`,
+        }),
+        clearedByObservationFingerprint: null,
+      },
+      sessionStateUpdate: "blocked",
+      appendObservationFingerprint: observation.fingerprint,
+    });
+  }
+
+  const cursor = state.cursor;
+  if (!cursor || !isLegalStartFromCursor(cursor)) {
+    return buildPlan({
+      kind: "block",
+      rationale: "attempt_started from a cursor that has no legal-start transition",
+      blockerUpdate: {
+        scope: "session",
+        nextValue: buildUnsafeRepairRequiredBlocker({
+          detectedAt: observation.occurredAt,
+          scope: "session",
+          reason: `cursor status ${cursor?.status ?? "null"} has no legal-start transition`,
+        }),
+        clearedByObservationFingerprint: null,
+      },
+      sessionStateUpdate: "blocked",
+      appendObservationFingerprint: observation.fingerprint,
+    });
+  }
+
+  const nextStatus = legalStartNextStatus(cursor);
+  return buildPlan({
+    kind: "start-attempt",
+    rationale: `legal start: ${cursor.status} -> ${nextStatus}`,
+    cursorUpdate: { ...cursor, status: nextStatus, phase: phaseForStatus(nextStatus, cursor.phase) },
+    sessionStateUpdate: "running",
+    appendObservationFingerprint: observation.fingerprint,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// observation_staged
+// ---------------------------------------------------------------------------
+
+function reduceObservationStaged(
+  state: ReducerState,
+  action: Extract<UltraPlanReducerAction, { kind: "observation_staged" }>,
+): UltraPlanMutationPlan {
+  const { observation } = action;
+  if (alreadyApplied(state.tracker, observation.fingerprint)) {
+    return buildPlan({ kind: "noop", rationale: "observation already applied" });
+  }
+  return buildPlan({
+    kind: "stage-observation",
+    rationale: `stage observation ${observation.fingerprint}`,
+    appendObservationFingerprint: observation.fingerprint,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// attempt_finalized  (precedence: conflicting -> proof -> blocker -> interrupted -> noop)
+// ---------------------------------------------------------------------------
+
+function reduceAttemptFinalized(
+  state: ReducerState,
+  action: Extract<UltraPlanReducerAction, { kind: "attempt_finalized" }>,
+): UltraPlanMutationPlan {
+  const { observation, nowIso } = action;
+  if (alreadyApplied(state.tracker, observation.fingerprint)) {
+    return buildPlan({ kind: "noop", rationale: "attempt_finalized already applied" });
+  }
+
+  const active = state.tracker.activeAttempt;
+  if (!active) {
+    return buildPlan({
+      kind: "noop",
+      rationale: "attempt_finalized observed without an active attempt; treated as replay",
+    });
+  }
+
+  const proofs = active.proofCandidates;
+  const blockers = active.blockerCandidates;
+  const cursor = state.cursor;
+
+  // Rule 1 — conflicting evidence: fail closed.
+  if (proofs.length > 0 && blockers.length > 0) {
+    return buildPlan({
+      kind: "block",
+      rationale: "conflicting evidence: proof and blocker in the same attempt finalization",
+      blockerUpdate: {
+        scope: "scenario",
+        nextValue: buildConflictingEvidenceBlocker({
+          detectedAt: nowIso,
+          scope: "scenario",
+          affected: cursor ? toAffected(cursor) : undefined,
+          reason: "valid proof and blocker candidate observed in same attempt",
+        }),
+        clearedByObservationFingerprint: null,
+      },
+      trackerAttemptFinalization: { attemptId: active.attemptId, outcome: "blocked", finalizedAt: nowIso },
+      sessionStateUpdate: "blocked",
+      appendObservationFingerprint: observation.fingerprint,
+    });
+  }
+
+  // Rule 2 — valid proof for the current target/phase advances scenario status.
+  if (proofs.length > 0 && cursor) {
+    const proof = pickProofForCursor(proofs, cursor);
+    if (proof) {
+      const nextStatus = provedStatusForPhase(proof.phase);
+      if (nextStatus) {
+        return buildPlan({
+          kind: "advance",
+          rationale: `${proof.phase}-phase proof matched cursor; advancing to ${nextStatus}`,
+          scenarioStatusUpdate: {
+            stack: cursor.stack!,
+            domainId: cursor.domainId!,
+            level: cursor.level!,
+            scenarioId: cursor.scenarioId!,
+            nextStatus,
+            appendProof: {
+              type: proof.type,
+              phase: proof.phase,
+              recordedAt: observation.occurredAt,
+              actor: observation.target?.resolvedSlot ?? "frontend-executor",
+              evidence: proof.evidence,
+              artifactRef: proof.artifactRef ?? `artifact://${proof.phase}-${active.attemptId}`,
+            },
+          },
+          cursorUpdate: advancedCursor(cursor, nextStatus),
+          trackerAttemptFinalization: { attemptId: active.attemptId, outcome: "advanced", finalizedAt: nowIso },
+          recomputeProgress: true,
+          appendObservationFingerprint: observation.fingerprint,
+        });
+      }
+    }
+  }
+
+  // Rule 3 — explicit blocker candidate.
+  if (blockers.length > 0) {
+    const candidate = blockers[0];
+    return buildPlan({
+      kind: "block",
+      rationale: `explicit blocker candidate ${candidate.blocker.code}`,
+      blockerUpdate: {
+        scope: candidate.blocker.scope,
+        nextValue: candidate.blocker,
+        clearedByObservationFingerprint: null,
+      },
+      trackerAttemptFinalization: { attemptId: active.attemptId, outcome: "blocked", finalizedAt: nowIso },
+      sessionStateUpdate: candidate.blocker.recoveryMode === "await-user" ? "awaiting-user" : "blocked",
+      appendObservationFingerprint: observation.fingerprint,
+    });
+  }
+
+  // Rule 4 — no proof, no blocker: interrupted outcome. Do NOT silently advance.
+  const interruptedBlocker = buildInterruptedAttemptBlocker({
+    detectedAt: nowIso,
+    scope: "scenario",
+    affected: cursor ? toAffected(cursor) : undefined,
+    attemptId: active.attemptId,
+  });
+  return buildPlan({
+    kind: "interrupt",
+    rationale: "no proof and no blocker observed; attempt interrupted",
+    blockerUpdate: {
+      scope: "scenario",
+      nextValue: interruptedBlocker,
+      clearedByObservationFingerprint: null,
+    },
+    trackerAttemptFinalization: { attemptId: active.attemptId, outcome: "interrupted", finalizedAt: nowIso },
+    sessionStateUpdate: "blocked",
+    appendObservationFingerprint: observation.fingerprint,
+    notes: [`missing-proof: ${buildProofMissingBlocker({ detectedAt: nowIso, expectedPhase: inferPhase(cursor) }).message}`],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// session_shutdown
+// ---------------------------------------------------------------------------
+
+function reduceSessionShutdown(
+  state: ReducerState,
+  action: Extract<UltraPlanReducerAction, { kind: "session_shutdown" }>,
+): UltraPlanMutationPlan {
+  const active = state.tracker.activeAttempt;
+  if (!active) {
+    return buildPlan({ kind: "noop", rationale: "session_shutdown with no active attempt" });
+  }
+  const interruptedBlocker = buildInterruptedAttemptBlocker({
+    detectedAt: action.nowIso,
+    scope: "scenario",
+    affected: state.cursor ? toAffected(state.cursor) : undefined,
+    attemptId: active.attemptId,
+    reason: "session shut down with in-flight active attempt",
+  });
+  return buildPlan({
+    kind: "interrupt",
+    rationale: `session_shutdown interrupted attempt ${active.attemptId}`,
+    blockerUpdate: {
+      scope: "scenario",
+      nextValue: interruptedBlocker,
+      clearedByObservationFingerprint: null,
+    },
+    trackerAttemptFinalization: { attemptId: active.attemptId, outcome: "interrupted", finalizedAt: action.nowIso },
+    sessionStateUpdate: "blocked",
+    appendObservationFingerprint: action.observation.fingerprint,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+interface PlanBuilderInput {
+  kind: UltraPlanMutationPlan["kind"];
+  rationale: string;
+  appendObservationFingerprint?: string | null;
+  scenarioStatusUpdate?: UltraPlanMutationPlan["scenarioStatusUpdate"];
+  reviewStatusUpdate?: UltraPlanMutationPlan["reviewStatusUpdate"];
+  blockerUpdate?: UltraPlanMutationPlan["blockerUpdate"];
+  cursorUpdate?: UltraPlanMutationPlan["cursorUpdate"];
+  sessionStateUpdate?: UltraPlanMutationPlan["sessionStateUpdate"];
+  trackerAttemptFinalization?: UltraPlanMutationPlan["trackerAttemptFinalization"];
+  recomputeProgress?: boolean;
+  repairActions?: UltraPlanMutationPlan["repairActions"];
+  notes?: string[];
+}
+
+function buildPlan(input: PlanBuilderInput): UltraPlanMutationPlan {
+  return {
+    kind: input.kind,
+    rationale: input.rationale,
+    appendObservationFingerprint: input.appendObservationFingerprint ?? null,
+    scenarioStatusUpdate: input.scenarioStatusUpdate ?? null,
+    reviewStatusUpdate: input.reviewStatusUpdate ?? null,
+    blockerUpdate: input.blockerUpdate ?? null,
+    cursorUpdate: input.cursorUpdate ?? null,
+    sessionStateUpdate: input.sessionStateUpdate ?? null,
+    trackerAttemptFinalization: input.trackerAttemptFinalization ?? null,
+    recomputeProgress: input.recomputeProgress ?? false,
+    repairActions: input.repairActions ?? [],
+    notes: input.notes ?? [],
+  };
+}
+
+function alreadyApplied(tracker: UltraPlanRuntimeTracker, fingerprint: string): boolean {
+  return tracker.appliedFingerprints.includes(fingerprint);
+}
+
+function isLegalStartFromCursor(cursor: UltraPlanCursor): boolean {
+  // Legal-start transitions per spec §transition classes:
+  //   planned -> red-running
+  //   red-proved -> green-running
+  //   review pending -> running
+  if (cursor.targetType === "scenario") {
+    return cursor.status === "planned" || cursor.status === "red-proved";
+  }
+  if (cursor.targetType === "domain-review" || cursor.targetType === "stack-review") {
+    return cursor.status === "pending";
+  }
+  return false;
+}
+
+function legalStartNextStatus(cursor: UltraPlanCursor): UltraPlanCursor["status"] {
+  if (cursor.targetType === "scenario") {
+    if (cursor.status === "planned") return "red-running";
+    if (cursor.status === "red-proved") return "green-running";
+  }
+  if (cursor.targetType === "domain-review" || cursor.targetType === "stack-review") {
+    return "running";
+  }
+  throw new Error(`legalStartNextStatus called with unsupported cursor status ${cursor.status}`);
+}
+
+function phaseForStatus(status: UltraPlanCursor["status"], fallback: UltraPlanCursor["phase"]): UltraPlanCursor["phase"] {
+  switch (status) {
+    case "red-running":
+      return "red";
+    case "green-running":
+      return "green";
+    case "red-proved":
+      return "green";
+    case "green-proved":
+      return "complete";
+    case "running":
+      return "review";
+    default:
+      return fallback;
+  }
+}
+
+function provedStatusForPhase(phase: UltraPlanProofCandidate["phase"]): UltraPlanScenarioStatus | null {
+  if (phase === "red") return "red-proved";
+  if (phase === "green") return "green-proved";
+  return null;
+}
+
+function advancedCursor(cursor: UltraPlanCursor, nextStatus: UltraPlanScenarioStatus): UltraPlanCursor {
+  return { ...cursor, status: nextStatus, phase: phaseForStatus(nextStatus, cursor.phase) };
+}
+
+function pickProofForCursor(proofs: UltraPlanProofCandidate[], cursor: UltraPlanCursor): UltraPlanProofCandidate | null {
+  const expectedPhase = inferPhase(cursor);
+  for (const proof of proofs) {
+    if (proof.phase !== expectedPhase) continue;
+    if (proof.target.stack !== cursor.stack) continue;
+    if (proof.target.domainId !== cursor.domainId) continue;
+    if (proof.target.level !== cursor.level) continue;
+    if (proof.target.scenarioId !== cursor.scenarioId) continue;
+    return proof;
+  }
+  return null;
+}
+
+function inferPhase(cursor: UltraPlanCursor | null): UltraPlanCursor["phase"] {
+  if (!cursor) return "red";
+  if (cursor.status === "red-running") return "red";
+  if (cursor.status === "green-running") return "green";
+  return cursor.phase;
+}
+
+function toAffected(cursor: UltraPlanCursor) {
+  return {
+    stack: cursor.stack,
+    domainId: cursor.domainId,
+    level: cursor.level,
+    scenarioId: cursor.scenarioId,
+  };
+}

package/src/ultraplan/runtime/repair.ts

@@ -0,0 +1,251 @@
+import type {
+  UltraPlanAttemptRecord,
+  UltraPlanBlocker,
+  UltraPlanManifest,
+  UltraPlanPendingMutation,
+  UltraPlanRepairAction,
+  UltraPlanRuntimeTracker,
+} from "../../types.js";
+import { buildUnsafeRepairRequiredBlocker } from "./blockers.js";
+
+/**
+ * Slice-2 deterministic repair engine. Pure.
+ *
+ * Safe auto-repair categories (spec §safe auto-repair boundaries, lines 707–723):
+ * - recompute cursor
+ * - recompute progress summaries
+ * - clear impossible active-attempt references
+ * - convert orphaned in-flight attempts into interrupted state
+ * - clear blockers directly invalidated by later proof on the same target
+ *
+ * Forbidden: inventing proof, promoting a target to terminal without evidence, discarding
+ * conflicting evidence, skipping ahead, or rewriting authored intent. When repair would require
+ * any of those, the engine emits an `unsafe-repair-required` blocker instead of a mutation.
+ */
+
+export interface RepairState {
+  tracker: UltraPlanRuntimeTracker;
+  manifest: UltraPlanManifest | null;
+}
+
+export interface RepairPlan {
+  /** Deterministic actions the caller applies to the tracker / derived state. */
+  actions: UltraPlanRepairAction[];
+  /** Blockers emitted by the repair engine when deterministic recovery is unsafe. */
+  emittedBlockers: UltraPlanBlocker[];
+  /** What the caller should do with the tracker's `activeAttempt`. */
+  activeAttemptAction: "leave" | "clear" | "finalize-as-interrupted";
+  /** Resume-time handling for a staged pending mutation. */
+  pendingMutationAction: "leave" | "clear" | "apply-and-clear";
+}
+
+// ---------------------------------------------------------------------------
+// session_start
+// ---------------------------------------------------------------------------
+
+export function repairOnSessionStart(state: RepairState, nowIso: string): RepairPlan {
+  const actions: UltraPlanRepairAction[] = [];
+  const emittedBlockers: UltraPlanBlocker[] = [];
+  let activeAttemptAction: RepairPlan["activeAttemptAction"] = "leave";
+  let pendingMutationAction: RepairPlan["pendingMutationAction"] = "leave";
+
+  const active = state.tracker.activeAttempt;
+  if (active) {
+    const hasProof = active.proofCandidates.length > 0;
+    const hasBlocker = active.blockerCandidates.length > 0;
+
+    if (hasProof && hasBlocker) {
+      emittedBlockers.push(buildUnsafeRepairRequiredBlocker({
+        detectedAt: nowIso,
+        scope: "scenario",
+        affected: {
+          stack: active.cursorSnapshot?.stack ?? null,
+          domainId: active.cursorSnapshot?.domainId ?? null,
+          level: active.cursorSnapshot?.level ?? null,
+          scenarioId: active.cursorSnapshot?.scenarioId ?? null,
+        },
+        reason: `attempt ${active.attemptId} carries both proof and blocker candidates; cannot auto-finalize`,
+      }));
+      actions.push({
+        op: "convert-active-to-interrupted",
+        attemptId: active.attemptId,
+        reason: "conflicting proof+blocker on resume",
+      });
+      activeAttemptAction = "finalize-as-interrupted";
+    } else {
+      actions.push({
+        op: "convert-active-to-interrupted",
+        attemptId: active.attemptId,
+        reason: "orphaned in-flight attempt recovered on session_start",
+      });
+      activeAttemptAction = "finalize-as-interrupted";
+    }
+  }
+
+  const pending = reconcilePendingMutation(state, nowIso);
+  pendingMutationAction = pending.pendingMutationAction;
+  emittedBlockers.push(...pending.emittedBlockers);
+
+  const manifestBlocker = state.manifest?.blocker ?? null;
+  if (manifestBlocker) {
+    const clearedBy = findLaterProofForBlocker(state.tracker, manifestBlocker);
+    if (clearedBy) {
+      actions.push({
+        op: "clear-blocker",
+        scope: manifestBlocker.scope,
+        clearedByObservationFingerprint: clearedBy,
+      });
+    }
+  }
+
+  return { actions, emittedBlockers, activeAttemptAction, pendingMutationAction };
+}
+
+// ---------------------------------------------------------------------------
+// session_shutdown
+// ---------------------------------------------------------------------------
+
+export function repairOnSessionShutdown(state: RepairState, nowIso: string): RepairPlan {
+  const actions: UltraPlanRepairAction[] = [];
+  let activeAttemptAction: RepairPlan["activeAttemptAction"] = "leave";
+
+  const active = state.tracker.activeAttempt;
+  if (active) {
+    actions.push({
+      op: "convert-active-to-interrupted",
+      attemptId: active.attemptId,
+      reason: `session shutdown with in-flight attempt (recorded at ${nowIso})`,
+    });
+    activeAttemptAction = "finalize-as-interrupted";
+  }
+
+  return { actions, emittedBlockers: [], activeAttemptAction, pendingMutationAction: "leave" };
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function findLaterProofForBlocker(tracker: UltraPlanRuntimeTracker, blocker: UltraPlanBlocker): string | null {
+  const affected = blocker.affected;
+  for (const attempt of tracker.finalizedAttempts) {
+    if (attempt.outcome !== "advanced") continue;
+    const proof = attempt.proofCandidates.find((p) =>
+      p.target.stack === affected.stack
+      && p.target.domainId === affected.domainId
+      && p.target.level === affected.level
+      && p.target.scenarioId === affected.scenarioId,
+    );
+    if (proof && isLaterThan(attempt.finalizedAt, blocker.detectedAt)) {
+      return proof.observationFingerprint;
+    }
+  }
+  return null;
+}
+
+function isLaterThan(candidate: string | null, reference: string): boolean {
+  if (!candidate) return false;
+  const a = Date.parse(candidate);
+  const b = Date.parse(reference);
+  if (Number.isNaN(a) || Number.isNaN(b)) return false;
+  return a > b;
+}
+
+function reconcilePendingMutation(
+  state: RepairState,
+  nowIso: string,
+): Pick<RepairPlan, "pendingMutationAction" | "emittedBlockers"> {
+  const pending = state.tracker.pendingMutation;
+  if (!pending) {
+    return { pendingMutationAction: "leave", emittedBlockers: [] };
+  }
+
+  if (!state.manifest) {
+    return {
+      pendingMutationAction: "leave",
+      emittedBlockers: [buildUnsafeRepairRequiredBlocker({
+        detectedAt: nowIso,
+        scope: "session",
+        reason: `pending mutation ${pending.attemptId} cannot be reconciled without a manifest snapshot`,
+      })],
+    };
+  }
+
+  if (isPendingMutationReflected(state.manifest, pending)) {
+    return { pendingMutationAction: "clear", emittedBlockers: [] };
+  }
+
+  if (canSafelyApplyPendingMutation(pending)) {
+    return { pendingMutationAction: "apply-and-clear", emittedBlockers: [] };
+  }
+
+  return {
+    pendingMutationAction: "leave",
+    emittedBlockers: [buildUnsafeRepairRequiredBlocker({
+      detectedAt: nowIso,
+      scope: "session",
+      reason: `pending mutation ${pending.attemptId} still requires canonical authored/review reconciliation`,
+    })],
+  };
+}
+
+function isPendingMutationReflected(manifest: UltraPlanManifest, pending: UltraPlanPendingMutation): boolean {
+  const mutationPlan = pending.mutationPlan;
+
+  if (mutationPlan.scenarioStatusUpdate || mutationPlan.recomputeProgress) {
+    return false;
+  }
+
+  const checks: boolean[] = [];
+
+  if (mutationPlan.blockerUpdate) {
+    const nextValue = mutationPlan.blockerUpdate.nextValue;
+    checks.push(nextValue === null
+      ? manifest.blocker === null
+      : JSON.stringify(manifest.blocker) === JSON.stringify(nextValue));
+  }
+
+  if (mutationPlan.cursorUpdate) {
+    checks.push(sameCursor(manifest.cursor, mutationPlan.cursorUpdate));
+  }
+
+  if (mutationPlan.sessionStateUpdate) {
+    checks.push(manifest.state === mutationPlan.sessionStateUpdate);
+  }
+
+  if (mutationPlan.reviewStatusUpdate) {
+    const review = manifest.reviews.find((candidate) =>
+      candidate.type === mutationPlan.reviewStatusUpdate?.type
+      && candidate.stack === mutationPlan.reviewStatusUpdate.stack
+      && candidate.domainId === mutationPlan.reviewStatusUpdate.domainId,
+    );
+    checks.push(
+      review?.status === mutationPlan.reviewStatusUpdate.nextStatus
+        && review.path === mutationPlan.reviewStatusUpdate.artifactRef,
+    );
+  }
+
+  return checks.length > 0 && checks.every(Boolean);
+}
+
+function canSafelyApplyPendingMutation(pending: UltraPlanPendingMutation): boolean {
+  const mutationPlan = pending.mutationPlan;
+  return mutationPlan.scenarioStatusUpdate === null
+    && mutationPlan.reviewStatusUpdate === null
+    && mutationPlan.recomputeProgress === false;
+}
+
+function sameCursor(left: UltraPlanManifest["cursor"], right: UltraPlanManifest["cursor"]): boolean {
+  if (!left || !right) {
+    return left === right;
+  }
+
+  return left.targetType === right.targetType
+    && left.stack === right.stack
+    && left.domainId === right.domainId
+    && left.level === right.level
+    && left.scenarioId === right.scenarioId
+    && left.phase === right.phase
+    && left.status === right.status
+    && left.summary === right.summary;
+}