feat(api): add structured schedule plan with topics, problems, gate, sweep and reserved problem handling

apps/api/src/gate.ts

@@ -2,21 +2,27 @@
  * Saturday review issue: created at midnight ET so the 8 AM digest can link
  * to it; scored when the issue closes (webhook).
  *
- * The gate half is a topic-blind quiz — one unsolved optional problem per
- * topic scheduled this week (which is why daily drills only draw from
- * earlier weeks). The recap half is generated data, deliberately NOT a task
- * list: the week's solved problems are already scheduled by the +3/+7 ladder,
- * and re-assigning them on Saturday would be massed practice.
+ * The gate half is a topic-blind quiz. When the plan fixes the set
+ * (`gate` in data/schedule.json) that list IS the gate, verbatim — every
+ * number must be a catalog problem, or the issue is not created, because a
+ * `/done` on an uncatalogued number can never be logged. Otherwise the set
+ * is sampled: one unsolved optional problem per topic scheduled this week
+ * (which is why daily drills only draw from earlier weeks), never one the
+ * plan has reserved. The recap half is generated data, deliberately NOT a
+ * task list: the week's solved problems are already scheduled by the +3/+7
+ * ladder, and re-assigning them on Saturday would be massed practice.
  *
  * Label is `review` (the retired Actions system owned `gate`). Creation is
- * idempotent by week; deferred Hards never appear.
+ * idempotent by week; deferred Hards never appear in a sampled set.
  */
 import {
   type ProblemRow,
+  RESERVED,
   type Result,
   SCHEDULE,
   campaignWeek,
   isoWeek,
+  lookupProblems,
   rng,
   sample,
   streak,
@@ -32,7 +38,7 @@ function capitalized(difficulty: string): string {
   return difficulty[0]!.toUpperCase() + difficulty.slice(1);
 }
 
-/** Unsolved problems of a topic in a set — never attempted, never drilled. */
+/** Unsolved problems of a topic in a set — never attempted, drilled, or reserved. */
 async function freshPool(db: D1Database, topic: number, set: string): Promise<ProblemRow[]> {
   const { results } = await db
     .prepare(
@@ -44,7 +50,7 @@ async function freshPool(db: D1Database, topic: number, set: string): Promise<Pr
     )
     .bind(topic, set)
     .all<ProblemRow>();
-  return results;
+  return results.filter((p) => !RESERVED.has(p.lc_number));
 }
 
 export interface CreateReport {
@@ -67,40 +73,52 @@ export async function createReviewIssue(env: Env, gh: GitHub, date: string): Pro
     return { created: false, issue: existing.issue, reason: `${title} exists (#${existing.issue})` };
   }
 
-  // Topics scheduled this week; review-only weeks (Sep 23 onward) sample
-  // across every topic that still has unsolved optional problems.
-  let topics = Object.entries(SCHEDULE)
-    .filter(([d]) => campaignWeek(d) === week)
-    .sort(([a], [b]) => (a < b ? -1 : 1))
-    .map(([, t]) => t);
-  if (topics.length === 0) {
-    const { results } = await db
-      .prepare(
-        `SELECT DISTINCT topic_issue AS t FROM problems
-         WHERE set_label = 'optional' AND stage = 'new'
-           AND lc_number NOT IN (SELECT lc_number FROM drill_pool_used)
-         ORDER BY topic_issue`,
-      )
-      .all<{ t: number }>();
-    topics = sample(results.map((r) => r.t), MAX_GATE_PROBLEMS, rng(`gate-topics-${iso}`)).sort(
-      (a, b) => a - b,
-    );
-  }
-  if (topics.length === 0) return { created: false, reason: "no topics with unsolved pools" };
-
-  const random = rng(`gate-${iso}`);
+  // The plan's fixed set wins; otherwise sample this week's topics, and in a
+  // week without topics, across every topic that still has an unsolved pool.
   const picks: { p: ProblemRow; fallback: boolean }[] = [];
-  for (const topic of topics) {
-    const optional = await freshPool(db, topic, "optional");
-    if (optional.length > 0) {
-      picks.push({ p: sample(optional, 1, random)[0]!, fallback: false });
-      continue;
+  const planned = SCHEDULE[date]?.gate;
+  if (planned) {
+    const { rows, missing } = await lookupProblems(db, planned);
+    if (missing.length) {
+      return {
+        created: false,
+        reason: `planned gate names problems outside the catalog: LC ${missing.join(", LC ")}`,
+      };
     }
-    const core = await freshPool(db, topic, "core");
-    if (core.length > 0) picks.push({ p: sample(core, 1, random)[0]!, fallback: true });
-    // Both pools exhausted: the topic is fully solved; nothing to quiz.
+    picks.push(...rows.map((p) => ({ p, fallback: false })));
+  } else {
+    let topics = Object.entries(SCHEDULE)
+      .filter(([d]) => campaignWeek(d) === week)
+      .sort(([a], [b]) => (a < b ? -1 : 1))
+      .flatMap(([, day]) => day.topics ?? []);
+    if (topics.length === 0) {
+      const { results } = await db
+        .prepare(
+          `SELECT DISTINCT topic_issue AS t FROM problems
+           WHERE set_label = 'optional' AND stage = 'new'
+             AND lc_number NOT IN (SELECT lc_number FROM drill_pool_used)
+           ORDER BY topic_issue`,
+        )
+        .all<{ t: number }>();
+      topics = sample(results.map((r) => r.t), MAX_GATE_PROBLEMS, rng(`gate-topics-${iso}`)).sort(
+        (a, b) => a - b,
+      );
+    }
+    if (topics.length === 0) return { created: false, reason: "no topics with unsolved pools" };
+
+    const random = rng(`gate-${iso}`);
+    for (const topic of topics) {
+      const optional = await freshPool(db, topic, "optional");
+      if (optional.length > 0) {
+        picks.push({ p: sample(optional, 1, random)[0]!, fallback: false });
+        continue;
+      }
+      const core = await freshPool(db, topic, "core");
+      if (core.length > 0) picks.push({ p: sample(core, 1, random)[0]!, fallback: true });
+      // Both pools exhausted: the topic is fully solved; nothing to quiz.
+    }
+    if (picks.length === 0) return { created: false, reason: `every pool for week ${week} is exhausted` };
   }
-  if (picks.length === 0) return { created: false, reason: `every pool for week ${week} is exhausted` };
 
   // Recap: everything attempted this week, plus streak — data, not tasks.
   const monday = weekMonday(date);
@@ -154,7 +172,7 @@ export async function createReviewIssue(env: Env, gh: GitHub, date: string): Pro
 
   const milestone = await db
     .prepare("SELECT milestone FROM topics WHERE issue = ? AND milestone IS NOT NULL")
-    .bind(topics[0])
+    .bind(picks[0]!.p.topic_issue)
     .first<{ milestone: number }>();
 
   const created = (await gh.rest(`/repos/${gh.repo}/issues`, {