@vue-skuilder/db 0.2.2 → 0.2.4

package/dist/{index-BWvO-_rJ.d.ts → index-BLLT5BYE.d.ts}

@@ -1,4 +1,4 @@
-import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-CJrLM1Ew.js';
+import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-CHgpWQAY.js';
 
 /**
  * Abstraction for file system operations needed by the migrator.

package/dist/{index-Ba7hYbHj.d.cts → index-k9NFHpS1.d.cts}

@@ -1,4 +1,4 @@
-import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-W8n-B6HG.cjs';
+import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-BFUa1pa3.cjs';
 
 /**
  * Abstraction for file system operations needed by the migrator.

package/dist/index.d.cts

@@ -1,15 +1,15 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-BMlMwSiG.cjs';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-BMlMwSiG.cjs';
-import { D as DataLayerProvider } from './dataLayerProvider-BEqB8VBR.cjs';
-import { C as CardHistory, c as CardRecord } from './types-legacy-JXDxinpU.cjs';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-JXDxinpU.cjs';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-kI9_jwTu.cjs';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-kI9_jwTu.cjs';
+import { D as DataLayerProvider } from './dataLayerProvider-CiA2Rr0v.cjs';
+import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.cjs';
+export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.cjs';
 import { Loggable } from './core/index.cjs';
 export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
 import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
-import { S as StaticCourseManifest } from './types-W8n-B6HG.cjs';
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-W8n-B6HG.cjs';
-import { F as FileSystemAdapter } from './index-Ba7hYbHj.cjs';
-export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-Ba7hYbHj.cjs';
+import { S as StaticCourseManifest } from './types-BFUa1pa3.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-BFUa1pa3.cjs';
+import { F as FileSystemAdapter } from './index-k9NFHpS1.cjs';
+export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-k9NFHpS1.cjs';
 import 'moment';
 
 /**
@@ -308,6 +308,32 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/** Per-queue debug view: total length, cumulative draws, and head-first cardIDs. */
+interface SessionQueueDebug {
+    length: number;
+    dequeueCount: number;
+    /** cardIDs in queue order, head (next draw) first. */
+    cards: string[];
+}
+/** Live snapshot of the controller, read fresh on each overlay tick. */
+interface SessionDebugSnapshot {
+    secondsRemaining: number;
+    hasCardGuarantee: boolean;
+    minCardsGuarantee: number;
+    wellIndicatedRemaining: number;
+    /** cardID of the card currently in front of the learner, if any. */
+    currentCard: string | null;
+    /** Session-durable hints re-merged into every pipeline run this session. */
+    sessionHints: ReplanHints | null;
+    /** True while a replan is executing (in-flight). */
+    replanActive: boolean;
+    /** Reason for the in-flight replan (caller label, or '(auto)'); may be stale when idle. */
+    replanLabel: string | null;
+    reviewQ: SessionQueueDebug;
+    newQ: SessionQueueDebug;
+    failedQ: SessionQueueDebug;
+}
+
 /**
  * Options for requesting a mid-session replan.
  *
@@ -318,6 +344,28 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
 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).
@@ -369,6 +417,58 @@ interface ResponseResult {
     performanceScore?: number;
     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).
+ */
+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".
+ */
+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.
+ */
+type OutcomeObserver = (outcome: SessionOutcome, controls: SessionControls) => void | Promise<void>;
 interface SessionServices {
     response: ResponseProcessor;
 }
@@ -408,6 +508,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by nextCard() to await completion before drawing from queues.
      */
     private _replanPromise;
+    /**
+     * 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.
+     */
+    private _activeReplanLabel;
     /**
      * Number of well-indicated new cards remaining before the queue
      * degrades to poorly-indicated content. Decremented on each newQ
@@ -427,6 +534,32 @@ declare class SessionController<TView = unknown> extends Loggable {
      * each nextCard() draw. Set by replans that include `minFollowUpCards`.
      */
     private _minCardsGuarantee;
+    /**
+     * 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;
+    /**
+     * Consumer-supplied hooks invoked after each question response is processed.
+     * Seeded from constructor options (threaded from
+     * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+     */
+    private _outcomeObservers;
+    /**
+     * Lazily-built, stable capability object handed to observers. Bound to
+     * `this`; constructed once so observers can rely on referential identity.
+     */
+    private _sessionControls;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -452,6 +585,7 @@ declare class SessionController<TView = unknown> extends Loggable {
     constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
         defaultBatchLimit?: number;
         initialReviewCap?: number;
+        outcomeObservers?: OutcomeObserver[];
     });
     private tick;
     /**
@@ -514,6 +648,66 @@ declare class SessionController<TView = unknown> extends Loggable {
      * newQ.peek(0) is the imminent draw we need to exclude.
      */
     private _runReplan;
+    /**
+     * 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: ReplanHints | null): void;
+    /**
+     * Read the current session-durable hints (for read-modify-write callers,
+     * e.g. an outcome observer that clamps a compounding boost).
+     */
+    getSessionHints(): ReplanHints | null;
+    /**
+     * 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(): SessionDebugSnapshot;
+    /**
+     * 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: ReplanHints): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 _notifyOutcomeObservers;
     /**
      * Run a replan, bypassing requestReplan()'s coalesce logic.
      *
@@ -906,6 +1100,11 @@ declare const sessionDebugAPI: {
      * Show current queue state.
      */
     showQueue(): void;
+    /**
+     * Toggle the pinned, live-updating DOM overlay for the active controller
+     * (queues, session hints, timer). No-ops in non-browser hosts.
+     */
+    dbgOverlay(): void;
     /**
      * Show presentation history for current or past session.
      */
@@ -1176,4 +1375,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-Ht3N2f-y.js';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-Ht3N2f-y.js';
-import { D as DataLayerProvider } from './dataLayerProvider-DObSXjnf.js';
-import { C as CardHistory, c as CardRecord } from './types-legacy-JXDxinpU.js';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-JXDxinpU.js';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-Cplhv3bJ.js';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-Cplhv3bJ.js';
+import { D as DataLayerProvider } from './dataLayerProvider-DrBqOUa3.js';
+import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.js';
+export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.js';
 import { Loggable } from './core/index.js';
 export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.js';
 import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
-import { S as StaticCourseManifest } from './types-CJrLM1Ew.js';
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CJrLM1Ew.js';
-import { F as FileSystemAdapter } from './index-BWvO-_rJ.js';
-export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-BWvO-_rJ.js';
+import { S as StaticCourseManifest } from './types-CHgpWQAY.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CHgpWQAY.js';
+import { F as FileSystemAdapter } from './index-BLLT5BYE.js';
+export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-BLLT5BYE.js';
 import 'moment';
 
 /**
@@ -308,6 +308,32 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/** Per-queue debug view: total length, cumulative draws, and head-first cardIDs. */
+interface SessionQueueDebug {
+    length: number;
+    dequeueCount: number;
+    /** cardIDs in queue order, head (next draw) first. */
+    cards: string[];
+}
+/** Live snapshot of the controller, read fresh on each overlay tick. */
+interface SessionDebugSnapshot {
+    secondsRemaining: number;
+    hasCardGuarantee: boolean;
+    minCardsGuarantee: number;
+    wellIndicatedRemaining: number;
+    /** cardID of the card currently in front of the learner, if any. */
+    currentCard: string | null;
+    /** Session-durable hints re-merged into every pipeline run this session. */
+    sessionHints: ReplanHints | null;
+    /** True while a replan is executing (in-flight). */
+    replanActive: boolean;
+    /** Reason for the in-flight replan (caller label, or '(auto)'); may be stale when idle. */
+    replanLabel: string | null;
+    reviewQ: SessionQueueDebug;
+    newQ: SessionQueueDebug;
+    failedQ: SessionQueueDebug;
+}
+
 /**
  * Options for requesting a mid-session replan.
  *
@@ -318,6 +344,28 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
 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).
@@ -369,6 +417,58 @@ interface ResponseResult {
     performanceScore?: number;
     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).
+ */
+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".
+ */
+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.
+ */
+type OutcomeObserver = (outcome: SessionOutcome, controls: SessionControls) => void | Promise<void>;
 interface SessionServices {
     response: ResponseProcessor;
 }
@@ -408,6 +508,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by nextCard() to await completion before drawing from queues.
      */
     private _replanPromise;
+    /**
+     * 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.
+     */
+    private _activeReplanLabel;
     /**
      * Number of well-indicated new cards remaining before the queue
      * degrades to poorly-indicated content. Decremented on each newQ
@@ -427,6 +534,32 @@ declare class SessionController<TView = unknown> extends Loggable {
      * each nextCard() draw. Set by replans that include `minFollowUpCards`.
      */
     private _minCardsGuarantee;
+    /**
+     * 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;
+    /**
+     * Consumer-supplied hooks invoked after each question response is processed.
+     * Seeded from constructor options (threaded from
+     * `StudySessionConfig.outcomeObservers`). See {@link OutcomeObserver}.
+     */
+    private _outcomeObservers;
+    /**
+     * Lazily-built, stable capability object handed to observers. Bound to
+     * `this`; constructed once so observers can rely on referential identity.
+     */
+    private _sessionControls;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -452,6 +585,7 @@ declare class SessionController<TView = unknown> extends Loggable {
     constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
         defaultBatchLimit?: number;
         initialReviewCap?: number;
+        outcomeObservers?: OutcomeObserver[];
     });
     private tick;
     /**
@@ -514,6 +648,66 @@ declare class SessionController<TView = unknown> extends Loggable {
      * newQ.peek(0) is the imminent draw we need to exclude.
      */
     private _runReplan;
+    /**
+     * 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: ReplanHints | null): void;
+    /**
+     * Read the current session-durable hints (for read-modify-write callers,
+     * e.g. an outcome observer that clamps a compounding boost).
+     */
+    getSessionHints(): ReplanHints | null;
+    /**
+     * 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(): SessionDebugSnapshot;
+    /**
+     * 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: ReplanHints): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 _notifyOutcomeObservers;
     /**
      * Run a replan, bypassing requestReplan()'s coalesce logic.
      *
@@ -906,6 +1100,11 @@ declare const sessionDebugAPI: {
      * Show current queue state.
      */
     showQueue(): void;
+    /**
+     * Toggle the pinned, live-updating DOM overlay for the active controller
+     * (queues, session hints, timer). No-ops in non-browser hosts.
+     */
+    dbgOverlay(): void;
     /**
      * Show presentation history for current or past session.
      */
@@ -1176,4 +1375,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };