@vue-skuilder/db 0.2.2 → 0.2.3

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 {
@@ -13379,6 +13382,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,6 +13467,9 @@ 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}
@@ -13565,6 +13597,7 @@ var SessionController = class _SessionController extends Loggable {
     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;
   }
   /**
@@ -13593,12 +13626,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 +13643,100 @@ 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;
+  }
+  /**
+   * 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.
    *
@@ -13636,7 +13764,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 +13916,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];
@@ -14068,7 +14199,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 +14211,8 @@ var SessionController = class _SessionController extends Loggable {
       maxSessionViews,
       sessionViews
     );
+    await this._notifyOutcomeObservers(cardRecord, currentCard, result);
+    return result;
   }
   dismissCurrentCard(action = "dismiss-success") {
     if (this._currentCard) {