@vue-skuilder/db 0.1.34 → 0.1.36

package/dist/core/index.d.cts

@@ -364,6 +364,19 @@ interface PipelineRunReport {
     finalCount: number;
     reviewsSelected: number;
     newSelected: number;
+    /**
+     * Card data for inspection.
+     *
+     * To keep the in-memory ring buffer small, this contains:
+     *   - All selected cards (the actual session output).
+     *   - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
+     *     useful for understanding "near misses" and filter behavior.
+     *
+     * The remaining low-score tail of the candidate pool (mostly ELO-window
+     * pull remnants that filters scored down) is summarized in `discardedTail`
+     * rather than retained verbatim — each retained card carries a multi-KB
+     * provenance trail, and the tail is typically hundreds of cards per run.
+     */
     cards: Array<{
         cardId: string;
         courseId: string;
@@ -376,6 +389,25 @@ interface PipelineRunReport {
         tags?: string[];
         selected: boolean;
     }>;
+    /**
+     * Summary of the discarded tail of the candidate pool — cards that were
+     * generated and scored but neither selected nor retained in `cards`.
+     *
+     * Provides breadcrumbs for "where did card X go?" investigations without
+     * the memory cost of keeping every dropped candidate's provenance.
+     *
+     * Future: may carry a bloom filter of discarded cardIds so callers can
+     * ask "was X in this run's discard tail?" with bounded memory cost.
+     */
+    discardedTail?: {
+        count: number;
+        /** [min, max] finalScore across the discarded tail. */
+        scoreRange?: [number, number];
+        /** [min, max] cardElo across the discarded tail (where parseable). */
+        eloRange?: [number, number];
+        /** Human-readable note for console display. */
+        note: string;
+    };
 }
 /**
  * Console API object exposed on window.skuilder.pipeline
@@ -468,6 +500,20 @@ declare const pipelineDebugAPI: {
      * @internal
      */
     _setSearch(query: string): void;
+    /**
+     * Internal UI helpers
+     * @internal
+     */
+    _copyConfig(runId: string, btn?: HTMLElement): void;
+    /**
+     * 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: string, btn?: HTMLElement): void;
     /**
      * Show help.
      */

package/dist/core/index.d.ts

@@ -364,6 +364,19 @@ interface PipelineRunReport {
     finalCount: number;
     reviewsSelected: number;
     newSelected: number;
+    /**
+     * Card data for inspection.
+     *
+     * To keep the in-memory ring buffer small, this contains:
+     *   - All selected cards (the actual session output).
+     *   - The top-N highest-scoring non-selected cards (see DISCARDED_KEEP_TOP),
+     *     useful for understanding "near misses" and filter behavior.
+     *
+     * The remaining low-score tail of the candidate pool (mostly ELO-window
+     * pull remnants that filters scored down) is summarized in `discardedTail`
+     * rather than retained verbatim — each retained card carries a multi-KB
+     * provenance trail, and the tail is typically hundreds of cards per run.
+     */
     cards: Array<{
         cardId: string;
         courseId: string;
@@ -376,6 +389,25 @@ interface PipelineRunReport {
         tags?: string[];
         selected: boolean;
     }>;
+    /**
+     * Summary of the discarded tail of the candidate pool — cards that were
+     * generated and scored but neither selected nor retained in `cards`.
+     *
+     * Provides breadcrumbs for "where did card X go?" investigations without
+     * the memory cost of keeping every dropped candidate's provenance.
+     *
+     * Future: may carry a bloom filter of discarded cardIds so callers can
+     * ask "was X in this run's discard tail?" with bounded memory cost.
+     */
+    discardedTail?: {
+        count: number;
+        /** [min, max] finalScore across the discarded tail. */
+        scoreRange?: [number, number];
+        /** [min, max] cardElo across the discarded tail (where parseable). */
+        eloRange?: [number, number];
+        /** Human-readable note for console display. */
+        note: string;
+    };
 }
 /**
  * Console API object exposed on window.skuilder.pipeline
@@ -468,6 +500,20 @@ declare const pipelineDebugAPI: {
      * @internal
      */
     _setSearch(query: string): void;
+    /**
+     * Internal UI helpers
+     * @internal
+     */
+    _copyConfig(runId: string, btn?: HTMLElement): void;
+    /**
+     * 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: string, btn?: HTMLElement): void;
     /**
      * Show help.
      */

package/dist/core/index.js

@@ -724,6 +724,7 @@ var PipelineDebugger_exports = {};
 __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
+  clearRunHistory: () => clearRunHistory,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -731,6 +732,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";
@@ -759,7 +763,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),
@@ -769,7 +773,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 {
@@ -784,7 +828,8 @@ function buildRunReport(courseId, courseName, generatorName, generators, generat
     finalCount: selectedCards.length,
     reviewsSelected,
     newSelected,
-    cards
+    cards,
+    discardedTail
   };
 }
 function formatProvenance(provenance) {
@@ -820,6 +865,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;
@@ -878,6 +961,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) => `
@@ -885,6 +975,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("");
@@ -893,11 +984,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>
 
@@ -912,7 +1005,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>` : ""}
@@ -936,7 +1032,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>
@@ -982,7 +1081,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";
@@ -991,6 +1090,7 @@ var init_PipelineDebugger = __esm({
     _activePipeline = null;
     MAX_RUNS = 10;
     runHistory = [];
+    DISCARDED_KEEP_TOP = 25;
     _uiContainer = null;
     _selectedRunIndex = null;
     _cardSearchQuery = "";
@@ -1055,7 +1155,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.
@@ -1360,6 +1467,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.
        */
@@ -5624,12 +5775,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;