@vue-skuilder/db 0.1.34 → 0.1.36

package/dist/index.d.cts

@@ -478,8 +478,19 @@ declare class SessionController<TView = unknown> extends Loggable {
     /**
      * Request a mid-session replan. Re-runs the pipeline with current user state
      * and atomically replaces the newQ contents. Safe to call at any time during
-     * a session — if called while a replan is already in progress, returns the
-     * existing replan promise (no duplicate work).
+     * a session.
+     *
+     * Concurrency policy:
+     * - Two unhinted auto-replans never run in parallel; the second coalesces
+     *   into the first (returns the same promise).
+     * - A hint-bearing replan that arrives while another replan is in flight
+     *   is queued to run **after** the in-flight one rather than dropped.
+     *   This preserves caller intent (label, requireCards, excludeTags,
+     *   limit, minFollowUpCards) instead of silently discarding it. Without
+     *   queueing, a background auto-replan that started just before a
+     *   completion-triggered replan would clobber the queue with unhinted
+     *   results (e.g. surfacing another gpc-intro card right after one
+     *   completed, skipping the prescribed `c-wst-*` follow-up).
      *
      * Does NOT affect reviewQ or failedQ.
      *
@@ -491,6 +502,25 @@ declare class SessionController<TView = unknown> extends Loggable {
      * calls this to ensure newly-unlocked content appears in the session.
      */
     requestReplan(options?: ReplanOptions | ReplanHints): Promise<void>;
+    /**
+     * True when a requestReplan call carries caller intent that must not be
+     * silently dropped. Bare unhinted auto-replans (depletion / quality
+     * triggers in nextCard) return false and may coalesce.
+     */
+    private _replanHasIntent;
+    /**
+     * Body of a single replan: populate auto-excludes, stash hints on
+     * sources, log, then run the pipeline. Extracted so it can be invoked
+     * either immediately (no in-flight replan) or queued (chained after
+     * the in-flight one resolves).
+     *
+     * IMPORTANT: hint stash and the queue-state snapshot used to build
+     * excludeCards happen at *invocation* time, not at *queue* time. For a
+     * queued replan that means excludes reflect the state after the prior
+     * replan landed — which is what we want, since the prior replan's
+     * newQ.peek(0) is the imminent draw we need to exclude.
+     */
+    private _runReplan;
     /**
      * Normalise the requestReplan argument. Accepts either a ReplanOptions
      * object (new API) or a plain Record<string, unknown> (legacy callers

package/dist/index.d.ts

@@ -478,8 +478,19 @@ declare class SessionController<TView = unknown> extends Loggable {
     /**
      * Request a mid-session replan. Re-runs the pipeline with current user state
      * and atomically replaces the newQ contents. Safe to call at any time during
-     * a session — if called while a replan is already in progress, returns the
-     * existing replan promise (no duplicate work).
+     * a session.
+     *
+     * Concurrency policy:
+     * - Two unhinted auto-replans never run in parallel; the second coalesces
+     *   into the first (returns the same promise).
+     * - A hint-bearing replan that arrives while another replan is in flight
+     *   is queued to run **after** the in-flight one rather than dropped.
+     *   This preserves caller intent (label, requireCards, excludeTags,
+     *   limit, minFollowUpCards) instead of silently discarding it. Without
+     *   queueing, a background auto-replan that started just before a
+     *   completion-triggered replan would clobber the queue with unhinted
+     *   results (e.g. surfacing another gpc-intro card right after one
+     *   completed, skipping the prescribed `c-wst-*` follow-up).
      *
      * Does NOT affect reviewQ or failedQ.
      *
@@ -491,6 +502,25 @@ declare class SessionController<TView = unknown> extends Loggable {
      * calls this to ensure newly-unlocked content appears in the session.
      */
     requestReplan(options?: ReplanOptions | ReplanHints): Promise<void>;
+    /**
+     * True when a requestReplan call carries caller intent that must not be
+     * silently dropped. Bare unhinted auto-replans (depletion / quality
+     * triggers in nextCard) return false and may coalesce.
+     */
+    private _replanHasIntent;
+    /**
+     * Body of a single replan: populate auto-excludes, stash hints on
+     * sources, log, then run the pipeline. Extracted so it can be invoked
+     * either immediately (no in-flight replan) or queued (chained after
+     * the in-flight one resolves).
+     *
+     * IMPORTANT: hint stash and the queue-state snapshot used to build
+     * excludeCards happen at *invocation* time, not at *queue* time. For a
+     * queued replan that means excludes reflect the state after the prior
+     * replan landed — which is what we want, since the prior replan's
+     * newQ.peek(0) is the imminent draw we need to exclude.
+     */
+    private _runReplan;
     /**
      * Normalise the requestReplan argument. Accepts either a ReplanOptions
      * object (new API) or a plain Record<string, unknown> (legacy callers

package/dist/index.js

@@ -877,6 +877,7 @@ var PipelineDebugger_exports = {};
 __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
+  clearRunHistory: () => clearRunHistory,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -884,6 +885,9 @@ __export(PipelineDebugger_exports, {
 function registerPipelineForDebug(pipeline) {
   _activePipeline = pipeline;
 }
+function clearRunHistory() {
+  runHistory.length = 0;
+}
 function getOrigin(card) {
   const firstEntry = card.provenance[0];
   if (!firstEntry) return "unknown";
@@ -912,7 +916,7 @@ function parseCardElo(provenance) {
 }
 function buildRunReport(courseId, courseName, generatorName, generators, generatedCount, filters, allCards, selectedCards, userElo, hints) {
   const selectedIds = new Set(selectedCards.map((c) => c.cardId));
-  const cards = allCards.map((card) => ({
+  const toReport = (card) => ({
     cardId: card.cardId,
     courseId: card.courseId,
     origin: getOrigin(card),
@@ -922,7 +926,47 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
     provenance: card.provenance,
     tags: card.tags,
     selected: selectedIds.has(card.cardId)
-  }));
+  });
+  const selectedReported = [];
+  const nearMissReported = [];
+  const discardedTailCards = [];
+  let nonSelectedSeen = 0;
+  for (const card of allCards) {
+    if (selectedIds.has(card.cardId)) {
+      selectedReported.push(toReport(card));
+    } else if (nonSelectedSeen < DISCARDED_KEEP_TOP) {
+      nearMissReported.push(toReport(card));
+      nonSelectedSeen++;
+    } else {
+      discardedTailCards.push(card);
+    }
+  }
+  const cards = [...selectedReported, ...nearMissReported];
+  let discardedTail;
+  if (discardedTailCards.length > 0) {
+    let scoreMin = Infinity;
+    let scoreMax = -Infinity;
+    let eloMin = Infinity;
+    let eloMax = -Infinity;
+    let eloSeen = false;
+    for (const c of discardedTailCards) {
+      if (c.score < scoreMin) scoreMin = c.score;
+      if (c.score > scoreMax) scoreMax = c.score;
+      const elo = parseCardElo(c.provenance);
+      if (elo !== void 0) {
+        eloSeen = true;
+        if (elo < eloMin) eloMin = elo;
+        if (elo > eloMax) eloMax = elo;
+      }
+    }
+    const eloFragment = eloSeen ? `, ELO ${eloMin}\u2013${eloMax}` : "";
+    discardedTail = {
+      count: discardedTailCards.length,
+      scoreRange: [scoreMin, scoreMax],
+      eloRange: eloSeen ? [eloMin, eloMax] : void 0,
+      note: `${discardedTailCards.length} additional candidate(s) scored below the top ${DISCARDED_KEEP_TOP} near-misses and were not retained (score ${scoreMin.toExponential(2)}\u2013${scoreMax.toExponential(2)}${eloFragment}). Likely ELO-window pull remnants filtered out by hierarchy/lesson/priority gates.`
+    };
+  }
   const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === "review").length;
   const newSelected = selectedCards.filter((c) => getOrigin(c) === "new").length;
   return {
@@ -937,7 +981,8 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
     finalCount: selectedCards.length,
     reviewsSelected,
     newSelected,
-    cards
+    cards,
+    discardedTail
   };
 }
 function formatProvenance(provenance) {
@@ -973,6 +1018,44 @@ function printRunSummary(run) {
   );
   console.groupEnd();
 }
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+  return escapeHtml(s).replace(/"/g, "&quot;");
+}
+function copyTextToClipboard(text, btn) {
+  const done = () => {
+    if (!btn) return;
+    const orig = btn.textContent ?? "Copy";
+    btn.textContent = "Copied!";
+    btn.classList.add("copied");
+    setTimeout(() => {
+      btn.textContent = orig;
+      btn.classList.remove("copied");
+    }, 1200);
+  };
+  const fallback = () => {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    try {
+      document.execCommand("copy");
+    } catch (e) {
+      logger.warn(`[Pipeline Debug] Copy failed: ${e}`);
+    }
+    document.body.removeChild(ta);
+    done();
+  };
+  if (navigator.clipboard?.writeText) {
+    navigator.clipboard.writeText(text).then(done).catch(fallback);
+  } else {
+    fallback();
+  }
+}
 function renderUI() {
   if (!_uiContainer) return;
   const runs = runHistory;
@@ -1031,6 +1114,13 @@ function renderUI() {
     #sk-pipeline-debugger .close-btn { background: #dc3545; color: white; border: none; padding: 0.5rem 1rem; border-radius: 4px; cursor: pointer; }
     #sk-pipeline-debugger .search-box { margin-bottom: 1rem; width: 100%; padding: 0.5rem; border: 1px solid #ced4da; border-radius: 4px; }
     #sk-pipeline-debugger .provenance { font-size: 12px; color: #666; margin-top: 0.25rem; white-space: pre-wrap; font-family: monospace; background: #f8f9fa; padding: 0.5rem; border-radius: 4px; }
+    #sk-pipeline-debugger .run-label { display: inline-block; margin-top: 0.25rem; padding: 0.1rem 0.4rem; background: #fff3cd; color: #664d03; border-radius: 3px; font-family: monospace; font-size: 11px; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; vertical-align: bottom; }
+    #sk-pipeline-debugger .label-banner { display: inline-block; padding: 0.25rem 0.6rem; background: #fff3cd; color: #664d03; border-radius: 4px; font-family: monospace; font-size: 13px; margin: 0 0 0.75rem 0; }
+    #sk-pipeline-debugger .copy-btn { background: #0d6efd; color: white; border: none; padding: 0.25rem 0.6rem; border-radius: 3px; cursor: pointer; font-size: 12px; margin-left: 0.5rem; }
+    #sk-pipeline-debugger .copy-btn:hover { background: #0b5ed7; }
+    #sk-pipeline-debugger .copy-btn.copied { background: #198754; }
+    #sk-pipeline-debugger .section-head { display: flex; align-items: center; justify-content: space-between; margin-top: 1rem; }
+    #sk-pipeline-debugger .section-head h3 { margin: 0; }
   `;
   const runListHtml = runs.length === 0 ? '<div style="padding: 1rem;">No runs captured yet.</div>' : runs.map(
     (r, i) => `
@@ -1038,6 +1128,7 @@ function renderUI() {
           <strong>${r.timestamp.toLocaleTimeString()}</strong><br/>
           <small>${r.courseName || r.courseId.slice(0, 8)}</small><br/>
           <small>${r.finalCount} cards selected</small>
+          ${r.hints?._label ? `<br/><span class="run-label" title="${escapeAttr(r.hints._label)}">${escapeHtml(r.hints._label)}</span>` : ""}
         </div>
       `
   ).join("");
@@ -1046,11 +1137,13 @@ function renderUI() {
     const filteredCards = selectedRun.cards.filter(
       (c) => !_cardSearchQuery || c.cardId.toLowerCase().includes(_cardSearchQuery.toLowerCase())
     );
+    const labelText = selectedRun.hints?._label ?? "(no label)";
     detailsHtml = `
       <h2>Run: ${selectedRun.runId}</h2>
+      <div class="label-banner" title="${escapeAttr(labelText)}">${escapeHtml(labelText)}</div>
       <p>
-        <strong>Time:</strong> ${selectedRun.timestamp.toLocaleString()} | 
-        <strong>Course:</strong> ${selectedRun.courseName || selectedRun.courseId} | 
+        <strong>Time:</strong> ${selectedRun.timestamp.toLocaleString()} |
+        <strong>Course:</strong> ${selectedRun.courseName || selectedRun.courseId} |
         <strong>User ELO:</strong> ${selectedRun.userElo ?? "unknown"}
       </p>
 
@@ -1065,7 +1158,10 @@ function renderUI() {
       </table>
 
       ${selectedRun.hints ? `
-        <h3>Ephemeral Hints</h3>
+        <div class="section-head">
+          <h3>Ephemeral Hints</h3>
+          <button class="copy-btn" onclick="window.skuilder.pipeline._copyConfig('${selectedRun.runId}', this)">Copy config</button>
+        </div>
         <table>
           ${selectedRun.hints._label ? `<tr><th>Label</th><td>${selectedRun.hints._label}</td></tr>` : ""}
           ${selectedRun.hints.boostTags ? `<tr><th>Boost Tags</th><td><pre style="margin:0">${JSON.stringify(selectedRun.hints.boostTags, null, 2)}</pre></td></tr>` : ""}
@@ -1089,7 +1185,10 @@ function renderUI() {
         </tbody>
       </table>
 
-      <h3>Cards (${selectedRun.finalCount} selected / ${selectedRun.cards.length} total)</h3>
+      <div class="section-head">
+        <h3>Cards (${selectedRun.finalCount} selected / ${selectedRun.cards.length} total)</h3>
+        <button class="copy-btn" onclick="window.skuilder.pipeline._copyResults('${selectedRun.runId}', this)">Copy results</button>
+      </div>
       <input type="text" class="search-box" placeholder="Search Card ID..." value="${_cardSearchQuery}" oninput="window.skuilder.pipeline._setSearch(this.value)">
       
       <table>
@@ -1135,7 +1234,7 @@ function mountPipelineDebugger() {
   win.skuilder = win.skuilder || {};
   win.skuilder.pipeline = pipelineDebugAPI;
 }
-var _activePipeline, MAX_RUNS, runHistory, _uiContainer, _selectedRunIndex, _cardSearchQuery, pipelineDebugAPI;
+var _activePipeline, MAX_RUNS, runHistory, DISCARDED_KEEP_TOP, _uiContainer, _selectedRunIndex, _cardSearchQuery, pipelineDebugAPI;
 var init_PipelineDebugger = __esm({
   "src/core/navigators/PipelineDebugger.ts"() {
     "use strict";
@@ -1144,6 +1243,7 @@ var init_PipelineDebugger = __esm({
     _activePipeline = null;
     MAX_RUNS = 10;
     runHistory = [];
+    DISCARDED_KEEP_TOP = 25;
     _uiContainer = null;
     _selectedRunIndex = null;
     _cardSearchQuery = "";
@@ -1208,7 +1308,14 @@ var init_PipelineDebugger = __esm({
             return;
           }
         }
-        logger.info(`[Pipeline Debug] Card '${cardId}' not found in recent runs.`);
+        const runsWithTails = runHistory.filter((r) => r.discardedTail && r.discardedTail.count > 0);
+        if (runsWithTails.length > 0) {
+          logger.info(
+            `[Pipeline Debug] Card '${cardId}' not found in retained cards. ${runsWithTails.length} run(s) have discarded tails that were not retained \u2014 the card may have been a low-score candidate. See run.discardedTail for ranges.`
+          );
+        } else {
+          logger.info(`[Pipeline Debug] Card '${cardId}' not found in recent runs.`);
+        }
       },
       /**
        * Explain why reviews may or may not have been selected.
@@ -1513,6 +1620,50 @@ var init_PipelineDebugger = __esm({
         _cardSearchQuery = query;
         renderUI();
       },
+      /**
+       * Internal UI helpers
+       * @internal
+       */
+      _copyConfig(runId, btn) {
+        const run = runHistory.find((r) => r.runId === runId);
+        if (!run) return;
+        const payload = {
+          runId: run.runId,
+          timestamp: run.timestamp.toISOString(),
+          courseId: run.courseId,
+          courseName: run.courseName,
+          hints: run.hints ?? null
+        };
+        copyTextToClipboard(JSON.stringify(payload, null, 2), btn);
+      },
+      /**
+       * Internal UI helpers
+       * @internal
+       *
+       * Copies an "abridged" view of results: just the selected cards with their
+       * generator, origin, final score, and the top provenance reason. Designed
+       * for pasting into bug reports without flooding with full provenance.
+       */
+      _copyResults(runId, btn) {
+        const run = runHistory.find((r) => r.runId === runId);
+        if (!run) return;
+        const selected = run.cards.filter((c) => c.selected).sort((a, b) => b.finalScore - a.finalScore).map((c) => ({
+          cardId: c.cardId,
+          generator: c.generator,
+          origin: c.origin,
+          score: Number(c.finalScore.toFixed(3)),
+          topReason: c.provenance[0]?.reason ?? ""
+        }));
+        const payload = {
+          runId: run.runId,
+          label: run.hints?._label ?? null,
+          finalCount: run.finalCount,
+          newSelected: run.newSelected,
+          reviewsSelected: run.reviewsSelected,
+          selected
+        };
+        copyTextToClipboard(JSON.stringify(payload, null, 2), btn);
+      },
       /**
        * Show help.
        */
@@ -5822,12 +5973,12 @@ ${e.stack}` : JSON.stringify(e);
       async getWeightedCards(limit) {
         const u = await this._getCurrentUser();
         try {
-          const navigator = await this.createNavigator(u);
+          const navigator2 = await this.createNavigator(u);
           if (this._pendingHints) {
-            navigator.setEphemeralHints(this._pendingHints);
+            navigator2.setEphemeralHints(this._pendingHints);
             this._pendingHints = null;
           }
-          return navigator.getWeightedCards(limit);
+          return navigator2.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[courseDB] Error getting weighted cards: ${e}`);
           throw e;
@@ -8872,12 +9023,12 @@ var init_courseDB2 = __esm({
       }
       async getWeightedCards(limit) {
         try {
-          const navigator = await this.createNavigator(this.userDB);
+          const navigator2 = await this.createNavigator(this.userDB);
           if (this._pendingHints) {
-            navigator.setEphemeralHints(this._pendingHints);
+            navigator2.setEphemeralHints(this._pendingHints);
             this._pendingHints = null;
           }
-          return navigator.getWeightedCards(limit);
+          return navigator2.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[static/courseDB] Error getting weighted cards: ${e}`);
           throw e;
@@ -12912,10 +13063,12 @@ mountMixerDebugger();
 
 // src/study/SessionDebugger.ts
 init_logger();
+init_PipelineDebugger();
 var activeSession = null;
 var sessionHistory = [];
 var MAX_HISTORY = 5;
 function startSessionTracking(reviewQLength, newQLength, failedQLength) {
+  clearRunHistory();
   const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   activeSession = {
     sessionId,
@@ -13373,8 +13526,19 @@ var SessionController = class _SessionController extends Loggable {
   /**
    * Request a mid-session replan. Re-runs the pipeline with current user state
    * and atomically replaces the newQ contents. Safe to call at any time during
-   * a session — if called while a replan is already in progress, returns the
-   * existing replan promise (no duplicate work).
+   * a session.
+   *
+   * Concurrency policy:
+   * - Two unhinted auto-replans never run in parallel; the second coalesces
+   *   into the first (returns the same promise).
+   * - A hint-bearing replan that arrives while another replan is in flight
+   *   is queued to run **after** the in-flight one rather than dropped.
+   *   This preserves caller intent (label, requireCards, excludeTags,
+   *   limit, minFollowUpCards) instead of silently discarding it. Without
+   *   queueing, a background auto-replan that started just before a
+   *   completion-triggered replan would clobber the queue with unhinted
+   *   results (e.g. surfacing another gpc-intro card right after one
+   *   completed, skipping the prescribed `c-wst-*` follow-up).
    *
    * Does NOT affect reviewQ or failedQ.
    *
@@ -13390,10 +13554,55 @@ var SessionController = class _SessionController extends Loggable {
     if (opts.hints || opts.label || opts.limit) {
       this._depletionReplanAttempted = false;
     }
+    const hasIntent = this._replanHasIntent(opts);
     if (this._replanPromise) {
-      this.log("Replan already in progress, awaiting existing replan");
-      return this._replanPromise;
+      if (!hasIntent) {
+        this.log("Replan already in progress, coalescing unhinted auto-replan");
+        return this._replanPromise;
+      }
+      const labelTag = opts.label ? ` [${opts.label}]` : "";
+      this.log(
+        `Replan in progress; queueing hint-bearing replan${labelTag} behind in-flight run`
+      );
+      const inflight = this._replanPromise;
+      const queued = inflight.catch(() => void 0).then(() => this._runReplan(opts));
+      this._replanPromise = queued.finally(() => {
+        if (this._replanPromise === queued) this._replanPromise = null;
+      });
+      return queued;
     }
+    const run = this._runReplan(opts);
+    this._replanPromise = run.finally(() => {
+      if (this._replanPromise === run) this._replanPromise = null;
+    });
+    await run;
+  }
+  /**
+   * True when a requestReplan call carries caller intent that must not be
+   * silently dropped. Bare unhinted auto-replans (depletion / quality
+   * triggers in nextCard) return false and may coalesce.
+   */
+  _replanHasIntent(opts) {
+    if (opts.label) return true;
+    if (opts.limit !== void 0) return true;
+    if (opts.minFollowUpCards !== void 0) return true;
+    if (opts.mode && opts.mode !== "replace") return true;
+    if (opts.hints && Object.keys(opts.hints).length > 0) return true;
+    return false;
+  }
+  /**
+   * Body of a single replan: populate auto-excludes, stash hints on
+   * sources, log, then run the pipeline. Extracted so it can be invoked
+   * either immediately (no in-flight replan) or queued (chained after
+   * the in-flight one resolves).
+   *
+   * IMPORTANT: hint stash and the queue-state snapshot used to build
+   * excludeCards happen at *invocation* time, not at *queue* time. For a
+   * queued replan that means excludes reflect the state after the prior
+   * replan landed — which is what we want, since the prior replan's
+   * newQ.peek(0) is the imminent draw we need to exclude.
+   */
+  async _runReplan(opts) {
     if (!opts.hints) opts.hints = {};
     const hints = opts.hints;
     const excludeSet = new Set(hints.excludeCards ?? []);
@@ -13403,6 +13612,9 @@ var SessionController = class _SessionController extends Loggable {
     for (const rec of this._sessionRecord) {
       excludeSet.add(rec.card.card_id);
     }
+    if (this.newQ.length > 0) {
+      excludeSet.add(this.newQ.peek(0).cardID);
+    }
     hints.excludeCards = [...excludeSet];
     if (opts.hints) {
       const hintsWithLabel = opts.label ? { ...opts.hints, _label: opts.label } : opts.hints;
@@ -13418,12 +13630,7 @@ var SessionController = class _SessionController extends Loggable {
       this._minCardsGuarantee = Math.max(this._minCardsGuarantee, opts.minFollowUpCards);
       this.log(`[Replan] Card guarantee set to ${this._minCardsGuarantee}`);
     }
-    this._replanPromise = this._executeReplan(opts);
-    try {
-      await this._replanPromise;
-    } finally {
-      this._replanPromise = null;
-    }
+    await this._executeReplan(opts);
   }
   /**
    * Normalise the requestReplan argument. Accepts either a ReplanOptions