@vue-skuilder/db 0.2.2 → 0.2.4

package/dist/index.mjs

@@ -4184,7 +4184,8 @@ var init_orchestration = __esm({
 // src/core/navigators/Pipeline.ts
 var Pipeline_exports = {};
 __export(Pipeline_exports, {
-  Pipeline: () => Pipeline
+  Pipeline: () => Pipeline,
+  mergeHints: () => mergeHints2
 });
 import { toCourseElo as toCourseElo5 } from "@vue-skuilder/common";
 function globToRegex(pattern) {
@@ -11242,6 +11243,7 @@ var ItemQueue = class {
 
 // src/study/SessionController.ts
 init_couch();
+init_core();
 init_recording();
 
 // src/util/index.ts
@@ -12668,6 +12670,7 @@ init_dataDirectory();
 
 // src/study/SessionController.ts
 init_navigators();
+init_Pipeline();
 
 // src/study/SourceMixer.ts
 var QuotaRoundRobinMixer = class {
@@ -13051,6 +13054,161 @@ mountMixerDebugger();
 // src/study/SessionDebugger.ts
 init_logger();
 init_PipelineDebugger();
+
+// src/study/SessionOverlay.ts
+init_logger();
+var activeController = null;
+function registerActiveController(controller) {
+  activeController = controller;
+}
+function getActiveController() {
+  return activeController;
+}
+var OVERLAY_ID = "skuilder-session-overlay";
+var POLL_MS = 300;
+var INLINE_THRESHOLD = 5;
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var spinnerFrame = 0;
+var overlayEl = null;
+var pollHandle = null;
+var expanded = { reviewQ: false, newQ: false, failedQ: false };
+function toggleSessionOverlay() {
+  if (typeof document === "undefined") {
+    logger.info("[Session Overlay] No DOM available (non-browser host); overlay unavailable.");
+    return;
+  }
+  if (overlayEl) {
+    teardown();
+    logger.info("[Session Overlay] Hidden.");
+  } else {
+    mount();
+    logger.info("[Session Overlay] Shown. Toggle off with window.skuilder.session.dbgOverlay().");
+  }
+}
+function mount() {
+  overlayEl = document.createElement("div");
+  overlayEl.id = OVERLAY_ID;
+  Object.assign(overlayEl.style, {
+    position: "fixed",
+    top: "8px",
+    left: "8px",
+    zIndex: "2147483647",
+    maxWidth: "320px",
+    maxHeight: "90vh",
+    overflowY: "auto",
+    padding: "8px 10px",
+    background: "rgba(17, 24, 39, 0.92)",
+    color: "#e5e7eb",
+    font: "11px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace",
+    borderRadius: "6px",
+    boxShadow: "0 4px 16px rgba(0,0,0,0.4)",
+    pointerEvents: "auto",
+    userSelect: "none"
+  });
+  document.body.appendChild(overlayEl);
+  render();
+  pollHandle = setInterval(render, POLL_MS);
+}
+function teardown() {
+  if (pollHandle !== null) {
+    clearInterval(pollHandle);
+    pollHandle = null;
+  }
+  if (overlayEl?.parentNode) {
+    overlayEl.parentNode.removeChild(overlayEl);
+  }
+  overlayEl = null;
+}
+function render() {
+  if (!overlayEl) return;
+  spinnerFrame++;
+  const ctrl = getActiveController();
+  if (!ctrl) {
+    overlayEl.innerHTML = headerHtml() + `<div style="opacity:.65">No active session.</div>`;
+    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);
+  overlayEl.querySelectorAll("[data-q]").forEach((el) => {
+    el.onclick = () => {
+      const key = el.dataset.q;
+      if (!key) return;
+      expanded[key] = !expanded[key];
+      render();
+    };
+  });
+}
+function headerHtml() {
+  return `<div style="font-weight:600;color:#93c5fd;margin-bottom:4px">\u2699 SessionController</div>`;
+}
+function replanHtml(s) {
+  if (!s.replanActive) {
+    return `<div style="margin-bottom:6px;opacity:.45">\u25CB idle</div>`;
+  }
+  const frame = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length];
+  const reason = esc(s.replanLabel ?? "(auto)");
+  return `<div style="margin-bottom:6px;color:#fde047">${frame} replanning <span style="opacity:.85">[${reason}]</span></div>`;
+}
+function metaHtml(s) {
+  const mmss = formatTime(s.secondsRemaining);
+  const guarantee = s.hasCardGuarantee ? ` \xB7 <span style="color:#fbbf24">guarantee ${s.minCardsGuarantee}</span>` : "";
+  const rows = [
+    `time ${mmss}${guarantee}`,
+    `well-indicated left: ${s.wellIndicatedRemaining}`,
+    `current: ${s.currentCard ? esc(s.currentCard) : '<span style="opacity:.6">\u2014</span>'}`
+  ];
+  return `<div style="margin-bottom:6px">${rows.map((r) => `<div>${r}</div>`).join("")}</div>`;
+}
+function hintsHtml(h) {
+  const parts = [];
+  if (h) {
+    if (h.boostTags && Object.keys(h.boostTags).length) {
+      parts.push(
+        `boost: ` + Object.entries(h.boostTags).map(([k, v]) => `${esc(k)}<span style="opacity:.6">\xD7${v}</span>`).join(", ")
+      );
+    }
+    if (h.boostCards && Object.keys(h.boostCards).length) {
+      parts.push(
+        `boostCards: ` + Object.entries(h.boostCards).map(([k, v]) => `${esc(k)}<span style="opacity:.6">\xD7${v}</span>`).join(", ")
+      );
+    }
+    if (h.requireCards?.length) parts.push(`require: ${h.requireCards.map(esc).join(", ")}`);
+    if (h.requireTags?.length) parts.push(`requireTags: ${h.requireTags.map(esc).join(", ")}`);
+    if (h.excludeTags?.length) parts.push(`exclude: ${h.excludeTags.map(esc).join(", ")}`);
+    if (h.excludeCards?.length) parts.push(`excludeCards: ${h.excludeCards.map(esc).join(", ")}`);
+  }
+  const body = parts.length ? parts.map((p) => `<div style="margin-left:6px">${p}</div>`).join("") : `<div style="margin-left:6px;opacity:.6">none</div>`;
+  return `<div style="margin-bottom:6px"><div style="color:#86efac">sessionHints</div>${body}</div>`;
+}
+function queueHtml(key, label, q) {
+  const collapsible = q.length > INLINE_THRESHOLD;
+  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>`;
+  }
+  return title + body;
+}
+function formatTime(totalSeconds) {
+  const s = Math.max(0, Math.round(totalSeconds));
+  const m = Math.floor(s / 60);
+  const r = s % 60;
+  return `${m}:${r.toString().padStart(2, "0")}`;
+}
+function esc(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// src/study/SessionDebugger.ts
 var activeSession = null;
 var sessionHistory = [];
 var MAX_HISTORY = 5;
@@ -13231,6 +13389,13 @@ var sessionDebugAPI = {
   showQueue() {
     showCurrentQueue();
   },
+  /**
+   * Toggle the pinned, live-updating DOM overlay for the active controller
+   * (queues, session hints, timer). No-ops in non-browser hosts.
+   */
+  dbgOverlay() {
+    toggleSessionOverlay();
+  },
   /**
    * Show presentation history for current or past session.
    */
@@ -13292,6 +13457,7 @@ var sessionDebugAPI = {
 \u{1F3AF} Session Debug API
 
 Commands:
+  .dbgOverlay()             Toggle the pinned live overlay (queues, hints, timer)
   .showQueue()              Show current queue state (active session only)
   .showHistory(index?)      Show presentation history (0=current/last, 1=previous, etc)
   .showInterleaving(index?) Analyze course interleaving pattern
@@ -13360,6 +13526,13 @@ var SessionController = class _SessionController extends Loggable {
    * Used by nextCard() to await completion before drawing from queues.
    */
   _replanPromise = null;
+  /**
+   * Reason for the replan currently executing in `_runReplan`, surfaced by the
+   * debug overlay's spinner. The caller's `opts.label` when present, else
+   * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+   * when the in-flight chain settles.
+   */
+  _activeReplanLabel = null;
   /**
    * Number of well-indicated new cards remaining before the queue
    * degrades to poorly-indicated content. Decremented on each newQ
@@ -13379,6 +13552,32 @@ var SessionController = class _SessionController extends Loggable {
    * each nextCard() draw. Set by replans that include `minFollowUpCards`.
    */
   _minCardsGuarantee = 0;
+  /**
+   * Session-durable scoring hints. Re-merged into every pipeline run for
+   * the rest of the session (initial plan + every replan, including bare
+   * auto-replans and the wedge-breaker), via `_applyHintsToSources`.
+   *
+   * Set by `setSessionHints()` (e.g. session-start post-lesson boost) or by
+   * any replan carrying `ReplanOptions.sessionHints` (e.g. a just-failed
+   * concept boost). Replace semantics, no decay — lives until overwritten
+   * or session end. See `ReplanOptions.sessionHints` for rationale.
+   *
+   * Note: the controller-managed auto-excludes (current card, session
+   * record, imminent draw) are intentionally NOT folded in here — those are
+   * recomputed per-run in `_runReplan` and would otherwise go stale.
+   */
+  _sessionHints = null;
+  /**
+   * Consumer-supplied hooks invoked after each question response is processed.
+   * Seeded from constructor options (threaded from
+   * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+   */
+  _outcomeObservers = [];
+  /**
+   * Lazily-built, stable capability object handed to observers. Bound to
+   * `this`; constructed once so observers can rely on referential identity.
+   */
+  _sessionControls = null;
   startTime;
   endTime;
   _secondsRemaining;
@@ -13438,11 +13637,15 @@ var SessionController = class _SessionController extends Loggable {
     if (options?.initialReviewCap !== void 0) {
       this._initialReviewCap = options.initialReviewCap;
     }
+    if (options?.outcomeObservers?.length) {
+      this._outcomeObservers = [...options.outcomeObservers];
+    }
     this.log(`Session constructed:
     startTime: ${this.startTime}
     endTime: ${this.endTime}
     defaultBatchLimit: ${this._defaultBatchLimit}
     initialReviewCap: ${this._initialReviewCap}`);
+    registerActiveController(this);
   }
   tick() {
     this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1e3);
@@ -13543,15 +13746,23 @@ var SessionController = class _SessionController extends Loggable {
       );
       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;
+      const tracked2 = queued.finally(() => {
+        if (this._replanPromise === tracked2) {
+          this._replanPromise = null;
+          this._activeReplanLabel = null;
+        }
       });
+      this._replanPromise = tracked2;
       return queued;
     }
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    const tracked = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
   /**
@@ -13560,11 +13771,11 @@ var SessionController = class _SessionController extends Loggable {
    * 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;
+    if (opts.sessionHints !== void 0) return true;
     return false;
   }
   /**
@@ -13580,6 +13791,7 @@ var SessionController = class _SessionController extends Loggable {
    * newQ.peek(0) is the imminent draw we need to exclude.
    */
   async _runReplan(opts) {
+    this._activeReplanLabel = opts.label ?? "(auto)";
     if (!opts.hints) opts.hints = {};
     const hints = opts.hints;
     const excludeSet = new Set(hints.excludeCards ?? []);
@@ -13593,12 +13805,13 @@ var SessionController = class _SessionController extends Loggable {
       excludeSet.add(this.newQ.peek(0).cardID);
     }
     hints.excludeCards = [...excludeSet];
-    if (opts.hints) {
-      const hintsWithLabel = opts.label ? { ...opts.hints, _label: opts.label } : opts.hints;
-      for (const source of this.sources) {
-        source.setEphemeralHints?.(hintsWithLabel);
-      }
+    if (opts.sessionHints !== void 0) {
+      this._sessionHints = opts.sessionHints;
+      this.log(
+        `[Replan] Session hints ${opts.sessionHints ? "set" : "cleared"}: ${JSON.stringify(opts.sessionHints)}`
+      );
     }
+    this._applyHintsToSources(opts.hints, opts.label);
     const labelTag = opts.label ? ` [${opts.label}]` : "";
     this.log(
       `Mid-session replan requested${labelTag} (limit: ${opts.limit ?? "default"}, mode: ${opts.mode ?? "replace"}${opts.hints ? ", with hints" : ""})`
@@ -13609,6 +13822,128 @@ var SessionController = class _SessionController extends Loggable {
     }
     await this._executeReplan(opts);
   }
+  /**
+   * Set the session-durable scoring hints (replace semantics, no decay).
+   *
+   * Unlike a one-shot replan hint, these are re-merged into every pipeline
+   * run for the rest of the session — including the initial plan when set
+   * before `prepareSession()`, every replan, the bare auto-replans, and the
+   * wedge-breaker. Pass `null` to clear.
+   *
+   * Typical callers:
+   * - `StudySession` at session start, threading `StudySessionConfig.initHints`
+   *   (e.g. a post-lesson concept boost) — so the boost outlives the first
+   *   queue rebuild instead of being clobbered by the first auto-replan.
+   * - A consumer view on a failure, boosting the just-failed concept tag.
+   *
+   * Does not itself trigger a replan; the next plan/replan picks it up.
+   */
+  setSessionHints(hints) {
+    this._sessionHints = hints;
+    this.log(`Session hints ${hints ? "set" : "cleared"}: ${JSON.stringify(hints)}`);
+  }
+  /**
+   * Read the current session-durable hints (for read-modify-write callers,
+   * e.g. an outcome observer that clamps a compounding boost).
+   */
+  getSessionHints() {
+    return this._sessionHints;
+  }
+  /**
+   * Live state snapshot for the debug overlay (window.skuilder.session
+   * .dbgOverlay()). Reads directly from the private queues and hints, so it
+   * always reflects the current moment — unlike the passive SessionDebugger
+   * snapshots, which only capture what was explicitly pushed to them.
+   */
+  getDebugSnapshot() {
+    const describe = (q) => {
+      const cards = [];
+      for (let i = 0; i < q.length; i++) {
+        cards.push(q.peek(i).cardID);
+      }
+      return { length: q.length, dequeueCount: q.dequeueCount, cards };
+    };
+    return {
+      secondsRemaining: this.secondsRemaining,
+      hasCardGuarantee: this.hasCardGuarantee,
+      minCardsGuarantee: this._minCardsGuarantee,
+      wellIndicatedRemaining: this._wellIndicatedRemaining,
+      currentCard: this._currentCard?.item.cardID ?? null,
+      sessionHints: this._sessionHints,
+      replanActive: this._replanPromise !== null,
+      replanLabel: this._activeReplanLabel,
+      reviewQ: describe(this.reviewQ),
+      newQ: describe(this.newQ),
+      failedQ: describe(this.failedQ)
+    };
+  }
+  /**
+   * Merge `hints` into the durable session hints via the pipeline's
+   * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
+   * Convenience over get-then-set for the common additive case. Note the
+   * multiplicative, no-decay semantics — clamp boost factors at the call
+   * site if a repeatedly-emphasised tag could compound unboundedly.
+   */
+  mergeSessionHints(hints) {
+    this._sessionHints = mergeHints2([this._sessionHints, hints]) ?? null;
+    this.log(`Session hints merged: ${JSON.stringify(this._sessionHints)}`);
+  }
+  /**
+   * Merge the durable `_sessionHints` with this run's one-shot hints and
+   * push the result to every source for consumption on the next pipeline
+   * run. Centralised so the initial plan and all replan paths apply session
+   * emphasis identically. No-op when there are no hints of either kind.
+   */
+  _applyHintsToSources(oneShot, label) {
+    const oneShotWithLabel = oneShot && label ? { ...oneShot, _label: label } : oneShot;
+    const merged = mergeHints2([this._sessionHints, oneShotWithLabel]);
+    if (!merged) return;
+    for (const source of this.sources) {
+      source.setEphemeralHints?.(merged);
+    }
+  }
+  /**
+   * Build (once) the stable capability object handed to outcome observers.
+   * Methods are bound to `this`; the object identity is stable across calls
+   * so observers may key off it.
+   */
+  _getSessionControls() {
+    if (!this._sessionControls) {
+      this._sessionControls = {
+        getSessionHints: () => this.getSessionHints(),
+        setSessionHints: (h) => this.setSessionHints(h),
+        mergeSessionHints: (h) => this.mergeSessionHints(h),
+        requestReplan: (opts) => this.requestReplan(opts)
+      };
+    }
+    return this._sessionControls;
+  }
+  /**
+   * Notify registered outcome observers about a processed response.
+   *
+   * Only question records are surfaced (non-question dismisses are skipped).
+   * Observers run after ELO/SRS are recorded and before navigation. Each is
+   * awaited but isolated in try/catch — a throwing observer is logged and
+   * skipped, never wedging the session. Keep observers cheap and `void` any
+   * long work (e.g. a triggered replan) to avoid stalling the draw.
+   */
+  async _notifyOutcomeObservers(record, currentCard, result) {
+    if (this._outcomeObservers.length === 0) return;
+    if (!isQuestionRecord(record)) return;
+    const outcome = {
+      record,
+      card: currentCard.card,
+      result
+    };
+    const controls = this._getSessionControls();
+    for (const observer of this._outcomeObservers) {
+      try {
+        await observer(outcome, controls);
+      } catch (e) {
+        this.error("[OutcomeObserver] observer threw; ignoring", e);
+      }
+    }
+  }
   /**
    * Run a replan, bypassing requestReplan()'s coalesce logic.
    *
@@ -13623,9 +13958,13 @@ var SessionController = class _SessionController extends Loggable {
    */
   async _replanUncoalesced(opts) {
     const run = this._runReplan(opts);
-    this._replanPromise = run.finally(() => {
-      if (this._replanPromise === run) this._replanPromise = null;
+    const tracked = run.finally(() => {
+      if (this._replanPromise === tracked) {
+        this._replanPromise = null;
+        this._activeReplanLabel = null;
+      }
     });
+    this._replanPromise = tracked;
     await run;
   }
   /**
@@ -13636,7 +13975,7 @@ var SessionController = class _SessionController extends Loggable {
    */
   normalizeReplanOptions(input) {
     if (!input) return {};
-    const replanKeys = ["hints", "limit", "mode", "label", "minFollowUpCards"];
+    const replanKeys = ["hints", "sessionHints", "limit", "mode", "label", "minFollowUpCards"];
     const inputKeys = Object.keys(input);
     if (inputKeys.some((k) => replanKeys.includes(k))) {
       return input;
@@ -13788,6 +14127,9 @@ var SessionController = class _SessionController extends Loggable {
     const additive = options?.additive ?? false;
     const newLimit = options?.limit ?? this._defaultBatchLimit;
     const fetchLimit = replan ? newLimit : newLimit + this._initialReviewCap;
+    if (!replan) {
+      this._applyHintsToSources();
+    }
     const batches = [];
     for (let i = 0; i < this.sources.length; i++) {
       const source = this.sources[i];
@@ -13978,14 +14320,14 @@ 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();
+      void this.requestReplan({ label: "auto:depletion" });
     }
     const REPLAN_BUFFER = 3;
     if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
       this.log(
         `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
       );
-      void this.requestReplan();
+      void this.requestReplan({ label: "auto:quality" });
     }
     if (this._secondsRemaining <= 0 && this.failedQ.length === 0 && this._minCardsGuarantee <= 0) {
       this._currentCard = null;
@@ -14068,7 +14410,7 @@ var SessionController = class _SessionController extends Loggable {
     const studySessionItem = {
       ...currentCard.item
     };
-    return await this.services.response.processResponse(
+    const result = await this.services.response.processResponse(
       cardRecord,
       cardHistory,
       studySessionItem,
@@ -14080,6 +14422,8 @@ var SessionController = class _SessionController extends Loggable {
       maxSessionViews,
       sessionViews
     );
+    await this._notifyOutcomeObservers(cardRecord, currentCard, result);
+    return result;
   }
   dismissCurrentCard(action = "dismiss-success") {
     if (this._currentCard) {