@vue-skuilder/db 0.2.1 → 0.2.3

package/src/impl/couch/courseDB.ts

@@ -302,11 +302,19 @@ export class CourseDB implements CourseDBInterface {
     elo = parseInt(elo as any);
     const limit = cardLimit ? cardLimit : 25;
 
+    // const tQ0 = performance.now();
+    // NOTE: `stale: 'update_after'` was tried here and removed — it gave no
+    // measurable speedup (PouchDB 9 effectively ignores it for the reindex
+    // cost) AND it can return an empty result on the first query after a cold
+    // DB open (index not yet loaded), which then poisons the pool cache. The
+    // session pool cache (see getCardsCenteredAtELO) is what removes the
+    // per-run cost, so we read the view normally (always-fresh) here.
     const below: PouchDB.Query.Response<object> = await this.db.query('elo', {
       limit: Math.ceil(limit / 2),
       startkey: elo,
       descending: true,
     });
+    // const tBelowQ = performance.now();
 
     const aboveLimit = limit - below.rows.length;
 
@@ -314,7 +322,13 @@ export class CourseDB implements CourseDBInterface {
       limit: aboveLimit,
       startkey: elo + 1,
     });
-    // logger.log(JSON.stringify(below));
+    // const tAbove = performance.now();
+    // [perf] parked: getCardsByELO view-query timing (below/above split)
+    // logger.info(
+      // `[perf][getCardsByELO] reqLimit=${limit} ` +
+        // `below=${(tBelowQ - tQ0).toFixed(0)}ms(${below.rows.length}r) ` +
+        // `above=${(tAbove - tBelowQ).toFixed(0)}ms(${above.rows.length}r)`
+    // );
 
     let cards = below.rows;
     cards = cards.concat(above.rows);
@@ -573,6 +587,8 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
 
   async addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void> {
     logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
+    // Strategy set changed — drop the cached navigator so it rebuilds.
+    this.invalidateNavigatorCache();
     // Admin write operation — use remote DB.
     return this.remoteDB.put(data).then(() => {});
   }
@@ -654,6 +670,35 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
    */
   private _pendingHints: ReplanHints | null = null;
 
+  /**
+   * Session-scoped cache of the broad ELO-neighbor pool used by
+   * getCardsCenteredAtELO. The `elo` view query re-indexes on first touch per
+   * call (PouchDB 9 ignores `stale`), so without this each plan/replan pays
+   * ~1.5-2s. The pool is fetched once and re-ranked against the live (roaming)
+   * ELO in memory on subsequent calls.
+   */
+  private _eloPoolCache: {
+    rows: (QualifiedCardID & { elo?: number })[];
+    fetchedAt: number;
+  } | null = null;
+  private readonly _eloPoolTtlMs = 5 * 60 * 1000;
+
+  /**
+   * Cached assembled navigator (Pipeline). createNavigator() reads strategy
+   * docs and builds a fresh Pipeline every call — whose internal `_tagCache`
+   * and `_cachedOrchestration` are designed to make replans cheap but never
+   * survive, because the instance is discarded each run. Caching it lets those
+   * caches persist across plan/replan within a session (SessionController holds
+   * one CourseDB instance for the session's lifetime). Rebuilt on user change,
+   * TTL expiry, or explicit invalidation after a strategy-doc write.
+   */
+  private _cachedNavigator: {
+    navigator: ContentNavigator;
+    userId: string;
+    builtAt: number;
+  } | null = null;
+  private readonly _navigatorTtlMs = 5 * 60 * 1000;
+
   public setEphemeralHints(hints: ReplanHints): void {
     this._pendingHints = hints;
   }
@@ -662,18 +707,60 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     const u = await this._getCurrentUser();
 
     try {
-      const navigator = await this.createNavigator(u);
+      // const tNav0 = performance.now(); // [perf] parked
+      const { navigator } = await this._getCachedNavigator(u);
+      // const tNav1 = performance.now(); // [perf] parked
       if (this._pendingHints) {
         navigator.setEphemeralHints(this._pendingHints);
         this._pendingHints = null;
       }
-      return navigator.getWeightedCards(limit);
+      const result = await navigator.getWeightedCards(limit);
+      // const tRun = performance.now(); // [perf] parked
+      // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
+      // logger.info(
+        // `[perf][courseDB] getWeightedCards(limit=${limit}): ` +
+          // `navigator=${(tNav1 - tNav0).toFixed(0)}ms(${navCache}) ` +
+          // `pipelineRun=${(tRun - tNav1).toFixed(0)}ms ` +
+          // `total=${(tRun - tNav0).toFixed(0)}ms`
+      // );
+      return result;
     } catch (e) {
       logger.error(`[courseDB] Error getting weighted cards: ${e}`);
       throw e;
     }
   }
 
+  /**
+   * Return the assembled navigator, reusing the cached instance when possible.
+   * Reuse preserves the Pipeline's per-session caches (tags, orchestration
+   * context) across replans, which is the dominant per-replan cost once the
+   * ELO-pool cost is removed. Rebuilds on user change or TTL expiry.
+   */
+  private async _getCachedNavigator(
+    user: UserDBInterface
+  ): Promise<{ navigator: ContentNavigator; cacheStatus: 'hit' | 'miss' }> {
+    const userId = user.getUsername();
+    const now = Date.now();
+    if (
+      this._cachedNavigator &&
+      this._cachedNavigator.userId === userId &&
+      now - this._cachedNavigator.builtAt < this._navigatorTtlMs
+    ) {
+      return { navigator: this._cachedNavigator.navigator, cacheStatus: 'hit' };
+    }
+    const navigator = await this.createNavigator(user);
+    this._cachedNavigator = { navigator, userId, builtAt: now };
+    return { navigator, cacheStatus: 'miss' };
+  }
+
+  /**
+   * Drop the cached navigator so the next getWeightedCards() rebuilds it.
+   * Call after mutating this course's navigation strategy documents.
+   */
+  public invalidateNavigatorCache(): void {
+    this._cachedNavigator = null;
+  }
+
   public async getCardsCenteredAtELO(
     options: {
       limit: number;
@@ -684,6 +771,9 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     },
     filter?: (a: QualifiedCardID) => boolean
   ): Promise<StudySessionItem[]> {
+    // [perf] parked: getCardsCenteredAtELO rewrite banner
+    // logger.info('[perf][run] getCardsCenteredAtELO rewrite (session pool cache + in-memory recenter)');
+    // const tCelo0 = performance.now();
     let targetElo: number;
 
     if (options.elo === 'user') {
@@ -706,26 +796,65 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
       targetElo = options.elo;
     }
 
-    let cards: (QualifiedCardID & { elo?: number })[] = [];
-    let mult: number = 4;
-    let previousCount: number = -1;
-    let newCount: number = 0;
+    // const tReg = performance.now();
+
+    // Broad neighbor pool fetched once per session and re-used. We over-fetch
+    // (POOL_SIZE >> limit) so that the in-memory active-card filter and the
+    // slowly-roaming ELO both have ample headroom before a refetch is needed.
+    const POOL_SIZE = Math.max(2000, options.limit * 4);
+    const nowMs = Date.now();
+    let cacheStatus: 'hit' | 'miss' | 'refresh' = 'hit';
+
+    if (!this._eloPoolCache || nowMs - this._eloPoolCache.fetchedAt > this._eloPoolTtlMs) {
+      // MISS: pay the (reindexing) view query once, then cache the raw pool.
+      // Guard: never cache an EMPTY pool. A cold-DB-open or sync-race fetch can
+      // transiently return [], and caching it would starve the session for the
+      // whole TTL. Leaving the cache untouched lets the next call retry.
+      const fetched = await this.getCardsByELO(targetElo, POOL_SIZE);
+      if (fetched.length > 0) {
+        this._eloPoolCache = { rows: fetched, fetchedAt: nowMs };
+      }
+      cacheStatus = 'miss';
+    }
 
-    while (cards.length < options.limit && newCount !== previousCount) {
-      cards = await this.getCardsByELO(targetElo, mult * options.limit);
-      previousCount = newCount;
-      newCount = cards.length;
+    // Apply the (fresh) caller filter, then re-center against the *current* ELO.
+    // Returns a new array each call — the cached pool is never mutated, and the
+    // ranking reflects the live ELO even as it drifts within a session.
+    const rankAgainstCurrentElo = (): (QualifiedCardID & { elo?: number })[] => {
+      const raw = this._eloPoolCache?.rows ?? [];
+      const survivors = filter ? raw.filter((c) => filter(c)) : raw;
+      return survivors
+        .map((c) => ({ ...c }))
+        .sort(
+          (a, b) =>
+            Math.abs((a.elo ?? targetElo) - targetElo) -
+            Math.abs((b.elo ?? targetElo) - targetElo)
+        );
+    };
 
-      logger.debug(`Found ${cards.length} elo neighbor cards...`);
+    let cards = rankAgainstCurrentElo();
 
-      if (filter) {
-        cards = cards.filter(filter);
-        logger.debug(`Filtered to ${cards.length} cards...`);
+    // Refetch once if the pool can't satisfy the limit — either the active-card
+    // filter has grown past pool coverage (hit), or the pool is missing because
+    // a prior fetch came back empty (cold open / sync race). A miss that cached
+    // a non-empty-but-small pool (genuinely small course) is left alone.
+    if (cards.length < options.limit && (cacheStatus === 'hit' || !this._eloPoolCache)) {
+      const fetched = await this.getCardsByELO(targetElo, POOL_SIZE);
+      if (fetched.length > 0) {
+        this._eloPoolCache = { rows: fetched, fetchedAt: nowMs };
       }
-
-      mult *= 2;
+      cards = rankAgainstCurrentElo();
+      cacheStatus = 'refresh';
     }
 
+    // [perf] parked: centeredAtELO regDoc / pool-cache timing
+    // logger.info(
+      // `[perf][centeredAtELO] regDoc=${(tReg - tCelo0).toFixed(0)}ms ` +
+        // `cache=${cacheStatus} build=${(performance.now() - tReg).toFixed(0)}ms ` +
+        // `poolRaw=${this._eloPoolCache?.rows.length ?? 0} postFilter=${cards.length} ` +
+        // `limit=${options.limit} targetElo=${targetElo}`
+    // );
+
     const selectedCards: {
       courseID: string;
       cardID: string;

package/src/study/SessionController.ts

@@ -12,11 +12,12 @@ import {
   StudySessionReviewItem,
 } from '@db/impl/couch';
 
-import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord } from '@db/core';
+import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord, isQuestionRecord } from '@db/core';
 import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
 import { getCardOrigin } from '@db/core/navigators';
 import { ReplanHints } from '@db/core/navigators/generators/types';
+import { mergeHints } from '@db/core/navigators/Pipeline';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
 import { captureMixerRun } from './MixerDebugger';
 import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking } from './SessionDebugger';
@@ -35,6 +36,28 @@ export type { ReplanHints } from '@db/core/navigators/generators/types';
 export interface ReplanOptions {
   /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
   hints?: ReplanHints;
+  /**
+   * Session-durable scoring hints. Unlike `hints` (one-shot, applied to
+   * exactly the run this replan triggers), `sessionHints` are stashed on
+   * the controller and re-merged into *every* subsequent pipeline run for
+   * the remainder of the session — including the bare auto-replans
+   * (depletion/quality) that carry no caller hints, and the wedge-breaker.
+   *
+   * Use for "emphasis that should outlive a single queue rebuild" — e.g.
+   * boosting a just-failed concept tag, or a post-lesson concept boost set
+   * at session start. Without this, a one-shot `hints` boost evaporates on
+   * the next replan and the freshly-rebuilt (replace-mode) queue clobbers
+   * whatever it surfaced.
+   *
+   * Semantics (KISS): setting `sessionHints` *replaces* the prior session
+   * hints wholesale (caller beware — no accumulation, no decay). They live
+   * until session end or until explicitly overwritten. Normal usage applies
+   * a fixed boost, so repeated identical requests are no-ops.
+   *
+   * Merged with per-run `hints` via the pipeline's `mergeHints` (boosts
+   * multiply, require/exclude lists concatenate).
+   */
+  sessionHints?: ReplanHints;
   /**
    * Maximum number of new cards to return from the pipeline.
    * Default: 20 (the standard session batch size).
@@ -102,6 +125,64 @@ export interface ResponseResult {
   shouldClearFeedbackShadow: boolean;
 }
 
+/**
+ * Read-only snapshot of a single processed response, handed to every
+ * registered {@link OutcomeObserver} after ELO/SRS have been recorded.
+ *
+ * Only emitted for question records (non-question dismisses are skipped).
+ */
+export interface SessionOutcome {
+  /** The user's response. Includes `isCorrect`, `performance`, `priorAttemps`. */
+  readonly record: QuestionRecord;
+  /**
+   * The card that was answered, including its `tags` — the primary key an
+   * observer matches against (e.g. `gpc:exercise:*`). `card_elo` reflects
+   * pre-update state; the ELO write for this response is already in flight.
+   */
+  readonly card: StudySessionRecord['card'];
+  /** The navigation decision produced for this response (read-only). */
+  readonly result: Readonly<ResponseResult>;
+}
+
+/**
+ * The narrow capability surface handed to an {@link OutcomeObserver}. This is
+ * the *only* way an observer can affect the session — it cannot touch ELO,
+ * the queues, the timer, or mutate the `ResponseResult`. A misbehaving
+ * observer degrades to "wrong boost", never "corrupted session".
+ */
+export interface SessionControls {
+  /** Current session-durable hints, or null. For read-modify-write. */
+  getSessionHints(): ReplanHints | null;
+  /** Replace the session-durable hints wholesale (no decay). */
+  setSessionHints(hints: ReplanHints | null): void;
+  /**
+   * Merge `hints` into the existing session-durable hints via the pipeline's
+   * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
+   * Convenience for the common "add a boost on top of what's there" case.
+   * Note: multiplicative + no decay — clamp boost factors yourself if a
+   * repeatedly-failed tag could compound unboundedly.
+   */
+  mergeSessionHints(hints: ReplanHints): void;
+  /** Request a replan (e.g. `{ mode: 'merge' }` for immediate visibility). */
+  requestReplan(opts?: ReplanOptions): Promise<void>;
+}
+
+/**
+ * A consumer-supplied hook invoked after each question response is processed.
+ *
+ * Fires on *every* question response (gate inside on `record.isCorrect` /
+ * `result.nextCardAction` as needed). Awaited but isolated: a throwing
+ * observer is caught and logged, never wedging the session. Keep the
+ * synchronous body cheap and `void` any long work (e.g. a triggered replan)
+ * so you don't stall navigation.
+ *
+ * Registered via `StudySessionConfig.outcomeObservers` → constructor options.
+ */
+export type OutcomeObserver = (
+  outcome: SessionOutcome,
+  controls: SessionControls
+) => void | Promise<void>;
+
 interface SessionServices {
   response: ResponseProcessor;
 }
@@ -177,6 +258,35 @@ export class SessionController<TView = unknown> extends Loggable {
    */
   private _minCardsGuarantee: number = 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.
+   */
+  private _sessionHints: ReplanHints | null = null;
+
+  /**
+   * Consumer-supplied hooks invoked after each question response is processed.
+   * Seeded from constructor options (threaded from
+   * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+   */
+  private _outcomeObservers: OutcomeObserver[] = [];
+
+  /**
+   * Lazily-built, stable capability object handed to observers. Bound to
+   * `this`; constructed once so observers can rely on referential identity.
+   */
+  private _sessionControls: SessionControls | null = null;
+
   private startTime: Date;
   private endTime: Date;
   private _secondsRemaining: number;
@@ -219,7 +329,11 @@ export class SessionController<TView = unknown> extends Loggable {
     dataLayer: DataLayerProvider,
     getViewComponent: (viewId: string) => TView,
     mixer?: SourceMixer,
-    options?: { defaultBatchLimit?: number; initialReviewCap?: number }
+    options?: {
+      defaultBatchLimit?: number;
+      initialReviewCap?: number;
+      outcomeObservers?: OutcomeObserver[];
+    }
   ) {
     super();
 
@@ -249,6 +363,9 @@ export class SessionController<TView = unknown> extends Loggable {
     if (options?.initialReviewCap !== undefined) {
       this._initialReviewCap = options.initialReviewCap;
     }
+    if (options?.outcomeObservers?.length) {
+      this._outcomeObservers = [...options.outcomeObservers];
+    }
 
     this.log(`Session constructed:
     startTime: ${this.startTime}
@@ -409,6 +526,7 @@ export class SessionController<TView = unknown> extends Loggable {
     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;
+    if (opts.sessionHints !== undefined) return true;
     return false;
   }
 
@@ -455,17 +573,21 @@ export class SessionController<TView = unknown> extends Loggable {
 
     hints.excludeCards = [...excludeSet];
 
-    // Forward hints to all sources (CourseDB stashes them, Pipeline consumes them)
-    if (opts.hints) {
-      // Thread label into hints so Pipeline can attach it to provenance
-      const hintsWithLabel = opts.label
-        ? { ...opts.hints, _label: opts.label }
-        : opts.hints;
-      for (const source of this.sources) {
-        source.setEphemeralHints?.(hintsWithLabel);
-      }
+    // Replace session-durable hints if this replan carries them. KISS:
+    // wholesale replace, no accumulation/decay (see ReplanOptions.sessionHints).
+    if (opts.sessionHints !== undefined) {
+      this._sessionHints = opts.sessionHints;
+      this.log(
+        `[Replan] Session hints ${opts.sessionHints ? 'set' : 'cleared'}: ` +
+        `${JSON.stringify(opts.sessionHints)}`
+      );
     }
 
+    // Forward hints to all sources (CourseDB stashes them, Pipeline consumes
+    // them). The one-shot `opts.hints` are merged with the durable
+    // `_sessionHints` so session emphasis survives this and every later run.
+    this._applyHintsToSources(opts.hints, opts.label);
+
     const labelTag = opts.label ? ` [${opts.label}]` : '';
     this.log(
       `Mid-session replan requested${labelTag}` +
@@ -478,7 +600,124 @@ export class SessionController<TView = unknown> extends Loggable {
       this.log(`[Replan] Card guarantee set to ${this._minCardsGuarantee}`);
     }
 
+    // [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
+    // const tReplan0 = performance.now();
     await this._executeReplan(opts);
+    // logger.info(
+    //   `[perf][SessionController] replan${labelTag} (limit=${opts.limit ?? 'default'}, ` +
+    //     `mode=${opts.mode ?? 'replace'}) took ${(performance.now() - tReplan0).toFixed(0)}ms`
+    // );
+  }
+
+  /**
+   * 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.
+   */
+  public setSessionHints(hints: ReplanHints | null): void {
+    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).
+   */
+  public getSessionHints(): ReplanHints | null {
+    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.
+   */
+  public mergeSessionHints(hints: ReplanHints): void {
+    this._sessionHints = mergeHints([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.
+   */
+  private _applyHintsToSources(oneShot?: ReplanHints, label?: string): void {
+    // Thread the provenance label into the one-shot layer; mergeHints will
+    // fold it into the combined `_label`.
+    const oneShotWithLabel: ReplanHints | undefined =
+      oneShot && label ? { ...oneShot, _label: label } : oneShot;
+
+    const merged = mergeHints([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.
+   */
+  private _getSessionControls(): SessionControls {
+    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.
+   */
+  private async _notifyOutcomeObservers(
+    record: CardRecord,
+    currentCard: StudySessionRecord,
+    result: ResponseResult
+  ): Promise<void> {
+    if (this._outcomeObservers.length === 0) return;
+    if (!isQuestionRecord(record)) return;
+
+    const outcome: SessionOutcome = {
+      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);
+      }
+    }
   }
 
   /**
@@ -513,7 +752,7 @@ export class SessionController<TView = unknown> extends Loggable {
     if (!input) return {};
 
     // If the input has any ReplanOptions-specific key, treat it as ReplanOptions
-    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 as ReplanOptions;
@@ -691,6 +930,7 @@ export class SessionController<TView = unknown> extends Loggable {
     additive?: boolean;
     limit?: number;
   }): Promise<number> {
+    // const tGwc0 = performance.now(); // [perf] parked
     const replan = options?.replan ?? false;
     const additive = options?.additive ?? false;
     const newLimit = options?.limit ?? this._defaultBatchLimit;
@@ -699,6 +939,14 @@ export class SessionController<TView = unknown> extends Loggable {
     // never touch reviewQ, so the inflation is unnecessary there.
     const fetchLimit = replan ? newLimit : newLimit + this._initialReviewCap;
 
+    // Initial plan: push session-durable hints to sources so the very first
+    // pipeline run reflects them (e.g. a post-lesson boost). Replans push
+    // their own session+one-shot merge via _runReplan before reaching here,
+    // so we must NOT re-apply here or we'd drop their per-run excludeCards.
+    if (!replan) {
+      this._applyHintsToSources();
+    }
+
     // Collect batches from each source
     const batches: SourceBatch[] = [];
 
@@ -721,6 +969,8 @@ export class SessionController<TView = unknown> extends Loggable {
       }
     }
 
+    // const tSources = performance.now(); // [perf] parked
+
     // Verify we got content from at least one source
     if (batches.length === 0) {
       if (replan) {
@@ -736,6 +986,7 @@ export class SessionController<TView = unknown> extends Loggable {
 
     // Mix weighted cards across sources using configured strategy
     const mixedWeighted = this.mixer.mix(batches, fetchLimit * this.sources.length);
+    // const tMixed = performance.now(); // [perf] parked
 
     // Capture mixer run for debugging - fetch course names
     const sourceIds = batches.map((b) => {
@@ -834,6 +1085,18 @@ export class SessionController<TView = unknown> extends Loggable {
     }
 
     this.log(report);
+
+    // [perf] parked: getWeightedContent stage timing
+    // const tEnd = performance.now();
+    // logger.info(
+    //   `[perf][SessionController] getWeightedContent(replan=${replan}): ` +
+    //     `sources=${(tSources - tGwc0).toFixed(0)}ms ` +
+    //     `mix=${(tMixed - tSources).toFixed(0)}ms ` +
+    //     `post=${(tEnd - tMixed).toFixed(0)}ms ` +
+    //     `total=${(tEnd - tGwc0).toFixed(0)}ms ` +
+    //     `[sources=${this.sources.length} fetchLimit=${fetchLimit} newLimit=${newLimit}]`
+    // );
+
     return wellIndicated;
   }
 
@@ -938,6 +1201,10 @@ export class SessionController<TView = unknown> extends Loggable {
   public async nextCard(
     action: SessionAction = 'dismiss-success'
   ): Promise<HydratedCard<TView> | null> {
+    // [perf] parked: nextCard provenance/timing (awaitedReplan, wedgeRuns)
+    // const tNext0 = performance.now();
+    // let awaitedInFlightReplan = false;
+    // let wedgeRuns = 0;
     // dismiss (or sort to failedQ) the current card
     this.dismissCurrentCard(action);
 
@@ -959,6 +1226,7 @@ export class SessionController<TView = unknown> extends Loggable {
       this.failedQ.length === 0
     ) {
       this.log('nextCard: queues empty, awaiting in-flight replan before drawing');
+      // awaitedInFlightReplan = true; // [perf] parked
       await this._replanPromise;
     }
 
@@ -1053,6 +1321,7 @@ export class SessionController<TView = unknown> extends Loggable {
         `Running pipeline (attempt ${wedgeEmptyStreak + 1}/${WEDGE_MAX_EMPTY_STREAK}).`
       );
       await this._replanUncoalesced({ label: 'wedge-breaker' });
+      // wedgeRuns++; // [perf] parked
       if (
         this.newQ.length === 0 &&
         this.reviewQ.length === 0 &&
@@ -1115,6 +1384,11 @@ export class SessionController<TView = unknown> extends Loggable {
         // Snapshot queue state
         snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
 
+        // [perf] parked: per-draw nextCard timing
+        // logger.info(
+        //   `[perf][nextCard] -> ${card.item.cardID} in ${(performance.now() - tNext0).toFixed(0)}ms ` +
+        //     `(awaitedReplan=${awaitedInFlightReplan} wedgeRuns=${wedgeRuns})`
+        // );
         return card;
       }
 
@@ -1159,7 +1433,7 @@ export class SessionController<TView = unknown> extends Loggable {
       ...currentCard.item,
     };
 
-    return await this.services.response.processResponse(
+    const result = await this.services.response.processResponse(
       cardRecord,
       cardHistory,
       studySessionItem,
@@ -1171,6 +1445,14 @@ export class SessionController<TView = unknown> extends Loggable {
       maxSessionViews,
       sessionViews
     );
+
+    // Surface the processed outcome to any registered observers (e.g. a
+    // difficulty-booster that bumps session hints on a failed exercise tag).
+    // Runs after ELO/SRS recording, before the caller navigates. Isolated so
+    // a faulty observer can't break response handling.
+    await this._notifyOutcomeObservers(cardRecord, currentCard, result);
+
+    return result;
   }
 
   private dismissCurrentCard(action: SessionAction = 'dismiss-success') {