@vue-skuilder/db 0.2.28 → 0.2.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
  2. package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
  3. package/dist/core/index.d.cts +13 -90
  4. package/dist/core/index.d.ts +13 -90
  5. package/dist/core/index.js +587 -179
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +586 -179
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
  11. package/dist/diagnostics/index.d.cts +79 -6
  12. package/dist/diagnostics/index.d.ts +79 -6
  13. package/dist/diagnostics/index.js +158 -4
  14. package/dist/diagnostics/index.js.map +1 -1
  15. package/dist/diagnostics/index.mjs +156 -4
  16. package/dist/diagnostics/index.mjs.map +1 -1
  17. package/dist/impl/couch/index.d.cts +11 -2
  18. package/dist/impl/couch/index.d.ts +11 -2
  19. package/dist/impl/couch/index.js +585 -179
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +585 -179
  22. package/dist/impl/couch/index.mjs.map +1 -1
  23. package/dist/impl/static/index.d.cts +8 -2
  24. package/dist/impl/static/index.d.ts +8 -2
  25. package/dist/impl/static/index.js +582 -179
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +582 -179
  28. package/dist/impl/static/index.mjs.map +1 -1
  29. package/dist/index.d.cts +66 -5
  30. package/dist/index.d.ts +66 -5
  31. package/dist/index.js +635 -180
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +622 -180
  34. package/dist/index.mjs.map +1 -1
  35. package/package.json +3 -3
  36. package/src/core/interfaces/contentSource.ts +7 -0
  37. package/src/core/navigators/Pipeline.ts +145 -13
  38. package/src/core/navigators/PipelineAssembler.ts +19 -40
  39. package/src/core/navigators/PipelineDebugger.ts +11 -2
  40. package/src/core/navigators/SrsDebugger.ts +37 -12
  41. package/src/core/navigators/defaults.ts +29 -5
  42. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  43. package/src/core/navigators/filters/eloDistance.ts +261 -76
  44. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  45. package/src/core/navigators/filters/index.ts +2 -2
  46. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  47. package/src/core/navigators/filters/relativePriority.ts +5 -1
  48. package/src/core/navigators/filters/types.ts +24 -1
  49. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  50. package/src/core/navigators/generators/elo.ts +23 -53
  51. package/src/core/navigators/generators/srs.ts +27 -124
  52. package/src/core/navigators/index.ts +31 -5
  53. package/src/core/navigators/pipelinePlan.ts +245 -0
  54. package/src/core/navigators/regulators.ts +230 -0
  55. package/src/core/types/studySession.ts +3 -0
  56. package/src/diagnostics/dataset.ts +13 -2
  57. package/src/diagnostics/index.ts +3 -0
  58. package/src/diagnostics/loader.ts +5 -2
  59. package/src/diagnostics/pipeline.ts +236 -0
  60. package/src/diagnostics/text.ts +26 -3
  61. package/src/impl/couch/courseDB.ts +13 -0
  62. package/src/impl/static/courseDB.ts +9 -0
  63. package/src/index.ts +4 -0
  64. package/src/study/SessionController.ts +20 -0
  65. package/src/study/SessionOverlay.ts +7 -4
  66. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  67. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
