@vue-skuilder/db 0.1.35 → 0.1.38

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.35",
+  "version": "0.1.38",
   "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.35",
+    "@vue-skuilder/common": "0.1.38",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.1.35"
+  "stableVersion": "0.1.38"
 }

package/src/core/navigators/Pipeline.ts

@@ -524,8 +524,11 @@ export class Pipeline extends ContentNavigator {
     // Capture run for debug API
     try {
       const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
-      // Use the full post-filter sorted array (not just top N) so that
-      // showCard() can inspect provenance for cards that didn't make the cut.
+      // Pass the full post-filter sorted array; buildRunReport retains all
+      // selected cards plus the top-N highest-scoring near-misses and
+      // summarizes the discarded tail (see DISCARDED_KEEP_TOP). This keeps
+      // showCard() useful for "why didn't this rank?" inspection without
+      // pinning hundreds of low-score candidates' provenance per run.
       // `cards` is the post-filter, post-hints, sorted array.
       const report = buildRunReport(
         this.course?.getCourseID() || 'unknown',

package/src/core/navigators/PipelineDebugger.ts

@@ -92,7 +92,19 @@ export interface PipelineRunReport {
   reviewsSelected: number;
   newSelected: number;
 
-  // Full card data for inspection
+  /**
+   * 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;
@@ -105,6 +117,26 @@ export 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;
+  };
 }
 
 /**
@@ -113,6 +145,30 @@ export interface PipelineRunReport {
 const MAX_RUNS = 10;
 const runHistory: PipelineRunReport[] = [];
 
+/**
+ * Cap on non-selected ("discarded") cards retained per run report.
+ *
+ * Pipeline candidate pools are typically hundreds of cards (ELO window pull
+ * + generators), but most are scored down by filters and never selected.
+ * Their provenance trails are the dominant text-memory cost in the ring
+ * buffer (each entry ~1–2 KB). Retaining only the top-N "near misses"
+ * preserves debugging value while collapsing memory roughly an order of
+ * magnitude or more.
+ */
+const DISCARDED_KEEP_TOP = 25;
+
+/**
+ * Programmatic clear of pipeline run history.
+ *
+ * Called by session-lifecycle hooks (session end, course switch, logout)
+ * to release retained provenance/tag arrays once they're no longer useful
+ * for in-session debugging. The interactive `clear()` debug method remains
+ * for manual use.
+ */
+export function clearRunHistory(): void {
+  runHistory.length = 0;
+}
+
 /**
  * Determine card origin from provenance trail.
  */
@@ -171,7 +227,11 @@ export function buildRunReport(
 ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
   const selectedIds = new Set(selectedCards.map((c) => c.cardId));
 
-  const cards = allCards.map((card) => ({
+  // `allCards` arrives post-filter and sorted by score (desc). Partition
+  // into selected vs not-selected, then retain only the top-N of the
+  // non-selected group to bound memory. The remaining low-score tail is
+  // summarized rather than kept (see discardedTail).
+  const toReport = (card: WeightedCard) => ({
     cardId: card.cardId,
     courseId: card.courseId,
     origin: getOrigin(card),
@@ -181,7 +241,55 @@ export function buildRunReport(
     provenance: card.provenance,
     tags: card.tags,
     selected: selectedIds.has(card.cardId),
-  }));
+  });
+
+  const selectedReported: ReturnType<typeof toReport>[] = [];
+  const nearMissReported: ReturnType<typeof toReport>[] = [];
+  const discardedTailCards: WeightedCard[] = [];
+
+  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: PipelineRunReport['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 !== undefined) {
+        eloSeen = true;
+        if (elo < eloMin) eloMin = elo;
+        if (elo > eloMax) eloMax = elo;
+      }
+    }
+    const eloFragment = eloSeen ? `, ELO ${eloMin}–${eloMax}` : '';
+    discardedTail = {
+      count: discardedTailCards.length,
+      scoreRange: [scoreMin, scoreMax],
+      eloRange: eloSeen ? [eloMin, eloMax] : undefined,
+      note:
+        `${discardedTailCards.length} additional candidate(s) scored below the ` +
+        `top ${DISCARDED_KEEP_TOP} near-misses and were not retained ` +
+        `(score ${scoreMin.toExponential(2)}–${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;
@@ -199,6 +307,7 @@ export function buildRunReport(
     reviewsSelected,
     newSelected,
     cards,
+    discardedTail,
   };
 }
 
@@ -273,6 +382,50 @@ let _uiContainer: HTMLElement | null = null;
 let _selectedRunIndex: number | null = null;
 let _cardSearchQuery = '';
 
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeAttr(s: string): string {
+  return escapeHtml(s).replace(/"/g, '&quot;');
+}
+
+function copyTextToClipboard(text: string, btn?: HTMLElement): void {
+  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(): void {
   if (!_uiContainer) return;
 
@@ -333,6 +486,13 @@ function renderUI(): void {
     #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 =
@@ -345,6 +505,7 @@ function renderUI(): void {
           <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>
       `
           )
@@ -359,11 +520,13 @@ function renderUI(): void {
         !_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>
 
@@ -382,7 +545,10 @@ function renderUI(): void {
       ${
         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>` : ''}
           ${
@@ -434,7 +600,10 @@ function renderUI(): void {
         </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>
@@ -554,7 +723,19 @@ export const pipelineDebugAPI = {
         return;
       }
     }
-    logger.info(`[Pipeline Debug] Card '${cardId}' not found in recent runs.`);
+    // Not found in any retained card list. If runs have discarded tails, the
+    // card may have been in the low-score remnant pool — surface that as a
+    // breadcrumb rather than a flat "not found".
+    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 — ` +
+          `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.`);
+    }
   },
 
   /**
@@ -932,6 +1113,55 @@ export const pipelineDebugAPI = {
     renderUI();
   },
 
+  /**
+   * Internal UI helpers
+   * @internal
+   */
+  _copyConfig(runId: string, btn?: HTMLElement): void {
+    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: string, btn?: HTMLElement): void {
+    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.
    */

package/src/impl/common/BaseUserDB.ts

@@ -686,7 +686,12 @@ Currently logged-in as ${this._username}.`
             _rev: existingDoc._rev,
           });
         } catch (e: unknown) {
-          if (e instanceof Error && e.name === 'not_found') {
+          // NB: PouchDB errors are plain objects ({error, reason, status, name,
+          // message, ...}), not Error instances — `e instanceof Error` is false
+          // for them. Check `.name` directly. The outer catch at line ~697
+          // already does this correctly; mirror that style here so the
+          // not_found → "create new doc" path actually fires for fresh user DBs.
+          if ((e as { name?: string })?.name === 'not_found') {
             // Create new doc
             await this.remoteDB.put(doc);
           } else {
@@ -716,7 +721,10 @@ Currently logged-in as ${this._username}.`
         _rev: existingDoc._rev,
       });
     } catch (e: unknown) {
-      if (e instanceof Error && e.name === 'conflict' && retries > 0) {
+      // NB: PouchDB errors are plain objects, not Error instances — see
+      // applyDesignDocs() above. Check `.name` directly so the conflict-retry
+      // path actually fires.
+      if ((e as { name?: string })?.name === 'conflict' && retries > 0) {
         await new Promise((resolve) => setTimeout(resolve, 1000));
         return this.applyDesignDoc(doc, retries - 1);
       }

package/src/study/SessionController.ts

@@ -343,8 +343,19 @@ export 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.
    *
@@ -365,11 +376,69 @@ export class SessionController<TView = unknown> extends Loggable {
       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;
+      }
+
+      // Queue the hint-bearing replan behind the in-flight one rather than
+      // dropping its hints. See class comment above for rationale.
+      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: Promise<void> = inflight
+        // Swallow errors in the upstream replan so the downstream still runs
+        // (the user's intent is independent of whether the prior run succeeded).
+        .catch(() => undefined)
+        .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.
+   */
+  private _replanHasIntent(opts: ReplanOptions): boolean {
+    if (opts.label) return true;
+    if (opts.limit !== undefined) return true;
+    if (opts.minFollowUpCards !== undefined) 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.
+   */
+  private async _runReplan(opts: ReplanOptions): Promise<void> {
     // Exclude all cards already presented this session. The pipeline may
     // not yet see their encounter records (async writes), so without this
     // they can re-enter newQ via replaceAll and cause duplicates.
@@ -423,13 +492,7 @@ export class SessionController<TView = unknown> extends Loggable {
       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);
   }
 
   /**

package/src/study/SessionDebugger.ts

@@ -1,4 +1,5 @@
 import { logger } from '../util/logger';
+import { clearRunHistory as clearPipelineRunHistory } from '../core/navigators/PipelineDebugger';
 
 // ============================================================================
 // SESSION DEBUGGER
@@ -75,6 +76,13 @@ export function startSessionTracking(
   newQLength: number,
   failedQLength: number
 ): void {
+  // Release pipeline run-history memory before this session begins piling
+  // new runs on top of the previous session's retained reports. Clearing on
+  // session START (rather than END) keeps post-session inspection — the
+  // dominant debugging workflow — fully functional: a finished session's
+  // run history sits intact until the user actually begins another one.
+  clearPipelineRunHistory();
+
   const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
   activeSession = {