@vue-skuilder/db 0.1.32-e → 0.1.32-f

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.32-e",
+  "version": "0.1.32-f",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.32-e",
+    "@vue-skuilder/common": "0.1.32-f",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -59,8 +59,8 @@
     "@types/uuid": "^10.0.0",
     "tsup": "^8.0.2",
     "typescript": "~5.9.3",
-    "vite": "^7.0.0",
-    "vitest": "^4.0.15"
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
   "stableVersion": "0.1.31"
 }

package/src/core/navigators/Pipeline.ts

@@ -406,17 +406,52 @@ export class Pipeline extends ContentNavigator {
     // Keep a copy of all cards for debug capture (before filtering removes any)
     const allCardsBeforeFiltering = [...cards];
 
+    // Pre-fetch any literal requireCards IDs that the generator didn't produce.
+    // requireCards is a hard guarantee — required cards bypass the filter chain
+    // and are injected directly into the final result by applyHints. We need
+    // them present in allCardsBeforeFiltering for that injection to find them.
+    // (Glob patterns are left to the existing pool-search behaviour.)
+    const pendingHints = this._ephemeralHints;
+    if (pendingHints?.requireCards?.length) {
+      const poolIds = new Set(allCardsBeforeFiltering.map((c) => c.cardId));
+      const missingIds = pendingHints.requireCards.filter(
+        (p) => !p.includes('*') && !poolIds.has(p)
+      );
+      if (missingIds.length > 0) {
+        const fetchedTags = await this.course!.getAppliedTagsBatch(missingIds);
+        const courseId = this.course!.getCourseID();
+        for (const cardId of missingIds) {
+          allCardsBeforeFiltering.push({
+            cardId,
+            courseId,
+            score: 1.0,
+            tags: fetchedTags.get(cardId) ?? [],
+            provenance: [],
+          });
+        }
+        logger.info(
+          `[Pipeline] Pre-fetched ${missingIds.length} required card(s) into pool: ${missingIds.join(', ')}`
+        );
+      }
+    }
+
     // Apply filters sequentially, tracking impact
+    // Track prescribed-origin cards through the filter chain for diagnostics
+    const prescribedIds = new Set(
+      cards
+        .filter((c) => c.provenance.some((p) => p.strategy === 'prescribed'))
+        .map((c) => c.cardId)
+    );
     const filterImpacts: FilterImpact[] = [];
     for (const filter of this.filters) {
       const beforeCount = cards.length;
       const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
       cards = await filter.transform(cards, context);
-      
+
       // Count boost/penalize/pass/removed for this filter
       let boosted = 0, penalized = 0, passed = 0;
       const removed = beforeCount - cards.length;
-      
+
       for (const card of cards) {
         const before = beforeScores.get(card.cardId) ?? 0;
         if (card.score > before) boosted++;
@@ -424,7 +459,25 @@ export class Pipeline extends ContentNavigator {
         else passed++;
       }
       filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
-      
+
+      // Report prescribed card fate through each filter
+      if (prescribedIds.size > 0) {
+        const survivingIds = new Set(cards.map((c) => c.cardId));
+        const killedPrescribed = [...prescribedIds].filter((id) => !survivingIds.has(id));
+        const zeroedPrescribed = cards
+          .filter((c) => prescribedIds.has(c.cardId) && c.score === 0)
+          .map((c) => c.cardId);
+        if (killedPrescribed.length > 0 || zeroedPrescribed.length > 0) {
+          logger.info(
+            `[Pipeline] Filter '${filter.name}' impact on prescribed cards: ` +
+              (killedPrescribed.length > 0 ? `removed=[${killedPrescribed.join(', ')}] ` : '') +
+              (zeroedPrescribed.length > 0 ? `zeroed=[${zeroedPrescribed.join(', ')}]` : '')
+          );
+          // Remove killed ones from tracking set
+          killedPrescribed.forEach((id) => prescribedIds.delete(id));
+        }
+      }
+
       logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
     }
 
@@ -483,7 +536,8 @@ export class Pipeline extends ContentNavigator {
         filterImpacts,
         cards,
         result,
-        context.userElo
+        context.userElo,
+        hints?? undefined
       );
       captureRun(report);
     } catch (e) {
@@ -614,16 +668,33 @@ export class Pipeline extends ContentNavigator {
       }
     }
 
-    // 3. Require — inject from the full pool if not already present
+    // 3. Require — ensure mandatory cards have floor score and are in the pool
     const cardIds = new Set(cards.map((c) => c.cardId));
+    const cardMap = new Map(cards.map((c) => [c.cardId, c]));
     const hintLabel = hints._label ? `Replan Hint (${hints._label})` : 'Replan Hint';
-    const inject = (card: WeightedCard, reason: string) => {
-      if (!cardIds.has(card.cardId)) {
-        // Give required cards a floor score so they sort above zero-score filler
-        const floorScore = Math.max(card.score, 1.0);
+
+    const applyRequirement = (card: WeightedCard, reason: string) => {
+      const mandatoryScore = Number.POSITIVE_INFINITY;
+      const existing = cardMap.get(card.cardId);
+
+      if (existing) {
+        // If already in the pool, upgrade to mandatory score if not already infinite
+        if (existing.score < mandatoryScore) {
+          existing.score = mandatoryScore;
+          existing.provenance.push({
+            strategy: 'ephemeralHint',
+            strategyId: 'ephemeral-hint',
+            strategyName: hintLabel,
+            action: 'boosted',
+            score: mandatoryScore,
+            reason: `${reason} (upgrade to mandatory score)`,
+          });
+        }
+      } else {
+        // If missing, inject from the full pool
         cards.push({
           ...card,
-          score: floorScore,
+          score: mandatoryScore,
           provenance: [
             ...card.provenance,
             {
@@ -631,26 +702,46 @@ export class Pipeline extends ContentNavigator {
               strategyId: 'ephemeral-hint',
               strategyName: hintLabel,
               action: 'boosted',
-              score: floorScore,
+              score: mandatoryScore,
               reason,
             },
           ],
         });
         cardIds.add(card.cardId);
+        cardMap.set(card.cardId, cards[cards.length - 1]);
       }
     };
 
     if (hints.requireCards?.length) {
       for (const pattern of hints.requireCards) {
+        // First check candidates already in the pool
+        for (const cardId of cardIds) {
+          if (globMatch(cardId, pattern)) {
+            applyRequirement(cardMap.get(cardId)!, `requireCard ${pattern}`);
+          }
+        }
+        // Then check full pool for injection
         for (const card of allCards) {
-          if (globMatch(card.cardId, pattern)) inject(card, `requireCard ${pattern}`);
+          if (globMatch(card.cardId, pattern)) {
+            applyRequirement(card, `requireCard ${pattern}`);
+          }
         }
       }
     }
     if (hints.requireTags?.length) {
       for (const pattern of hints.requireTags) {
+        // First check candidates already in the pool
+        for (const cardId of cardIds) {
+          const card = cardMap.get(cardId)!;
+          if (cardMatchesTagPattern(card, pattern)) {
+            applyRequirement(card, `requireTag ${pattern}`);
+          }
+        }
+        // Then check full pool for injection
         for (const card of allCards) {
-          if (cardMatchesTagPattern(card, pattern)) inject(card, `requireTag ${pattern}`);
+          if (cardMatchesTagPattern(card, pattern)) {
+            applyRequirement(card, `requireTag ${pattern}`);
+          }
         }
       }
     }

package/src/core/navigators/PipelineDebugger.ts

@@ -9,6 +9,7 @@ import {
 } from './index';
 import { logger } from '../../util/logger';
 import type { Pipeline, CardSpaceDiagnosis } from './Pipeline';
+import type { ReplanHints } from './generators/types';
 
 /**
  * Captured reference to the most recently created Pipeline instance.
@@ -83,6 +84,9 @@ export interface PipelineRunReport {
   // Filter phase
   filters: FilterImpact[];
 
+  /** Ephemeral hints applied during this run */
+  hints?: ReplanHints;
+
   // Results
   finalCount: number;
   reviewsSelected: number;
@@ -93,6 +97,7 @@ export interface PipelineRunReport {
     cardId: string;
     courseId: string;
     origin: 'new' | 'review' | 'unknown';
+    generator?: string;
     finalScore: number;
     /** Card's ELO (parsed from ELO generator provenance, if available) */
     cardElo?: number;
@@ -115,8 +120,10 @@ function getOrigin(card: WeightedCard): 'new' | 'review' | 'unknown' {
   const firstEntry = card.provenance[0];
   if (!firstEntry) return 'unknown';
   const reason = firstEntry.reason?.toLowerCase() || '';
-  if (reason.includes('new card')) return 'new';
-  if (reason.includes('review')) return 'review';
+  const strategy = firstEntry.strategy?.toLowerCase() || '';
+
+  if (reason.includes('new card') || strategy.includes('elo')) return 'new';
+  if (reason.includes('review') || strategy.includes('srs')) return 'review';
   return 'unknown';
 }
 
@@ -159,7 +166,8 @@ export function buildRunReport(
   filters: FilterImpact[],
   allCards: WeightedCard[],
   selectedCards: WeightedCard[],
-  userElo?: number
+  userElo?: number,
+  hints?: ReplanHints
 ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
   const selectedIds = new Set(selectedCards.map((c) => c.cardId));
 
@@ -167,6 +175,7 @@ export function buildRunReport(
     cardId: card.cardId,
     courseId: card.courseId,
     origin: getOrigin(card),
+    generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
     finalScore: card.score,
     cardElo: parseCardElo(card.provenance),
     provenance: card.provenance,
@@ -185,6 +194,7 @@ export function buildRunReport(
     generators,
     generatedCount,
     filters,
+    hints,
     finalCount: selectedCards.length,
     reviewsSelected,
     newSelected,
@@ -255,6 +265,223 @@ function printRunSummary(run: PipelineRunReport): void {
   console.groupEnd();
 }
 
+// ============================================================================
+// UI DEBUGGER (VANILLA HTML)
+// ============================================================================
+
+let _uiContainer: HTMLElement | null = null;
+let _selectedRunIndex: number | null = null;
+let _cardSearchQuery = '';
+
+function renderUI(): void {
+  if (!_uiContainer) return;
+
+  const runs = runHistory;
+  const selectedRun = _selectedRunIndex !== null ? runs[_selectedRunIndex] : null;
+
+  const styles = `
+    #sk-pipeline-debugger {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100vw;
+      height: 100vh;
+      background: #f8f9fa;
+      color: #212529;
+      z-index: 999999;
+      display: flex;
+      flex-direction: column;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      font-size: 14px;
+    }
+    #sk-pipeline-debugger header {
+      padding: 1rem;
+      background: #343a40;
+      color: white;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    #sk-pipeline-debugger .container {
+      display: flex;
+      flex: 1;
+      overflow: hidden;
+    }
+    #sk-pipeline-debugger .sidebar {
+      width: 300px;
+      border-right: 1px solid #dee2e6;
+      overflow-y: auto;
+      background: white;
+    }
+    #sk-pipeline-debugger .main-content {
+      flex: 1;
+      overflow-y: auto;
+      padding: 1.5rem;
+    }
+    #sk-pipeline-debugger .run-item {
+      padding: 0.75rem 1rem;
+      border-bottom: 1px solid #eee;
+      cursor: pointer;
+    }
+    #sk-pipeline-debugger .run-item:hover { background: #f1f3f5; }
+    #sk-pipeline-debugger .run-item.active { background: #e9ecef; border-left: 4px solid #007bff; }
+    #sk-pipeline-debugger h2, #sk-pipeline-debugger h3 { margin-top: 0; }
+    #sk-pipeline-debugger table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; background: white; }
+    #sk-pipeline-debugger th, #sk-pipeline-debugger td { border: 1px solid #dee2e6; padding: 0.5rem; text-align: left; }
+    #sk-pipeline-debugger th { background: #f1f3f5; }
+    #sk-pipeline-debugger code { background: #f1f3f5; padding: 0.1rem 0.3rem; border-radius: 3px; font-family: monospace; }
+    #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; }
+  `;
+
+  const runListHtml =
+    runs.length === 0
+      ? '<div style="padding: 1rem;">No runs captured yet.</div>'
+      : runs
+          .map(
+            (r, i) => `
+        <div class="run-item ${i === _selectedRunIndex ? 'active' : ''}" onclick="window.skuilder.pipeline._selectRun(${i})">
+          <strong>${r.timestamp.toLocaleTimeString()}</strong><br/>
+          <small>${r.courseName || r.courseId.slice(0, 8)}</small><br/>
+          <small>${r.finalCount} cards selected</small>
+        </div>
+      `
+          )
+          .join('');
+
+  let detailsHtml =
+    '<div style="color: #6c757d; text-align: center; margin-top: 5rem;">Select a run to see details</div>';
+
+  if (selectedRun) {
+    const filteredCards = selectedRun.cards.filter(
+      (c) =>
+        !_cardSearchQuery || c.cardId.toLowerCase().includes(_cardSearchQuery.toLowerCase())
+    );
+
+    detailsHtml = `
+      <h2>Run: ${selectedRun.runId}</h2>
+      <p>
+        <strong>Time:</strong> ${selectedRun.timestamp.toLocaleString()} | 
+        <strong>Course:</strong> ${selectedRun.courseName || selectedRun.courseId} | 
+        <strong>User ELO:</strong> ${selectedRun.userElo ?? 'unknown'}
+      </p>
+
+      <h3>Pipeline Config</h3>
+      <table>
+        <tr><th>Generator</th><td>${selectedRun.generatorName} (${selectedRun.generatedCount} candidates)</td></tr>
+        ${(selectedRun.generators || [])
+          .map(
+            (g) => `
+          <tr><td style="padding-left: 2rem;">↳ ${g.name}</td><td>${g.cardCount} cards (${g.newCount} new, ${g.reviewCount} review, top: ${g.topScore.toFixed(2)})</td></tr>
+        `
+          )
+          .join('')}
+      </table>
+
+      ${
+        selectedRun.hints
+          ? `
+        <h3>Ephemeral Hints</h3>
+        <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>`
+              : ''
+          }
+          ${
+            selectedRun.hints.boostCards
+              ? `<tr><th>Boost Cards</th><td><pre style="margin:0">${JSON.stringify(selectedRun.hints.boostCards, null, 2)}</pre></td></tr>`
+              : ''
+          }
+          ${
+            selectedRun.hints.requireTags
+              ? `<tr><th>Require Tags</th><td>${selectedRun.hints.requireTags.join(', ')}</td></tr>`
+              : ''
+          }
+          ${
+            selectedRun.hints.requireCards
+              ? `<tr><th>Require Cards</th><td>${selectedRun.hints.requireCards.join(', ')}</td></tr>`
+              : ''
+          }
+          ${
+            selectedRun.hints.excludeTags
+              ? `<tr><th>Exclude Tags</th><td>${selectedRun.hints.excludeTags.join(', ')}</td></tr>`
+              : ''
+          }
+          ${
+            selectedRun.hints.excludeCards
+              ? `<tr><th>Exclude Cards</th><td>${selectedRun.hints.excludeCards.join(', ')}</td></tr>`
+              : ''
+          }
+        </table>
+      `
+          : ''
+      }
+
+      <h3>Filter Impact</h3>
+      <table>
+        <thead><tr><th>Filter</th><th>Boosted</th><th>Penalized</th><th>Passed</th><th>Removed</th></tr></thead>
+        <tbody>
+          ${selectedRun.filters
+            .map(
+              (f) => `
+            <tr><td>${f.name}</td><td>↑${f.boosted}</td><td>↓${f.penalized}</td><td>=${f.passed}</td><td>✕${f.removed}</td></tr>
+          `
+            )
+            .join('')}
+        </tbody>
+      </table>
+
+      <h3>Cards (${selectedRun.finalCount} selected / ${selectedRun.cards.length} total)</h3>
+      <input type="text" class="search-box" placeholder="Search Card ID..." value="${_cardSearchQuery}" oninput="window.skuilder.pipeline._setSearch(this.value)">
+      
+      <table>
+        <thead><tr><th>ID</th><th>Generator</th><th>Origin</th><th>Score</th><th>Selected</th></tr></thead>
+        <tbody>
+          ${filteredCards
+            .map(
+              (c) => `
+            <tr>
+              <td><code>${c.cardId}</code></td>
+              <td>${c.generator || 'unknown'}</td>
+              <td>${c.origin}</td>
+              <td>${c.finalScore.toFixed(3)}</td>
+              <td>${c.selected ? '✅' : '❌'}</td>
+            </tr>
+            ${
+              c.selected || _cardSearchQuery
+                ? `
+              <tr>
+                <td colspan="5">
+                  <div class="provenance">${formatProvenance(c.provenance)}</div>
+                </td>
+              </tr>
+            `
+                : ''
+            }
+          `
+            )
+            .join('')}
+        </tbody>
+      </table>
+    `;
+  }
+
+  _uiContainer.innerHTML = `
+    <style>${styles}</style>
+    <header>
+      <strong>Pipeline Debugger</strong>
+      <button class="close-btn" onclick="window.skuilder.pipeline.ui()">Close</button>
+    </header>
+    <div class="container">
+      <div class="sidebar">${runListHtml}</div>
+      <div class="main-content">${detailsHtml}</div>
+    </div>
+  `;
+}
+
 /**
  * Console API object exposed on window.skuilder.pipeline
  */
@@ -429,17 +656,26 @@ export const pipelineDebugAPI = {
         const mode = reason.match(/mode=([^;]+)/)?.[1] ?? 'unknown';
         const blocked = reason.match(/blocked=([^;]+)/)?.[1] ?? 'unknown';
         const blockedTargets = reason.match(/blockedTargets=([^;]+)/)?.[1] ?? 'none';
+        const supportCard = reason.match(/supportCard=([^;]+)/)?.[1] ?? 'none';
         const supportTags = reason.match(/supportTags=([^;]+)/)?.[1] ?? 'none';
         const multiplier = reason.match(/multiplier=([^;]+)/)?.[1] ?? 'unknown';
+        const supportSource =
+          mode === 'discovered-support'
+            ? 'discovered'
+            : mode === 'support'
+              ? 'authored'
+              : 'n/a';
 
         return {
           group: parsedGroup,
           mode,
+          supportSource,
           cardId: card.cardId,
           selected: card.selected ? 'yes' : 'no',
           finalScore: card.finalScore.toFixed(3),
           blocked,
           blockedTargets,
+          supportCard,
           supportTags,
           multiplier,
         };
@@ -462,6 +698,8 @@ export const pipelineDebugAPI = {
     const selectedRows = rows.filter((r) => r.selected === 'yes');
     const blockedTargetSet = new Set<string>();
     const supportTagSet = new Set<string>();
+    const authoredSupportSet = new Set<string>();
+    const discoveredSupportSet = new Set<string>();
 
     for (const row of rows) {
       if (row.blockedTargets && row.blockedTargets !== 'none') {
@@ -476,6 +714,13 @@ export const pipelineDebugAPI = {
           .filter(Boolean)
           .forEach((t) => supportTagSet.add(t));
       }
+      if (row.supportCard && row.supportCard !== 'none') {
+        if (row.supportSource === 'discovered') {
+          discoveredSupportSet.add(row.supportCard);
+        } else if (row.supportSource === 'authored') {
+          authoredSupportSet.add(row.supportCard);
+        }
+      }
     }
 
     logger.info(`Prescribed cards in run: ${rows.length}`);
@@ -486,6 +731,12 @@ export const pipelineDebugAPI = {
     logger.info(
       `Resolved support tags referenced: ${supportTagSet.size > 0 ? [...supportTagSet].join(', ') : 'none'}`
     );
+    logger.info(
+      `Authored support cards emitted: ${authoredSupportSet.size > 0 ? [...authoredSupportSet].join(', ') : 'none'}`
+    );
+    logger.info(
+      `Discovered support cards emitted: ${discoveredSupportSet.size > 0 ? [...discoveredSupportSet].join(', ') : 'none'}`
+    );
 
     // eslint-disable-next-line no-console
     console.groupEnd();
@@ -641,6 +892,46 @@ export const pipelineDebugAPI = {
     );
   },
 
+  /**
+   * Toggle the full-screen UI debugger.
+   */
+  ui(): void {
+    if (_uiContainer) {
+      document.body.removeChild(_uiContainer);
+      _uiContainer = null;
+      return;
+    }
+
+    _uiContainer = document.createElement('div');
+    _uiContainer.id = 'sk-pipeline-debugger';
+    document.body.appendChild(_uiContainer);
+
+    // Initial select last run if any
+    if (_selectedRunIndex === null && runHistory.length > 0) {
+      _selectedRunIndex = 0;
+    }
+
+    renderUI();
+  },
+
+  /**
+   * Internal UI helpers
+   * @internal
+   */
+  _selectRun(index: number): void {
+    _selectedRunIndex = index;
+    renderUI();
+  },
+
+  /**
+   * Internal UI helpers
+   * @internal
+   */
+  _setSearch(query: string): void {
+    _cardSearchQuery = query;
+    renderUI();
+  },
+
   /**
    * Show help.
    */
@@ -649,6 +940,7 @@ export const pipelineDebugAPI = {
 🔧 Pipeline Debug API
 
 Commands:
+  .ui()                  Toggle full-screen UI debugger
   .showLastRun()         Show summary of most recent pipeline run
   .showRun(id|index)     Show summary of a specific run (by index or ID suffix)
   .showCard(cardId)      Show provenance trail for a specific card
@@ -665,6 +957,7 @@ Commands:
   .help()                Show this help message
 
 Example:
+  window.skuilder.pipeline.ui()
   window.skuilder.pipeline.showLastRun()
   window.skuilder.pipeline.showRun(1)
   await window.skuilder.pipeline.diagnoseCardSpace()

package/src/core/navigators/generators/CompositeGenerator.ts

@@ -223,7 +223,10 @@ export default class CompositeGenerator extends ContentNavigator implements Card
     for (const [, items] of byCardId) {
       const cards = items.map((i) => i.card);
       const aggregatedScore = this.aggregateScores(items);
-      const finalScore = Math.min(1.0, aggregatedScore); // Clamp to [0, 1]
+      // Allow scores above 1.0 to pass through — generators like prescribed
+      // intentionally use high scores to express curriculum priority.
+      // Only clamp negative scores.
+      const finalScore = Math.max(0, aggregatedScore);
 
       // Merge provenance from all generators that produced this card
       const mergedProvenance = cards.flatMap((c) => c.provenance);