@@ -1,7 +1,7 @@
1
1
  export { A as AdminDBInterface, d as AssignedCard, a as AssignedContent, c as AssignedCourse, b as AssignedTag, C as ClassroomDBInterface, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from '../classroomDB-DLTtLZct.cjs';
2
- import { an as LearnableWeight, M as UserOutcomeRecord, ao as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-DpQqTG3m.cjs';
3
- export { K as ActivityRecord, a9 as CardGenerator, ab as CardGeneratorFactory, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, k as ContentNavigationStrategyData, l as ContentNavigator, t as ContentSourceID, i as CourseInfo, L as CourseRegistration, c as CourseRegistrationDoc, a as CoursesDBInterface, al as FilterImpact, aa as GeneratorContext, G as GeneratorResult, ak as GeneratorSummary, T as HYDRATION_MARKER_ID, V as HydrationMarker, X as NavigatorConstructor, a5 as NavigatorRole, a6 as NavigatorRoles, a4 as Navigators, am as PipelineForecaster, ai as PipelineRunReport, R as ReplanHints, aj as RunReportCard, b as ScheduledCard, f as SessionEloEvent, d as SessionStateSnapshot, v as SessionStateSnapshotProvider, I as SessionTrackingData, a2 as StrategyContribution, m as StudyContentSource, S as StudySessionDoc, n as StudySessionFailedItem, o as StudySessionFailedNewItem, p as StudySessionFailedReviewItem, j as StudySessionItem, q as StudySessionNewItem, r as StudySessionReviewItem, g as StudySessionRunCard, h as StudySessionRunCardTrail, e as StudySessionRunSummary, J as UserConfig, A as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, w as UserDBReader, x as UserDBWriter, P as UserHydrationState, Q as UserHydrationStatus, B as UsrCrsDataInterface, ap as computeDeviation, ar as computeEffectiveWeight, aq as computeSpread, as as createOrchestrationContext, ah as drainCapturedRuns, ae as getActivePipeline, a3 as getCardOrigin, Z as getRegisteredNavigator, a0 as getRegisteredNavigatorNames, $ as getRegisteredNavigatorRole, ag as getRunsForSession, u as getStudySource, _ as hasRegisteredNavigator, a1 as initializeNavigatorRegistry, a8 as isFilter, a7 as isGenerator, s as isReview, N as makeStudySessionId, ad as mountPipelineDebugger, O as newSessionId, ac as pipelineDebugAPI, Y as registerNavigator, af as setDebugSessionId } from '../contentSource-DpQqTG3m.cjs';
4
- export { D as DataLayerProvider } from '../dataLayerProvider-Dl3cAAvQ.cjs';
2
+ import { av as LearnableWeight, T as UserOutcomeRecord, aw as OrchestrationContext, W as WeightedCard, C as CourseDBInterface } from '../contentSource-B6FrSihy.cjs';
3
+ export { P as ActivityRecord, ae as CardFilter, ag as CardFilterFactory, ah as CardGenerator, aj as CardGeneratorFactory, K as ClassroomRegistration, J as ClassroomRegistrationDesignation, L as ClassroomRegistrationDoc, b as ContentNavigationStrategyData, m as ContentNavigator, v as ContentSourceID, k as CourseInfo, Q as CourseRegistration, d as CourseRegistrationDoc, a as CoursesDBInterface, af as FilterContext, at as FilterImpact, F as FilterKind, ai as GeneratorContext, G as GeneratorResult, as as GeneratorSummary, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, a0 as NavigatorConstructor, N as NavigatorRole, ab as NavigatorRoles, aa as Navigators, au as PipelineForecaster, aq as PipelineRunReport, n as ReplanHints, ar as RunReportCard, c as ScheduledCard, h as SessionEloEvent, e as SessionStateSnapshot, x as SessionStateSnapshotProvider, M as SessionTrackingData, a8 as StrategyContribution, o as StudyContentSource, S as StudySessionDoc, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, l as StudySessionItem, s as StudySessionNewItem, t as StudySessionReviewItem, i as StudySessionRunCard, j as StudySessionRunCardTrail, f as StudySessionRunSummary, O as UserConfig, H as UserCourseSetting, E as UserCourseSettings, B as UserDBAuthenticator, U as UserDBInterface, z as UserDBReader, A as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, I as UsrCrsDataInterface, ax as computeDeviation, az as computeEffectiveWeight, ay as computeSpread, aA as createOrchestrationContext, ap as drainCapturedRuns, am as getActivePipeline, a9 as getCardOrigin, a5 as getRegisteredFilterKind, a2 as getRegisteredNavigator, a6 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, ao as getRunsForSession, w as getStudySource, a3 as hasRegisteredNavigator, a7 as initializeNavigatorRegistry, ad as isFilter, ac as isGenerator, u as isReview, V as makeStudySessionId, al as mountPipelineDebugger, X as newSessionId, ak as pipelineDebugAPI, a1 as registerNavigator, an as setDebugSessionId } from '../contentSource-B6FrSihy.cjs';
4
+ export { D as DataLayerProvider } from '../dataLayerProvider-DUxDqMtZ.cjs';
5
5
  import { D as DocType, Q as QuestionRecord, f as DocTypePrefixes, c as CardHistory, b as CardRecord } from '../types-legacy-BkOYOR6U.cjs';
6
6
  export { C as CardData, g as CourseListData, h as DataShapeData, a as DisplayableData, F as Field, G as GuestUsername, d as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, T as Tag, e as TagStub, l as log } from '../types-legacy-BkOYOR6U.cjs';
7
7
  import { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -230,13 +230,18 @@ interface SrsBacklogDebug {
230
230
  scheduledTotal: number;
231
231
  /** Reviews eligible (due) right now. */
232
232
  dueNow: number;
233
- /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
233
+ /** Healthy review mass (card-equivalents); the multiplier is ×1.0 at or below it. */
234
234
  healthyBacklog: number;
235
- /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
235
+ /**
236
+ * Review mass: the due reviews' filtered scores against a reference, each at
237
+ * most 1. Set by the regulator stage; null until it has run.
238
+ */
239
+ reviewMass: number | null;
240
+ /** Multiplier the regulator stage applied to every due review this run (>= 1.0, unbounded). */
236
241
  backlogMultiplier: number;
237
- /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
242
+ /** Exponential growth-rate base the multiplier climbs by per multiple of healthy mass in excess. */
238
243
  backlogGrowthRate: number;
239
- /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
244
+ /** Highest review urgency score from the SRS generator (before filters and regulators); null if none due. */
240
245
  topReviewScore: number | null;
241
246
  /** Human-readable time until the next review comes due, or null if some are due now. */
242
247
  nextDueIn: string | null;
@@ -295,88 +300,6 @@ declare function getStrategyPressureDebug(): StrategyPressureDebug[];
295
300
  /** Drop all captured snapshots (called on session start, alongside pipeline history). */
296
301
  declare function clearStrategyPressureDebug(): void;
297
302
 
298
- /**
299
- * Shared context available to all filters in a pipeline.
300
- *
301
- * Built once per getWeightedCards() call and passed to each filter.
302
- * This avoids repeated lookups for common data like user ELO.
303
- */
304
- interface FilterContext {
305
- /** User database interface */
306
- user: UserDBInterface;
307
- /** Course database interface */
308
- course: CourseDBInterface;
309
- /** User's global ELO score for this course */
310
- userElo: number;
311
- /** Orchestration context for evolutionary weighting */
312
- orchestration?: OrchestrationContext;
313
- }
314
- /**
315
- * A filter that transforms a list of weighted cards.
316
- *
317
- * Filters are pure transforms - they receive cards and context,
318
- * and return a modified list of cards. No delegate wrapping,
319
- * no side effects beyond provenance tracking.
320
- *
321
- * ## Implementation Guidelines
322
- *
323
- * 1. **Append provenance**: Every filter should add a StrategyContribution
324
- * entry documenting its decision for each card.
325
- *
326
- * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
327
- * This ensures filter order doesn't matter.
328
- *
329
- * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
330
- * Don't filter it out - let provenance show why it was excluded.
331
- *
332
- * 4. **Don't sort**: The Pipeline handles final sorting.
333
- * Filters just transform scores.
334
- *
335
- * ## Example Implementation
336
- *
337
- * ```typescript
338
- * const myFilter: CardFilter = {
339
- * name: 'My Filter',
340
- * async transform(cards, context) {
341
- * return cards.map(card => {
342
- * const multiplier = computeMultiplier(card, context);
343
- * const newScore = card.score * multiplier;
344
- * return {
345
- * ...card,
346
- * score: newScore,
347
- * provenance: [...card.provenance, {
348
- * strategy: 'myFilter',
349
- * strategyName: 'My Filter',
350
- * strategyId: 'MY_FILTER',
351
- * action: multiplier < 1 ? 'penalized' : 'passed',
352
- * score: newScore,
353
- * reason: 'Explanation of decision'
354
- * }]
355
- * };
356
- * });
357
- * }
358
- * };
359
- * ```
360
- */
361
- interface CardFilter {
362
- /** Human-readable name for this filter */
363
- name: string;
364
- /**
365
- * Transform a list of weighted cards.
366
- *
367
- * @param cards - Cards to transform (already scored by generator)
368
- * @param context - Shared context (user, course, userElo, etc.)
369
- * @returns Transformed cards with updated scores and provenance
370
- */
371
- transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
372
- }
373
- /**
374
- * Factory function type for creating filters from configuration.
375
- *
376
- * Used by PipelineAssembler to instantiate filters from strategy documents.
377
- */
378
- type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
379
-
380
303
  interface DiversityRerankOptions {
381
304
  /**
382
305
  * How hard repetition is penalised. Larger → steeper demotion of repeated
@@ -595,4 +518,4 @@ declare const userDBDebugAPI: {
595
518
  */
596
519
  declare function mountUserDBDebugger(): void;
597
520
 
598
- export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PressureGaugeDebug, QuestionRecord, type SignalConfig, type SrsBacklogDebug, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountUserDBDebugger, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
521
+ export { type BulkCardProcessorConfig, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PressureGaugeDebug, QuestionRecord, type SignalConfig, type SrsBacklogDebug, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountUserDBDebugger, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
@@ -1,7 +1,7 @@
1
1
  export { A as AdminDBInterface, d as AssignedCard, a as AssignedContent, c as AssignedCourse, b as AssignedTag, C as ClassroomDBInterface, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from '../classroomDB-DLTtLZct.js';
2
- import { an as LearnableWeight, M as UserOutcomeRecord, ao as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BoFBwvYa.js';
3
- export { K as ActivityRecord, a9 as CardGenerator, ab as CardGeneratorFactory, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, k as ContentNavigationStrategyData, l as ContentNavigator, t as ContentSourceID, i as CourseInfo, L as CourseRegistration, c as CourseRegistrationDoc, a as CoursesDBInterface, al as FilterImpact, aa as GeneratorContext, G as GeneratorResult, ak as GeneratorSummary, T as HYDRATION_MARKER_ID, V as HydrationMarker, X as NavigatorConstructor, a5 as NavigatorRole, a6 as NavigatorRoles, a4 as Navigators, am as PipelineForecaster, ai as PipelineRunReport, R as ReplanHints, aj as RunReportCard, b as ScheduledCard, f as SessionEloEvent, d as SessionStateSnapshot, v as SessionStateSnapshotProvider, I as SessionTrackingData, a2 as StrategyContribution, m as StudyContentSource, S as StudySessionDoc, n as StudySessionFailedItem, o as StudySessionFailedNewItem, p as StudySessionFailedReviewItem, j as StudySessionItem, q as StudySessionNewItem, r as StudySessionReviewItem, g as StudySessionRunCard, h as StudySessionRunCardTrail, e as StudySessionRunSummary, J as UserConfig, A as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, w as UserDBReader, x as UserDBWriter, P as UserHydrationState, Q as UserHydrationStatus, B as UsrCrsDataInterface, ap as computeDeviation, ar as computeEffectiveWeight, aq as computeSpread, as as createOrchestrationContext, ah as drainCapturedRuns, ae as getActivePipeline, a3 as getCardOrigin, Z as getRegisteredNavigator, a0 as getRegisteredNavigatorNames, $ as getRegisteredNavigatorRole, ag as getRunsForSession, u as getStudySource, _ as hasRegisteredNavigator, a1 as initializeNavigatorRegistry, a8 as isFilter, a7 as isGenerator, s as isReview, N as makeStudySessionId, ad as mountPipelineDebugger, O as newSessionId, ac as pipelineDebugAPI, Y as registerNavigator, af as setDebugSessionId } from '../contentSource-BoFBwvYa.js';
4
- export { D as DataLayerProvider } from '../dataLayerProvider-D_LJT3F4.js';
2
+ import { av as LearnableWeight, T as UserOutcomeRecord, aw as OrchestrationContext, W as WeightedCard, C as CourseDBInterface } from '../contentSource-CqJmbOZN.js';
3
+ export { P as ActivityRecord, ae as CardFilter, ag as CardFilterFactory, ah as CardGenerator, aj as CardGeneratorFactory, K as ClassroomRegistration, J as ClassroomRegistrationDesignation, L as ClassroomRegistrationDoc, b as ContentNavigationStrategyData, m as ContentNavigator, v as ContentSourceID, k as CourseInfo, Q as CourseRegistration, d as CourseRegistrationDoc, a as CoursesDBInterface, af as FilterContext, at as FilterImpact, F as FilterKind, ai as GeneratorContext, G as GeneratorResult, as as GeneratorSummary, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, a0 as NavigatorConstructor, N as NavigatorRole, ab as NavigatorRoles, aa as Navigators, au as PipelineForecaster, aq as PipelineRunReport, n as ReplanHints, ar as RunReportCard, c as ScheduledCard, h as SessionEloEvent, e as SessionStateSnapshot, x as SessionStateSnapshotProvider, M as SessionTrackingData, a8 as StrategyContribution, o as StudyContentSource, S as StudySessionDoc, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, l as StudySessionItem, s as StudySessionNewItem, t as StudySessionReviewItem, i as StudySessionRunCard, j as StudySessionRunCardTrail, f as StudySessionRunSummary, O as UserConfig, H as UserCourseSetting, E as UserCourseSettings, B as UserDBAuthenticator, U as UserDBInterface, z as UserDBReader, A as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, I as UsrCrsDataInterface, ax as computeDeviation, az as computeEffectiveWeight, ay as computeSpread, aA as createOrchestrationContext, ap as drainCapturedRuns, am as getActivePipeline, a9 as getCardOrigin, a5 as getRegisteredFilterKind, a2 as getRegisteredNavigator, a6 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, ao as getRunsForSession, w as getStudySource, a3 as hasRegisteredNavigator, a7 as initializeNavigatorRegistry, ad as isFilter, ac as isGenerator, u as isReview, V as makeStudySessionId, al as mountPipelineDebugger, X as newSessionId, ak as pipelineDebugAPI, a1 as registerNavigator, an as setDebugSessionId } from '../contentSource-CqJmbOZN.js';
4
+ export { D as DataLayerProvider } from '../dataLayerProvider-B9_UCvkR.js';
5
5
  import { D as DocType, Q as QuestionRecord, f as DocTypePrefixes, c as CardHistory, b as CardRecord } from '../types-legacy-BkOYOR6U.js';
6
6
  export { C as CardData, g as CourseListData, h as DataShapeData, a as DisplayableData, F as Field, G as GuestUsername, d as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, T as Tag, e as TagStub, l as log } from '../types-legacy-BkOYOR6U.js';
7
7
  import { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -230,13 +230,18 @@ interface SrsBacklogDebug {
230
230
  scheduledTotal: number;
231
231
  /** Reviews eligible (due) right now. */
232
232
  dueNow: number;
233
- /** Healthy backlog threshold; multiplier is ×1.0 at or below this. */
233
+ /** Healthy review mass (card-equivalents); the multiplier is ×1.0 at or below it. */
234
234
  healthyBacklog: number;
235
- /** Global multiplier applied to every due review's urgency this run (>= 1.0, unbounded). */
235
+ /**
236
+ * Review mass: the due reviews' filtered scores against a reference, each at
237
+ * most 1. Set by the regulator stage; null until it has run.
238
+ */
239
+ reviewMass: number | null;
240
+ /** Multiplier the regulator stage applied to every due review this run (>= 1.0, unbounded). */
236
241
  backlogMultiplier: number;
237
- /** Exponential growth-rate base the multiplier climbs by per multiple of healthyBacklog excess. */
242
+ /** Exponential growth-rate base the multiplier climbs by per multiple of healthy mass in excess. */
238
243
  backlogGrowthRate: number;
239
- /** Highest review score produced this run (post-multiplier; can exceed 1.0); null if none due. */
244
+ /** Highest review urgency score from the SRS generator (before filters and regulators); null if none due. */
240
245
  topReviewScore: number | null;
241
246
  /** Human-readable time until the next review comes due, or null if some are due now. */
242
247
  nextDueIn: string | null;
@@ -295,88 +300,6 @@ declare function getStrategyPressureDebug(): StrategyPressureDebug[];
295
300
  /** Drop all captured snapshots (called on session start, alongside pipeline history). */
296
301
  declare function clearStrategyPressureDebug(): void;
297
302
 
298
- /**
299
- * Shared context available to all filters in a pipeline.
300
- *
301
- * Built once per getWeightedCards() call and passed to each filter.
302
- * This avoids repeated lookups for common data like user ELO.
303
- */
304
- interface FilterContext {
305
- /** User database interface */
306
- user: UserDBInterface;
307
- /** Course database interface */
308
- course: CourseDBInterface;
309
- /** User's global ELO score for this course */
310
- userElo: number;
311
- /** Orchestration context for evolutionary weighting */
312
- orchestration?: OrchestrationContext;
313
- }
314
- /**
315
- * A filter that transforms a list of weighted cards.
316
- *
317
- * Filters are pure transforms - they receive cards and context,
318
- * and return a modified list of cards. No delegate wrapping,
319
- * no side effects beyond provenance tracking.
320
- *
321
- * ## Implementation Guidelines
322
- *
323
- * 1. **Append provenance**: Every filter should add a StrategyContribution
324
- * entry documenting its decision for each card.
325
- *
326
- * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
327
- * This ensures filter order doesn't matter.
328
- *
329
- * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
330
- * Don't filter it out - let provenance show why it was excluded.
331
- *
332
- * 4. **Don't sort**: The Pipeline handles final sorting.
333
- * Filters just transform scores.
334
- *
335
- * ## Example Implementation
336
- *
337
- * ```typescript
338
- * const myFilter: CardFilter = {
339
- * name: 'My Filter',
340
- * async transform(cards, context) {
341
- * return cards.map(card => {
342
- * const multiplier = computeMultiplier(card, context);
343
- * const newScore = card.score * multiplier;
344
- * return {
345
- * ...card,
346
- * score: newScore,
347
- * provenance: [...card.provenance, {
348
- * strategy: 'myFilter',
349
- * strategyName: 'My Filter',
350
- * strategyId: 'MY_FILTER',
351
- * action: multiplier < 1 ? 'penalized' : 'passed',
352
- * score: newScore,
353
- * reason: 'Explanation of decision'
354
- * }]
355
- * };
356
- * });
357
- * }
358
- * };
359
- * ```
360
- */
361
- interface CardFilter {
362
- /** Human-readable name for this filter */
363
- name: string;
364
- /**
365
- * Transform a list of weighted cards.
366
- *
367
- * @param cards - Cards to transform (already scored by generator)
368
- * @param context - Shared context (user, course, userElo, etc.)
369
- * @returns Transformed cards with updated scores and provenance
370
- */
371
- transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
372
- }
373
- /**
374
- * Factory function type for creating filters from configuration.
375
- *
376
- * Used by PipelineAssembler to instantiate filters from strategy documents.
377
- */
378
- type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
379
-
380
303
  interface DiversityRerankOptions {
381
304
  /**
382
305
  * How hard repetition is penalised. Larger → steeper demotion of repeated
@@ -595,4 +518,4 @@ declare const userDBDebugAPI: {
595
518
  */
596
519
  declare function mountUserDBDebugger(): void;
597
520
 
598
- export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PressureGaugeDebug, QuestionRecord, type SignalConfig, type SrsBacklogDebug, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountUserDBDebugger, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
521
+ export { type BulkCardProcessorConfig, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PressureGaugeDebug, QuestionRecord, type SignalConfig, type SrsBacklogDebug, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountUserDBDebugger, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };