update policy and fix other issues

app/Services/StudentYearStatusService.php

@@ -72,6 +72,34 @@ class StudentYearStatusService
         ]);
     }
 
+    /**
+     * Mark students who existed in a source school year as returning in the target year.
+     *
+     * This is intentionally idempotent so school-year activation/closing and repair
+     * migrations can call it safely.
+     */
+    public function markReturningStudentsForTargetYear(string $sourceSchoolYear, string $targetSchoolYear): int
+    {
+        $sourceSchoolYear = trim($sourceSchoolYear);
+        $targetSchoolYear = trim($targetSchoolYear);
+
+        if (
+            ! preg_match('/^\d{4}-\d{4}$/', $sourceSchoolYear)
+            || ! preg_match('/^\d{4}-\d{4}$/', $targetSchoolYear)
+            || $sourceSchoolYear === $targetSchoolYear
+            || ! $this->db->tableExists('student_year_status')
+        ) {
+            return 0;
+        }
+
+        $studentIds = $this->returningStudentIds($sourceSchoolYear);
+        foreach ($studentIds as $studentId) {
+            $this->upsert($studentId, $targetSchoolYear, false);
+        }
+
+        return count($studentIds);
+    }
+
     /**
      * @param list<array<string, mixed>> $students
      */
@@ -144,6 +172,37 @@ class StudentYearStatusService
         return $flags;
     }
 
+    /**
+     * @return list<int>
+     */
+    private function returningStudentIds(string $sourceSchoolYear): array
+    {
+        $ids = [];
+
+        foreach (['student_year_status', 'student_class', 'enrollments'] as $table) {
+            if (! $this->db->tableExists($table) || ! $this->db->fieldExists('school_year', $table)) {
+                continue;
+            }
+
+            $rows = $this->db->table($table)
+                ->select('student_id')
+                ->where('school_year', $sourceSchoolYear)
+                ->where('student_id IS NOT NULL', null, false)
+                ->groupBy('student_id')
+                ->get()
+                ->getResultArray();
+
+            foreach ($rows as $row) {
+                $studentId = (int) ($row['student_id'] ?? 0);
+                if ($studentId > 0) {
+                    $ids[$studentId] = true;
+                }
+            }
+        }
+
+        return array_keys($ids);
+    }
+
     public function activeSchoolYear(): ?string
     {
         if ($this->db->tableExists('school_years')) {