@vue-skuilder/db 0.1.24 → 0.1.25

package/dist/{contentSource-BotbOOfX.d.ts → contentSource-BmnmvH8C.d.ts}

@@ -469,6 +469,11 @@ interface UserDBReader {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data access. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @returns The strategy's data payload, or null if no state exists
@@ -544,6 +549,11 @@ interface UserDBWriter extends DocumentUpdater {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data writes. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @param data - The strategy's data payload to store
@@ -552,6 +562,9 @@ interface UserDBWriter extends DocumentUpdater {
     /**
      * Delete strategy-specific state for a course.
      *
+     * @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      */
@@ -604,6 +617,34 @@ interface UsrCrsDataInterface {
     getScheduledReviewCount(): Promise<number>;
     getCourseSettings(): Promise<UserCourseSettings>;
     updateCourseSettings(updates: UserCourseSetting[]): void;
+    /**
+     * Get strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.getStrategyState()`.
+     * The courseId is bound at construction via `getCourseInterface(courseId)`,
+     * so callers cannot accidentally access another course's state.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @returns The state payload, or null if no state exists
+     */
+    getStrategyState<T>(strategyKey: string): Promise<T | null>;
+    /**
+     * Store strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.putStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @param data - The state payload to store
+     */
+    putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     */
+    deleteStrategyState(strategyKey: string): Promise<void>;
 }
 type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
 interface ClassroomRegistration {

package/dist/{contentSource-C90LH-OH.d.cts → contentSource-DfBbaLA-.d.cts}

@@ -469,6 +469,11 @@ interface UserDBReader {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data access. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @returns The strategy's data payload, or null if no state exists
@@ -544,6 +549,11 @@ interface UserDBWriter extends DocumentUpdater {
      * Strategies use this to persist preferences, learned patterns, or temporal
      * tracking data across sessions. Each strategy owns its own namespace.
      *
+     * @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
+     * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+     * allowing accidental cross-course data writes. The course-scoped interface binds
+     * courseId once at construction.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      * @param data - The strategy's data payload to store
@@ -552,6 +562,9 @@ interface UserDBWriter extends DocumentUpdater {
     /**
      * Delete strategy-specific state for a course.
      *
+     * @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
+     * Direct use bypasses course-scoping safety.
+     *
      * @param courseId - The course this state applies to
      * @param strategyKey - Unique key identifying the strategy (typically class name)
      */
@@ -604,6 +617,34 @@ interface UsrCrsDataInterface {
     getScheduledReviewCount(): Promise<number>;
     getCourseSettings(): Promise<UserCourseSettings>;
     updateCourseSettings(updates: UserCourseSetting[]): void;
+    /**
+     * Get strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.getStrategyState()`.
+     * The courseId is bound at construction via `getCourseInterface(courseId)`,
+     * so callers cannot accidentally access another course's state.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @returns The state payload, or null if no state exists
+     */
+    getStrategyState<T>(strategyKey: string): Promise<T | null>;
+    /**
+     * Store strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.putStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     * @param data - The state payload to store
+     */
+    putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for this course.
+     *
+     * Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
+     *
+     * @param strategyKey - Unique key identifying the state document
+     */
+    deleteStrategyState(strategyKey: string): Promise<void>;
 }
 type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
 interface ClassroomRegistration {

package/dist/core/index.d.cts

@@ -1,6 +1,6 @@
-import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-C90LH-OH.cjs';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H as SessionTrackingData, V as StrategyContribution, 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, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-C90LH-OH.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-DGKp4zFB.cjs';
+import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, V as StrategyContribution } from '../contentSource-DfBbaLA-.cjs';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H 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, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-DfBbaLA-.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-BeRXVMs5.cjs';
 import { D as DocType, i as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-JXDxinpU.cjs';
 export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-JXDxinpU.cjs';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -383,6 +383,96 @@ interface CardGenerator {
  */
 type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
 
+/**
+ * Summary of a single generator's contribution.
+ */
+interface GeneratorSummary {
+    name: string;
+    cardCount: number;
+    newCount: number;
+    reviewCount: number;
+    topScore: number;
+}
+/**
+ * Summary of a filter's impact on scores.
+ */
+interface FilterImpact {
+    name: string;
+    boosted: number;
+    penalized: number;
+    passed: number;
+    removed: number;
+}
+/**
+ * Complete record of a single pipeline execution.
+ */
+interface PipelineRunReport {
+    runId: string;
+    timestamp: Date;
+    courseId: string;
+    courseName?: string;
+    generatorName: string;
+    generators?: GeneratorSummary[];
+    generatedCount: number;
+    filters: FilterImpact[];
+    finalCount: number;
+    reviewsSelected: number;
+    newSelected: number;
+    cards: Array<{
+        cardId: string;
+        courseId: string;
+        origin: 'new' | 'review' | 'unknown';
+        finalScore: number;
+        provenance: StrategyContribution[];
+        selected: boolean;
+    }>;
+}
+/**
+ * Console API object exposed on window.skuilder.pipeline
+ */
+declare const pipelineDebugAPI: {
+    /**
+     * Get raw run history for programmatic access.
+     */
+    readonly runs: PipelineRunReport[];
+    /**
+     * Show summary of a specific pipeline run.
+     */
+    showRun(idOrIndex?: string | number): void;
+    /**
+     * Show summary of the last pipeline run.
+     */
+    showLastRun(): void;
+    /**
+     * Show detailed provenance for a specific card.
+     */
+    showCard(cardId: string): void;
+    /**
+     * Explain why reviews may or may not have been selected.
+     */
+    explainReviews(): void;
+    /**
+     * Show all runs in compact format.
+     */
+    listRuns(): void;
+    /**
+     * Export run history as JSON for bug reports.
+     */
+    export(): string;
+    /**
+     * Clear run history.
+     */
+    clear(): void;
+    /**
+     * Show help.
+     */
+    help(): void;
+};
+/**
+ * Mount the debug API on window.skuilder.pipeline
+ */
+declare function mountPipelineDebugger(): void;
+
 /**
  * Template literal type for strategy state document IDs.
  *
@@ -515,4 +605,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, QuestionRecord, type SignalConfig, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorContext, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BotbOOfX.js';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H as SessionTrackingData, V as StrategyContribution, 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, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-BotbOOfX.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-SBpz9jQf.js';
+import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, V as StrategyContribution } from '../contentSource-BmnmvH8C.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H 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, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-BmnmvH8C.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-CG9GfaAY.js';
 import { D as DocType, i as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-JXDxinpU.js';
 export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-JXDxinpU.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -383,6 +383,96 @@ interface CardGenerator {
  */
 type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
 
+/**
+ * Summary of a single generator's contribution.
+ */
+interface GeneratorSummary {
+    name: string;
+    cardCount: number;
+    newCount: number;
+    reviewCount: number;
+    topScore: number;
+}
+/**
+ * Summary of a filter's impact on scores.
+ */
+interface FilterImpact {
+    name: string;
+    boosted: number;
+    penalized: number;
+    passed: number;
+    removed: number;
+}
+/**
+ * Complete record of a single pipeline execution.
+ */
+interface PipelineRunReport {
+    runId: string;
+    timestamp: Date;
+    courseId: string;
+    courseName?: string;
+    generatorName: string;
+    generators?: GeneratorSummary[];
+    generatedCount: number;
+    filters: FilterImpact[];
+    finalCount: number;
+    reviewsSelected: number;
+    newSelected: number;
+    cards: Array<{
+        cardId: string;
+        courseId: string;
+        origin: 'new' | 'review' | 'unknown';
+        finalScore: number;
+        provenance: StrategyContribution[];
+        selected: boolean;
+    }>;
+}
+/**
+ * Console API object exposed on window.skuilder.pipeline
+ */
+declare const pipelineDebugAPI: {
+    /**
+     * Get raw run history for programmatic access.
+     */
+    readonly runs: PipelineRunReport[];
+    /**
+     * Show summary of a specific pipeline run.
+     */
+    showRun(idOrIndex?: string | number): void;
+    /**
+     * Show summary of the last pipeline run.
+     */
+    showLastRun(): void;
+    /**
+     * Show detailed provenance for a specific card.
+     */
+    showCard(cardId: string): void;
+    /**
+     * Explain why reviews may or may not have been selected.
+     */
+    explainReviews(): void;
+    /**
+     * Show all runs in compact format.
+     */
+    listRuns(): void;
+    /**
+     * Export run history as JSON for bug reports.
+     */
+    export(): string;
+    /**
+     * Clear run history.
+     */
+    clear(): void;
+    /**
+     * Show help.
+     */
+    help(): void;
+};
+/**
+ * Mount the debug API on window.skuilder.pipeline
+ */
+declare function mountPipelineDebugger(): void;
+
 /**
  * Template literal type for strategy state document IDs.
  *
@@ -515,4 +605,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, QuestionRecord, type SignalConfig, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorContext, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };