@vue-skuilder/db 0.2.7 → 0.2.9

package/dist/{contentSource-Cplhv3bJ.d.ts → contentSource-C-0t0y0V.d.ts}

@@ -1192,6 +1192,13 @@ interface StudySessionItem {
     cardID: string;
     courseID: string;
     elo?: number;
+    /**
+     * Pipeline suitability score at queue-build time, carried for observability
+     * (the debug overlay renders the now-load-bearing supply ranking). `+INF`
+     * marks a mandatory required card. Not used for any draw decision — the
+     * supplyQ is already ordered, so the controller draws front-to-back.
+     */
+    score?: number;
 }
 interface ContentSourceID {
     type: 'course' | 'classroom';

package/dist/{contentSource-kI9_jwTu.d.cts → contentSource-jSkcOt2s.d.cts}

@@ -1192,6 +1192,13 @@ interface StudySessionItem {
     cardID: string;
     courseID: string;
     elo?: number;
+    /**
+     * Pipeline suitability score at queue-build time, carried for observability
+     * (the debug overlay renders the now-load-bearing supply ranking). `+INF`
+     * marks a mandatory required card. Not used for any draw decision — the
+     * supplyQ is already ordered, so the controller draws front-to-back.
+     */
+    score?: number;
 }
 interface ContentSourceID {
     type: 'course' | 'classroom';

package/dist/core/index.d.cts

@@ -1,6 +1,6 @@
-import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } 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, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, 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, 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, O as registerNavigator } from '../contentSource-kI9_jwTu.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-CiA2Rr0v.cjs';
+import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } from '../contentSource-jSkcOt2s.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, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, 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, 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, O as registerNavigator } from '../contentSource-jSkcOt2s.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-BDClIrFC.cjs';
 import { D as DocType, d as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-4tlwHnXo.cjs';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, 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 { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -12,6 +12,31 @@ declare abstract class Loggable {
     protected error(...args: unknown[]): void;
 }
 
+/** Per-course snapshot of SRS backlog state, captured on each SRS generator run. */
+interface SrsBacklogDebug {
+    courseId: string;
+    /** Total reviews scheduled for this course (due + not-yet-due). */
+    scheduledTotal: number;
+    /** Reviews eligible (due) right now. */
+    dueNow: number;
+    /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
+    healthyBacklog: number;
+    /** Global multiplier applied to every due review's urgency this run (1.0 → max). */
+    backlogMultiplier: number;
+    /** Max achievable backlog multiplier (the cap), for headroom context. */
+    maxBacklogMultiplier: number;
+    /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
+    topReviewScore: number | null;
+    /** Human-readable time until the next review comes due, or null if some are due now. */
+    nextDueIn: string | null;
+    /** Epoch ms of capture. */
+    timestamp: number;
+}
+/** Current backlog snapshot for every course seen, newest-first. */
+declare function getSrsBacklogDebug(): SrsBacklogDebug[];
+/** Drop all captured snapshots (called on session start, alongside pipeline history). */
+declare function clearSrsBacklogDebug(): void;
+
 /**
  * Snapshot of the learning state for a strategy.
  *
@@ -340,6 +365,37 @@ declare const DIVERSITY_FLOOR = 0.3;
  */
 declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
 
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -361,6 +417,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -742,4 +805,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, clearSrsBacklogDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } 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, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, 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, 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, O as registerNavigator } from '../contentSource-Cplhv3bJ.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-DrBqOUa3.js';
+import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } from '../contentSource-C-0t0y0V.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, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, 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, 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, O as registerNavigator } from '../contentSource-C-0t0y0V.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-BB0oi9T0.js';
 import { D as DocType, d as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-4tlwHnXo.js';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, 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 { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -12,6 +12,31 @@ declare abstract class Loggable {
     protected error(...args: unknown[]): void;
 }
 
+/** Per-course snapshot of SRS backlog state, captured on each SRS generator run. */
+interface SrsBacklogDebug {
+    courseId: string;
+    /** Total reviews scheduled for this course (due + not-yet-due). */
+    scheduledTotal: number;
+    /** Reviews eligible (due) right now. */
+    dueNow: number;
+    /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
+    healthyBacklog: number;
+    /** Global multiplier applied to every due review's urgency this run (1.0 → max). */
+    backlogMultiplier: number;
+    /** Max achievable backlog multiplier (the cap), for headroom context. */
+    maxBacklogMultiplier: number;
+    /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
+    topReviewScore: number | null;
+    /** Human-readable time until the next review comes due, or null if some are due now. */
+    nextDueIn: string | null;
+    /** Epoch ms of capture. */
+    timestamp: number;
+}
+/** Current backlog snapshot for every course seen, newest-first. */
+declare function getSrsBacklogDebug(): SrsBacklogDebug[];
+/** Drop all captured snapshots (called on session start, alongside pipeline history). */
+declare function clearSrsBacklogDebug(): void;
+
 /**
  * Snapshot of the learning state for a strategy.
  *
@@ -340,6 +365,37 @@ declare const DIVERSITY_FLOOR = 0.3;
  */
 declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
 
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -361,6 +417,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -742,4 +805,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, clearSrsBacklogDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };