@vue-skuilder/db 0.2.4 → 0.2.7

package/dist/index.mjs

@@ -849,6 +849,95 @@ var init_courseLookupDB = __esm({
   }
 });
 
+// src/core/navigators/diversityRerank.ts
+var diversityRerank_exports = {};
+__export(diversityRerank_exports, {
+  DIVERSITY_FLOOR: () => DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH: () => DIVERSITY_STRENGTH,
+  diversityRerank: () => diversityRerank
+});
+function diversityRerank(cards, opts = {}) {
+  const strength = opts.strength ?? DIVERSITY_STRENGTH;
+  const floor = opts.floor ?? DIVERSITY_FLOOR;
+  const n = cards.length;
+  if (n <= 1) return cards;
+  const df = /* @__PURE__ */ new Map();
+  for (const card of cards) {
+    for (const tag of card.tags ?? []) {
+      df.set(tag, (df.get(tag) ?? 0) + 1);
+    }
+  }
+  const idf = /* @__PURE__ */ new Map();
+  for (const [tag, freq] of df) {
+    idf.set(tag, Math.log(n / freq));
+  }
+  const remaining = [...cards];
+  const emittedCount = /* @__PURE__ */ new Map();
+  const out = [];
+  const repetitionLoad = (card) => {
+    let load = 0;
+    for (const tag of card.tags ?? []) {
+      const seen = emittedCount.get(tag);
+      if (seen) load += (idf.get(tag) ?? 0) * seen;
+    }
+    return load;
+  };
+  while (remaining.length > 0) {
+    let bestIdx = 0;
+    let bestValue = -Infinity;
+    let bestPenalty = 1;
+    let bestLoad = 0;
+    for (let i = 0; i < remaining.length; i++) {
+      const card = remaining[i];
+      const load = repetitionLoad(card);
+      const penalty = load > 0 ? Math.max(floor, 1 / (1 + strength * load)) : 1;
+      const value = card.score * penalty;
+      if (value > bestValue) {
+        bestValue = value;
+        bestIdx = i;
+        bestPenalty = penalty;
+        bestLoad = load;
+      }
+    }
+    const [picked] = remaining.splice(bestIdx, 1);
+    if (Number.isFinite(picked.score) && bestPenalty < 1) {
+      const newScore = picked.score * bestPenalty;
+      out.push({
+        ...picked,
+        score: newScore,
+        provenance: [
+          ...picked.provenance,
+          {
+            strategy: STRATEGY,
+            strategyId: STRATEGY_ID,
+            strategyName: STRATEGY_NAME,
+            action: "penalized",
+            score: newScore,
+            reason: `repeated tags (load ${bestLoad.toFixed(2)}) \u2192 \xD7${bestPenalty.toFixed(2)}`
+          }
+        ]
+      });
+    } else {
+      out.push(picked);
+    }
+    for (const tag of picked.tags ?? []) {
+      emittedCount.set(tag, (emittedCount.get(tag) ?? 0) + 1);
+    }
+  }
+  return out;
+}
+var DIVERSITY_STRENGTH, DIVERSITY_FLOOR, STRATEGY, STRATEGY_ID, STRATEGY_NAME;
+var init_diversityRerank = __esm({
+  "src/core/navigators/diversityRerank.ts"() {
+    "use strict";
+    DIVERSITY_STRENGTH = 0.6;
+    DIVERSITY_FLOOR = 0.3;
+    STRATEGY = "diversityRerank";
+    STRATEGY_ID = "DIVERSITY_RERANK";
+    STRATEGY_NAME = "Diversity Re-rank";
+  }
+});
+
 // src/core/navigators/PipelineDebugger.ts
 var PipelineDebugger_exports = {};
 __export(PipelineDebugger_exports, {
@@ -1917,12 +2006,13 @@ __export(elo_exports, {
   default: () => ELONavigator
 });
 import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
-var ELONavigator;
+var ELO_RELEVANCE_SIGMA, ELONavigator;
 var init_elo = __esm({
   "src/core/navigators/generators/elo.ts"() {
     "use strict";
     init_navigators();
     init_logger();
+    ELO_RELEVANCE_SIGMA = 300;
     ELONavigator = class extends ContentNavigator {
       /** Human-readable name for CardGenerator interface */
       name;
@@ -1962,8 +2052,8 @@ var init_elo = __esm({
         const scored = newCards.map((c) => {
           const cardElo = c.elo ?? 1e3;
           const distance = Math.abs(cardElo - userGlobalElo);
-          const rawScore = Math.max(0, 1 - distance / 500);
-          const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
+          const relevance = Math.exp(-((distance / ELO_RELEVANCE_SIGMA) ** 2));
+          const samplingKey = relevance * (0.5 + 0.5 * Math.random());
           return {
             cardId: c.cardID,
             courseId: c.courseID,
@@ -1975,7 +2065,7 @@ var init_elo = __esm({
                 strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
                 action: "generated",
                 score: samplingKey,
-                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`
+                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), relevance ${relevance.toFixed(3)}, key ${samplingKey.toFixed(3)}`
               }
             ]
           };
@@ -2043,7 +2133,7 @@ function shuffleInPlace(arr) {
 function pickTopByScore(cards, limit) {
   return [...cards].sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId)).slice(0, limit);
 }
-var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
+var DEFAULT_FRESHNESS_WINDOW, DEFAULT_MAX_DIRECT_PER_RUN, DEFAULT_MAX_SUPPORT_PER_RUN, DEFAULT_HIERARCHY_DEPTH, DEFAULT_MIN_COUNT, DEFAULT_PRACTICE_MIN_COUNT, DEFAULT_MAX_PRACTICE_PER_RUN, BASE_TARGET_SCORE, BASE_SUPPORT_SCORE, DISCOVERED_SUPPORT_SCORE, BASE_PRACTICE_SCORE, MAX_TARGET_MULTIPLIER, MAX_SUPPORT_MULTIPLIER, PRESCRIBED_DEBUG_VERSION, PrescribedCardsGenerator;
 var init_prescribed = __esm({
   "src/core/navigators/generators/prescribed.ts"() {
     "use strict";
@@ -2054,9 +2144,12 @@ var init_prescribed = __esm({
     DEFAULT_MAX_SUPPORT_PER_RUN = 3;
     DEFAULT_HIERARCHY_DEPTH = 2;
     DEFAULT_MIN_COUNT = 3;
+    DEFAULT_PRACTICE_MIN_COUNT = 3;
+    DEFAULT_MAX_PRACTICE_PER_RUN = 4;
     BASE_TARGET_SCORE = 1;
     BASE_SUPPORT_SCORE = 0.8;
     DISCOVERED_SUPPORT_SCORE = 12;
+    BASE_PRACTICE_SCORE = 1;
     MAX_TARGET_MULTIPLIER = 8;
     MAX_SUPPORT_MULTIPLIER = 4;
     PRESCRIBED_DEBUG_VERSION = "testversion-prescribed-v3";
@@ -2164,7 +2257,18 @@ var init_prescribed = __esm({
             courseId,
             emittedIds
           );
-          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards);
+          const practiceCards = this.buildPracticeCards({
+            group,
+            courseId,
+            emittedIds,
+            cardsByTag,
+            hierarchyConfigs,
+            userTagElo,
+            userGlobalElo,
+            activeIds,
+            seenIds
+          });
+          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
         }
         const hintSummary = this.buildSupportHintSummary(groupRuntimes);
         const hints = Object.keys(hintSummary.boostTags).length > 0 ? {
@@ -2192,6 +2296,7 @@ var init_prescribed = __esm({
         const surfacedByGroup = /* @__PURE__ */ new Map();
         for (const card of finalCards) {
           const prov = card.provenance[0];
+          if (prov?.reason.includes("mode=practice")) continue;
           const groupId = prov?.reason.match(/group=([^;]+)/)?.[1];
           const mode = prov?.reason.includes("mode=support") ? "supportIds" : "targetIds";
           if (!groupId) continue;
@@ -2261,7 +2366,12 @@ var init_prescribed = __esm({
               enabled: raw.hierarchyWalk?.enabled !== false,
               maxDepth: typeof raw.hierarchyWalk?.maxDepth === "number" ? raw.hierarchyWalk.maxDepth : DEFAULT_HIERARCHY_DEPTH
             },
-            retireOnEncounter: raw.retireOnEncounter !== false
+            retireOnEncounter: raw.retireOnEncounter !== false,
+            practiceTagPatterns: dedupe(
+              Array.isArray(raw.practiceTagPatterns) ? raw.practiceTagPatterns.filter((v) => typeof v === "string") : []
+            ),
+            practiceMinCount: typeof raw.practiceMinCount === "number" ? raw.practiceMinCount : DEFAULT_PRACTICE_MIN_COUNT,
+            maxPracticeCardsPerRun: typeof raw.maxPracticeCardsPerRun === "number" ? raw.maxPracticeCardsPerRun : DEFAULT_MAX_PRACTICE_PER_RUN
           })).filter((g) => g.targetCardIds.length > 0);
           return { groups };
         } catch {
@@ -2484,6 +2594,92 @@ var init_prescribed = __esm({
         }
         return cards;
       }
+      /**
+       * Emit drill cards for *unlocked-but-under-practiced* skills.
+       *
+       * For each course tag matching the group's `practiceTagPatterns` that is both
+       * unlocked (all hierarchy prerequisites met — i.e. the learner has been
+       * introduced to it) and under-practiced (per-tag attempt count below
+       * `practiceMinCount`), this resolves cards carrying that tag and emits them
+       * into the candidate pool. It exists because global-ELO retrieval
+       * systematically fails to fetch the (low-ELO) drill cards for a
+       * freshly-introduced skill — putting them in the pool here lets the pipeline's
+       * scoring + the durable per-skill boost order them. Ordering/emphasis is NOT
+       * this method's job; it only guarantees presence.
+       *
+       * Fully data-driven: the unlock relation comes from the hierarchy config and
+       * practice-status from per-tag ELO. No card-id or tag-namespace hard-coding.
+       */
+      buildPracticeCards(args) {
+        const {
+          group,
+          courseId,
+          emittedIds,
+          cardsByTag,
+          hierarchyConfigs,
+          userTagElo,
+          userGlobalElo,
+          activeIds,
+          seenIds
+        } = args;
+        const patterns = group.practiceTagPatterns ?? [];
+        if (patterns.length === 0) return [];
+        const practiceMinCount = group.practiceMinCount ?? DEFAULT_PRACTICE_MIN_COUNT;
+        const maxPractice = group.maxPracticeCardsPerRun ?? DEFAULT_MAX_PRACTICE_PER_RUN;
+        const practiceTags = [...cardsByTag.keys()].filter(
+          (tag) => patterns.some((p) => matchesTagPattern(tag, p)) && this.isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) && (userTagElo[tag]?.count ?? 0) < practiceMinCount
+        );
+        if (practiceTags.length === 0) return [];
+        const practiceCardIds = this.findDiscoveredSupportCards({
+          supportTags: practiceTags,
+          cardsByTag,
+          activeIds,
+          seenIds,
+          excludedIds: emittedIds,
+          limit: maxPractice
+        });
+        if (practiceCardIds.length === 0) return [];
+        logger.info(
+          `[Prescribed] Group '${group.id}' practice: ${practiceTags.length} unlocked under-practiced skill(s), emitting ${practiceCardIds.length} drill card(s)`
+        );
+        const cards = [];
+        for (const cardId of practiceCardIds) {
+          emittedIds.add(cardId);
+          cards.push({
+            cardId,
+            courseId,
+            score: BASE_PRACTICE_SCORE,
+            provenance: [
+              {
+                strategy: "prescribed",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-prescribed",
+                action: "generated",
+                score: BASE_PRACTICE_SCORE,
+                reason: `mode=practice;group=${group.id};underPracticedSkills=${practiceTags.length};practiceTags=${practiceTags.slice(0, 8).join("|")}${practiceTags.length > 8 ? "|\u2026" : ""};testversion=${PRESCRIBED_DEBUG_VERSION}`
+              }
+            ]
+          });
+        }
+        return cards;
+      }
+      /**
+       * True for a skill that was *gated and is now reached*: it has at least one
+       * declared hierarchy prerequisite set, and every set is fully satisfied by the
+       * learner's per-tag ELO. This deliberately EXCLUDES tags with no prerequisites
+       * — an ungated tag was never "introduced" in the curricular sense, so it isn't
+       * a post-intro drill target (e.g. whole-word spelling tags that share the
+       * `gpc:exercise:*` prefix but have no intro gate). Those are left to normal
+       * ELO retrieval. This is the precise population the retrieval gap strands:
+       * just-unlocked, low-ELO skills.
+       */
+      isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) {
+        const prereqSets = hierarchyConfigs.map((hierarchy) => hierarchy.prerequisites[tag]).filter((prereqs) => Array.isArray(prereqs) && prereqs.length > 0);
+        if (prereqSets.length === 0) return false;
+        return prereqSets.every(
+          (prereqs) => prereqs.every((pr) => this.isPrerequisiteMet(pr, userTagElo[pr.tag], userGlobalElo))
+        );
+      }
       findSupportCardsByTags(group, tagsByCard, supportTags) {
         if (supportTags.length === 0) {
           return [];
@@ -4278,7 +4474,7 @@ function logResultCards(cards) {
   for (let i = 0; i < cards.length; i++) {
     const c = cards[i];
     const tags = c.tags?.slice(0, 3).join(", ") || "";
-    const filters = c.provenance.filter((p) => p.strategy === "hierarchyDefinition" || p.strategy === "priorityDefinition" || p.strategy === "interferenceFilter" || p.strategy === "letterGating" || p.strategy === "ephemeralHint").map((p) => {
+    const filters = c.provenance.filter((p) => p.strategy === "hierarchyDefinition" || p.strategy === "priorityDefinition" || p.strategy === "interferenceFilter" || p.strategy === "letterGating" || p.strategy === "ephemeralHint" || p.strategy === "diversityRerank").map((p) => {
       const arrow = p.action === "boosted" ? "\u2191" : p.action === "penalized" ? "\u2193" : "=";
       return `${p.strategyName}${arrow}${p.score.toFixed(2)}`;
     }).join(" | ");
@@ -4309,6 +4505,7 @@ var init_Pipeline = __esm({
     init_logger();
     init_orchestration();
     init_PipelineDebugger();
+    init_diversityRerank();
     VERBOSE_RESULTS = true;
     Pipeline = class extends ContentNavigator {
       generator;
@@ -4482,6 +4679,7 @@ var init_Pipeline = __esm({
           this._ephemeralHints = null;
           cards = this.applyHints(cards, hints, allCardsBeforeFiltering);
         }
+        cards = diversityRerank(cards);
         cards.sort((a, b) => b.score - a.score);
         const tFilter = performance.now();
         const result = cards.slice(0, limit);
@@ -5050,6 +5248,7 @@ var init_3 = __esm({
       "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
       "./PipelineDebugger.ts": () => Promise.resolve().then(() => (init_PipelineDebugger(), PipelineDebugger_exports)),
       "./defaults.ts": () => Promise.resolve().then(() => (init_defaults(), defaults_exports)),
+      "./diversityRerank.ts": () => Promise.resolve().then(() => (init_diversityRerank(), diversityRerank_exports)),
       "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
       "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
       "./filters/hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
@@ -5075,9 +5274,12 @@ var init_3 = __esm({
 var navigators_exports = {};
 __export(navigators_exports, {
   ContentNavigator: () => ContentNavigator,
+  DIVERSITY_FLOOR: () => DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH: () => DIVERSITY_STRENGTH,
   NavigatorRole: () => NavigatorRole,
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
+  diversityRerank: () => diversityRerank,
   getCardOrigin: () => getCardOrigin,
   getRegisteredNavigator: () => getRegisteredNavigator,
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
@@ -5161,6 +5363,7 @@ var navigatorRegistry, Navigators, NavigatorRole, NavigatorRoles, ContentNavigat
 var init_navigators = __esm({
   "src/core/navigators/index.ts"() {
     "use strict";
+    init_diversityRerank();
     init_PipelineDebugger();
     init_logger();
     init_();
@@ -11220,8 +11423,17 @@ var ItemQueue = class {
    * Merge new items into the front of the queue, skipping duplicates.
    * Used by additive replans to inject high-quality candidates without
    * discarding the existing queue contents.
+   *
+   * `forceFrontIds` carries the mandatory (`+INF`) cards in this batch — a
+   * durable `requireCard`/`requireTag` re-asserted by every replan. An ordinary
+   * duplicate is left in place (skip), but a mandatory one that's *already*
+   * queued is pulled out of its current slot so it rejoins at the front in batch
+   * order. Without this, an additive merge unshifts fresh non-required cards
+   * ahead of an already-present required card, steadily burying it until it never
+   * gets drawn — defeating the "must appear" guarantee. Returns the count of
+   * genuinely new cards added (re-fronted duplicates are not counted).
    */
-  mergeToFront(items, cardIdExtractor) {
+  mergeToFront(items, cardIdExtractor, forceFrontIds) {
     let added = 0;
     const toInsert = [];
     for (const item of items) {
@@ -11230,6 +11442,11 @@ var ItemQueue = class {
         this.seenCardIds.push(cardId);
         toInsert.push(item);
         added++;
+      } else if (forceFrontIds?.has(cardId)) {
+        const idx = this.q.findIndex((qi) => cardIdExtractor(qi) === cardId);
+        if (idx >= 0) {
+          toInsert.push(...this.q.splice(idx, 1));
+        }
       }
     }
     this.q.unshift(...toInsert);
@@ -13071,7 +13288,15 @@ var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834"
 var spinnerFrame = 0;
 var overlayEl = null;
 var pollHandle = null;
-var expanded = { reviewQ: false, newQ: false, failedQ: false };
+var lastSnapshot = null;
+var copyFlashUntil = 0;
+var minified = false;
+var expanded = {
+  reviewQ: false,
+  newQ: false,
+  failedQ: false,
+  drawn: false
+};
 function toggleSessionOverlay() {
   if (typeof document === "undefined") {
     logger.info("[Session Overlay] No DOM available (non-browser host); overlay unavailable.");
@@ -13086,6 +13311,7 @@ function toggleSessionOverlay() {
   }
 }
 function mount() {
+  minified = false;
   overlayEl = document.createElement("div");
   overlayEl.id = OVERLAY_ID;
   Object.assign(overlayEl.style, {
@@ -13124,11 +13350,23 @@ function render() {
   spinnerFrame++;
   const ctrl = getActiveController();
   if (!ctrl) {
-    overlayEl.innerHTML = headerHtml() + `<div style="opacity:.65">No active session.</div>`;
+    lastSnapshot = null;
+    overlayEl.innerHTML = headerHtml() + (minified ? "" : `<div style="opacity:.65">No active session.</div>`);
+    attachHandlers();
     return;
   }
   const s = ctrl.getDebugSnapshot();
-  overlayEl.innerHTML = headerHtml() + replanHtml(s) + metaHtml(s) + hintsHtml(s.sessionHints) + queueHtml("reviewQ", "reviewQ", s.reviewQ) + queueHtml("newQ", "newQ", s.newQ) + queueHtml("failedQ", "failedQ", s.failedQ);
+  lastSnapshot = s;
+  if (minified) {
+    overlayEl.innerHTML = headerHtml();
+    attachHandlers();
+    return;
+  }
+  overlayEl.innerHTML = headerHtml() + replanHtml(s) + metaHtml(s) + hintsHtml(s.sessionHints) + queueHtml("reviewQ", "reviewQ", s.reviewQ) + queueHtml("newQ", "newQ", s.newQ) + queueHtml("failedQ", "failedQ", s.failedQ) + drawnHtml("drawn", s.drawnCards);
+  attachHandlers();
+}
+function attachHandlers() {
+  if (!overlayEl) return;
   overlayEl.querySelectorAll("[data-q]").forEach((el) => {
     el.onclick = () => {
       const key = el.dataset.q;
@@ -13137,9 +13375,45 @@ function render() {
       render();
     };
   });
+  const copyBtn = overlayEl.querySelector("[data-copy]");
+  if (copyBtn) {
+    copyBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      copySnapshot();
+    };
+  }
+  const minBtn = overlayEl.querySelector("[data-min]");
+  if (minBtn) {
+    minBtn.onclick = (ev) => {
+      ev.stopPropagation();
+      minified = !minified;
+      render();
+    };
+  }
+}
+function copySnapshot() {
+  const text = snapshotToText(lastSnapshot);
+  const flash = () => {
+    copyFlashUntil = Date.now() + 1200;
+    render();
+  };
+  const clip = typeof navigator !== "undefined" ? navigator.clipboard : void 0;
+  if (clip?.writeText) {
+    clip.writeText(text).then(flash, (err) => {
+      logger.warn(`[Session Overlay] Clipboard write failed: ${String(err)}`);
+    });
+  } else {
+    logger.info(`[Session Overlay] Clipboard unavailable; snapshot follows:
+${text}`);
+  }
 }
 function headerHtml() {
-  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:4px">\u2699 SessionController</div>`;
+  const flashing = Date.now() < copyFlashUntil;
+  const btnLabel = flashing ? "\u2713 copied" : "\u2398 copy";
+  const btnColor = flashing ? "#86efac" : "#93c5fd";
+  const copyBtn = `<span data-copy style="cursor:pointer;float:right;font-weight:400;color:${btnColor};border:1px solid currentColor;border-radius:4px;padding:0 4px;line-height:1.3">${btnLabel}</span>`;
+  const minBtn = `<span data-min title="${minified ? "Restore" : "Minify"}" style="cursor:pointer;float:right;font-weight:400;color:#93c5fd;border:1px solid currentColor;border-radius:4px;padding:0 5px;margin-right:4px;line-height:1.3">${minified ? "\u25A2" : "\u2014"}</span>`;
+  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:${minified ? 0 : 4}px">${copyBtn}${minBtn}\u2699 SessionController</div>`;
 }
 function replanHtml(s) {
   if (!s.replanActive) {
@@ -13182,22 +13456,98 @@ function hintsHtml(h) {
 }
 function queueHtml(key, label, q) {
   const collapsible = q.length > INLINE_THRESHOLD;
-  const isOpen = !collapsible || expanded[key];
+  const isOpen = collapsible && expanded[key];
   const caret = collapsible ? expanded[key] ? "\u25BE " : "\u25B8 " : "";
   const drawn = q.dequeueCount ? ` <span style="opacity:.5">drawn ${q.dequeueCount}</span>` : "";
   const titleStyle = collapsible ? "cursor:pointer;color:#f9a8d4" : "color:#f9a8d4";
   const titleAttr = collapsible ? ` data-q="${key}"` : "";
   const title = `<div${titleAttr} style="${titleStyle}">${caret}${label}: ${q.length}${drawn}</div>`;
-  let body = "";
-  if (isOpen && q.cards.length) {
-    body = `<ol style="margin:2px 0 6px 0;padding-left:20px">` + q.cards.map((c) => `<li style="white-space:nowrap">${esc(c)}</li>`).join("") + `</ol>`;
-  } else if (!q.cards.length) {
-    body = `<div style="margin:1px 0 6px 6px;opacity:.5">empty</div>`;
-  } else {
-    body = `<div style="margin:1px 0 6px 6px;opacity:.55">(${q.length} cards \u2014 click to expand)</div>`;
+  if (!q.cards.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">empty</div>`;
+  }
+  const shown = isOpen ? q.cards : q.cards.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = q.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+  let body = `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">` + shown.map((c) => `<li style="white-space:nowrap">${esc(c)}</li>`).join("") + `</ol>`;
+  if (collapsible) {
+    const footer = isOpen ? "\u25BE show less" : `\u2026 +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
   }
   return title + body;
 }
+function outcomeGlyph(correct) {
+  if (correct === true) return `<span style="color:#86efac">\u2713</span>`;
+  if (correct === false) return `<span style="color:#fca5a5">\u2717</span>`;
+  return `<span style="opacity:.5">\xB7</span>`;
+}
+function drawnHtml(key, drawn) {
+  const collapsible = drawn.length > INLINE_THRESHOLD;
+  const isOpen = collapsible && expanded[key];
+  const caret = collapsible ? expanded[key] ? "\u25BE " : "\u25B8 " : "";
+  const titleStyle = collapsible ? "cursor:pointer;color:#c4b5fd" : "color:#c4b5fd";
+  const titleAttr = collapsible ? ` data-q="${key}"` : "";
+  const title = `<div${titleAttr} style="${titleStyle}">${caret}drawn: ${drawn.length}</div>`;
+  if (!drawn.length) {
+    return title + `<div style="margin:1px 0 6px 6px;opacity:.5">none yet</div>`;
+  }
+  const shown = isOpen ? drawn : drawn.slice(0, INLINE_THRESHOLD);
+  const hiddenCount = drawn.length - shown.length;
+  const listMarginBottom = collapsible ? 2 : 6;
+  const rows = shown.map((d) => {
+    const retries = d.attempts > 1 ? `<span style="opacity:.5"> \xD7${d.attempts}</span>` : "";
+    const time = `<span style="opacity:.45"> ${Math.round(d.timeSpentMs / 100) / 10}s</span>`;
+    return `<li style="white-space:nowrap">${outcomeGlyph(d.correct)} ${esc(d.cardID)}<span style="opacity:.5"> [${esc(d.status)}]</span>${retries}${time}</li>`;
+  }).join("");
+  let body = `<ol style="margin:2px 0 ${listMarginBottom}px 0;padding-left:20px">${rows}</ol>`;
+  if (collapsible) {
+    const footer = isOpen ? "\u25BE show less" : `\u2026 +${hiddenCount} more`;
+    body += `<div data-q="${key}" style="cursor:pointer;margin:0 0 6px 20px;opacity:.6">${footer}</div>`;
+  }
+  return title + body;
+}
+function snapshotToText(s) {
+  if (!s) return "SessionController \u2014 no active session.";
+  const lines = [];
+  lines.push("=== SessionController ===");
+  lines.push(`time ${formatTime(s.secondsRemaining)}`);
+  if (s.hasCardGuarantee) lines.push(`guarantee: ${s.minCardsGuarantee}`);
+  lines.push(`well-indicated left: ${s.wellIndicatedRemaining}`);
+  lines.push(`current: ${s.currentCard ?? "\u2014"}`);
+  lines.push(
+    s.replanActive ? `replan: ACTIVE [${s.replanLabel ?? "(auto)"}]` : "replan: idle"
+  );
+  lines.push("");
+  lines.push("sessionHints:");
+  const h = s.sessionHints;
+  const hintParts = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length)
+      hintParts.push(`  boost: ${Object.entries(h.boostTags).map(([k, v]) => `${k}\xD7${v}`).join(", ")}`);
+    if (h.boostCards && Object.keys(h.boostCards).length)
+      hintParts.push(`  boostCards: ${Object.entries(h.boostCards).map(([k, v]) => `${k}\xD7${v}`).join(", ")}`);
+    if (h.requireCards?.length) hintParts.push(`  require: ${h.requireCards.join(", ")}`);
+    if (h.requireTags?.length) hintParts.push(`  requireTags: ${h.requireTags.join(", ")}`);
+    if (h.excludeTags?.length) hintParts.push(`  exclude: ${h.excludeTags.join(", ")}`);
+    if (h.excludeCards?.length) hintParts.push(`  excludeCards: ${h.excludeCards.join(", ")}`);
+  }
+  lines.push(hintParts.length ? hintParts.join("\n") : "  none");
+  const queueText = (label, q) => {
+    lines.push("");
+    lines.push(`${label}: ${q.length} (drawn ${q.dequeueCount})`);
+    q.cards.forEach((c, i) => lines.push(`  ${i + 1}. ${c}`));
+  };
+  queueText("reviewQ", s.reviewQ);
+  queueText("newQ", s.newQ);
+  queueText("failedQ", s.failedQ);
+  lines.push("");
+  lines.push(`drawn: ${s.drawnCards.length}`);
+  s.drawnCards.forEach((d, i) => {
+    const mark = d.correct === true ? "\u2713" : d.correct === false ? "\u2717" : "\xB7";
+    const time = `${Math.round(d.timeSpentMs / 100) / 10}s`;
+    lines.push(`  ${i + 1}. ${mark} ${d.cardID} [${d.status}] \xD7${d.attempts} ${time}`);
+  });
+  return lines.join("\n");
+}
 function formatTime(totalSeconds) {
   const s = Math.max(0, Math.round(totalSeconds));
   const m = Math.floor(s / 60);
@@ -13567,6 +13917,21 @@ var SessionController = class _SessionController extends Loggable {
    * recomputed per-run in `_runReplan` and would otherwise go stale.
    */
   _sessionHints = null;
+  /**
+   * Card IDs that have been *served* (drawn/consumed) this session. Populated
+   * at the single consumption choke-point (removeItemFromQueue), so it reflects
+   * a draw the instant it happens — earlier than `_sessionRecord`, which only
+   * lands once the card is *responded to*.
+   *
+   * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+   * card shown once must never re-enter newQ this session. This is the general
+   * guard against re-presentation — including the case where a replan in flight
+   * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+   * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+   * legitimately recur and are tracked by their own queues, so this only gates
+   * `new`-origin candidates.
+   */
+  _servedCardIds = /* @__PURE__ */ new Set();
   /**
    * Consumer-supplied hooks invoked after each question response is processed.
    * Seeded from constructor options (threaded from
@@ -13776,6 +14141,7 @@ var SessionController = class _SessionController extends Loggable {
     if (opts.mode && opts.mode !== "replace") return true;
     if (opts.hints && Object.keys(opts.hints).length > 0) return true;
     if (opts.sessionHints !== void 0) return true;
+    if (opts.mergeSessionHints !== void 0) return true;
     return false;
   }
   /**
@@ -13811,6 +14177,10 @@ var SessionController = class _SessionController extends Loggable {
         `[Replan] Session hints ${opts.sessionHints ? "set" : "cleared"}: ${JSON.stringify(opts.sessionHints)}`
       );
     }
+    if (opts.mergeSessionHints !== void 0) {
+      this._sessionHints = mergeHints2([this._sessionHints, opts.mergeSessionHints]) ?? null;
+      this.log(`[Replan] Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+    }
     this._applyHintsToSources(opts.hints, opts.label);
     const labelTag = opts.label ? ` [${opts.label}]` : "";
     this.log(
@@ -13863,6 +14233,16 @@ var SessionController = class _SessionController extends Loggable {
       }
       return { length: q.length, dequeueCount: q.dequeueCount, cards };
     };
+    const drawnCards = this._sessionRecord.map((r) => {
+      const last = r.records[r.records.length - 1];
+      return {
+        cardID: r.item.cardID,
+        status: r.item.status,
+        attempts: r.records.length,
+        correct: last && isQuestionRecord(last) ? last.isCorrect : null,
+        timeSpentMs: r.records.reduce((sum, rec) => sum + rec.timeSpent, 0)
+      };
+    });
     return {
       secondsRemaining: this.secondsRemaining,
       hasCardGuarantee: this.hasCardGuarantee,
@@ -13874,7 +14254,8 @@ var SessionController = class _SessionController extends Loggable {
       replanLabel: this._activeReplanLabel,
       reviewQ: describe(this.reviewQ),
       newQ: describe(this.newQ),
-      failedQ: describe(this.failedQ)
+      failedQ: describe(this.failedQ),
+      drawnCards
     };
   }
   /**
@@ -14183,7 +14564,16 @@ var SessionController = class _SessionController extends Loggable {
       mixedWeighted
     );
     const reviewWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "review").slice(0, this._initialReviewCap);
-    const newWeighted = mixedWeighted.filter((w) => getCardOrigin(w) === "new").slice(0, newLimit);
+    const newCandidates = mixedWeighted.filter(
+      (w) => getCardOrigin(w) === "new" && !this._servedCardIds.has(w.cardId)
+    );
+    const mandatoryWeighted = newCandidates.filter((w) => w.score === Number.POSITIVE_INFINITY);
+    const optionalWeighted = newCandidates.filter((w) => w.score !== Number.POSITIVE_INFINITY);
+    const newWeighted = [
+      ...mandatoryWeighted,
+      ...optionalWeighted.slice(0, Math.max(0, newLimit - mandatoryWeighted.length))
+    ];
+    const mandatoryIds = new Set(mandatoryWeighted.map((w) => w.cardId));
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
     let report = replan ? "Replan content:\n" : "Mixed content session created with:\n";
     if (!replan) {
@@ -14218,7 +14608,7 @@ var SessionController = class _SessionController extends Loggable {
 `;
     }
     if (additive) {
-      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID);
+      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID, mandatoryIds);
       report += `Additive merge: ${added} new cards added to front of newQ
 `;
     } else if (replan) {
@@ -14320,7 +14710,7 @@ var SessionController = class _SessionController extends Loggable {
       this.log(
         `[AutoReplan:depletion] newQ has ${this.newQ.length} card(s) (${otherContent} in other queues) with ${this._secondsRemaining}s remaining. Triggering background replan.`
       );
-      void this.requestReplan({ label: "auto:depletion" });
+      void this.requestReplan({ label: "auto:depletion", mode: "merge" });
     }
     const REPLAN_BUFFER = 3;
     if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
@@ -14461,6 +14851,8 @@ var SessionController = class _SessionController extends Loggable {
    * Remove an item from its source queue after consumption by nextCard().
    */
   removeItemFromQueue(item) {
+    this._clearDurableRequirement(item.cardID);
+    this._servedCardIds.add(item.cardID);
     if (this.reviewQ.peek(0)?.cardID === item.cardID) {
       this.reviewQ.dequeue((queueItem) => queueItem.cardID);
     } else if (this.newQ.peek(0)?.cardID === item.cardID) {
@@ -14472,6 +14864,27 @@ var SessionController = class _SessionController extends Loggable {
       this.failedQ.dequeue((queueItem) => queueItem.cardID);
     }
   }
+  /**
+   * Remove a satisfied card ID from the durable session-hint `requireCards`
+   * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+   * the card was not a durable requirement.
+   *
+   * Matches literal IDs only: a glob/pattern requirement (which may stand for
+   * several cards) is NOT considered satisfied by a single draw and is left in
+   * place — durable patterns are the caller's responsibility, one-shot `hints`
+   * remain the right tool for them.
+   */
+  _clearDurableRequirement(cardID) {
+    const req = this._sessionHints?.requireCards;
+    if (!req || req.length === 0) return;
+    const next = req.filter((id) => id !== cardID);
+    if (next.length === req.length) return;
+    this._sessionHints = {
+      ...this._sessionHints,
+      requireCards: next.length > 0 ? next : void 0
+    };
+    this.log(`[Replan] Durable requirement satisfied & cleared on draw: ${cardID}`);
+  }
   /**
    * End the session and record learning outcomes.
    *
@@ -14526,6 +14939,8 @@ export {
   ContentNavigator,
   CouchDBToStaticPacker,
   CourseLookup,
+  DIVERSITY_FLOOR,
+  DIVERSITY_STRENGTH,
   DocType,
   DocTypePrefixes,
   ENV,
@@ -14551,6 +14966,7 @@ export {
   computeSpread,
   computeStrategyGradient,
   createOrchestrationContext,
+  diversityRerank,
   docIsDeleted,
   endSessionTracking,
   ensureAppDataDirectory,