@vue-skuilder/db 0.2.2 → 0.2.3

package/dist/{types-W8n-B6HG.d.cts → types-BFUa1pa3.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.cjs';
+import { D as DocType } from './types-legacy-4tlwHnXo.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-CJrLM1Ew.d.ts → types-CHgpWQAY.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.js';
+import { D as DocType } from './types-legacy-4tlwHnXo.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-JXDxinpU.d.cts → types-legacy-4tlwHnXo.d.cts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type QuestionRecord as d, type CardData as e, type CourseListData as f, type DisplayableData as g, type DataShapeData as h, type QuestionData as i, log as l };

package/dist/{types-legacy-JXDxinpU.d.ts → types-legacy-4tlwHnXo.d.ts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type QuestionRecord as d, type CardData as e, type CourseListData as f, type DisplayableData as g, type DataShapeData as h, type QuestionData as i, log as l };

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-W8n-B6HG.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-Ba7hYbHj.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-BFUa1pa3.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-k9NFHpS1.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.cjs';
+import '../../types-legacy-4tlwHnXo.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CJrLM1Ew.js';
-export { C as CouchDBToStaticPacker } from '../../index-BWvO-_rJ.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CHgpWQAY.js';
+export { C as CouchDBToStaticPacker } from '../../index-BLLT5BYE.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.js';
+import '../../types-legacy-4tlwHnXo.js';
 import 'moment';

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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.2.2",
+    "@vue-skuilder/common": "0.2.3",
     "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.2.2"
+  "stableVersion": "0.2.3"
 }

package/src/core/navigators/Pipeline.ts

@@ -48,7 +48,7 @@ function cardMatchesTagPattern(card: WeightedCard, pattern: string): boolean {
   return (card.tags ?? []).some((tag) => globMatch(tag, pattern));
 }
 
-function mergeHints(allHints: Array<ReplanHints | null | undefined>): ReplanHints | undefined {
+export function mergeHints(allHints: Array<ReplanHints | null | undefined>): ReplanHints | undefined {
   const defined = allHints.filter((h): h is ReplanHints => h !== null && h !== undefined);
   if (defined.length === 0) return undefined;
 

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}` +
@@ -487,6 +609,117 @@ export class SessionController<TView = unknown> extends Loggable {
     // );
   }
 
+  /**
+   * 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);
+      }
+    }
+  }
+
   /**
    * Run a replan, bypassing requestReplan()'s coalesce logic.
    *
@@ -519,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;
@@ -706,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[] = [];
 
@@ -1192,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,
@@ -1204,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') {