@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
@@ -469,6 +469,86 @@ interface CardSpaceDiagnosis {
469
469
  elapsedMs: number;
470
470
  }
471
471
 
472
+ type RegulatorName = 'review-mass' | 'intake';
473
+ /** One regulator's reading for one pipeline run. Persisted on run summaries. */
474
+ interface RegulatorReading {
475
+ name: RegulatorName;
476
+ /** The class the multiplier applies to. */
477
+ class: 'review' | 'new';
478
+ /** The valve's urgency: review mass (card-equivalents) or intake hours. */
479
+ urgency: number;
480
+ multiplier: number;
481
+ /** Candidates the multiplier applied to. */
482
+ applied: number;
483
+ inputs: Record<string, number>;
484
+ }
485
+ interface RegulatorConfig {
486
+ reviewMass: {
487
+ /**
488
+ * Unit of mass for reviews without an SRS urgency (from another
489
+ * generator): a filtered score this high weighs 1.
490
+ */
491
+ referenceScore: number;
492
+ /** Mass (card-equivalents) at or below which there's no pressure. */
493
+ healthyMass: number;
494
+ /** Multiplier growth per multiple of `healthyMass` in excess. */
495
+ rate: number;
496
+ };
497
+ intake: {
498
+ /** Multiplier growth per `scaleHours` without a new card. */
499
+ rate: number;
500
+ scaleHours: number;
501
+ };
502
+ }
503
+ /**
504
+ * Defaults. Review mass keeps the SRS generator's former healthy threshold and
505
+ * growth rate (20, ×2), now applied to mass instead of count. Intake doubles
506
+ * per day of servable time without a new card.
507
+ */
508
+ declare const DEFAULT_REGULATOR_CONFIG: RegulatorConfig;
509
+ /**
510
+ * One due review's weight in the mass, in [0, 1]: its SRS urgency times the
511
+ * filters' net effect on it (filtered score ÷ the score it was generated
512
+ * with), so every course signal discounts it. A review without an urgency
513
+ * weighs its filtered score against the reference.
514
+ */
515
+ declare function reviewWeight(card: WeightedCard, generatedScore: number | undefined, referenceScore: number): number;
516
+ /**
517
+ * @param reviews - Due reviews, after filters
518
+ * @param generatedScores - Each card's score as generated, before filters
519
+ */
520
+ declare function reviewMassReading(reviews: WeightedCard[], generatedScores: ReadonlyMap<string, number>, config?: RegulatorConfig['reviewMass']): RegulatorReading;
521
+ /** The intake valve's clock, persisted per user and course (strategy state). */
522
+ interface IntakeClockState {
523
+ /** When a new card was last presented (ISO). */
524
+ lastNewAt: string;
525
+ /** Closed stretches since then during which no eligible new card existed (ms). */
526
+ frozenMs: number;
527
+ /** Start of the current stretch with no eligible new card (ISO), or null. */
528
+ unservableSince: string | null;
529
+ }
530
+ /** Strategy-state key for the intake clock. */
531
+ declare const INTAKE_CLOCK_KEY = "IntakeClock";
532
+ /** A fresh clock: a new card was just presented (or the clock is starting). */
533
+ declare function resetIntakeClock(nowMs: number): IntakeClockState;
534
+ /** Frozen time so far, including an open unservable stretch. */
535
+ declare function frozenMsAt(state: IntakeClockState, nowMs: number): number;
536
+ /** Servable hours since a new card was last presented. */
537
+ declare function intakeHours(state: IntakeClockState, nowMs: number): number;
538
+ /**
539
+ * Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
540
+ * eligible new candidates. The clock freezes while there are none (exhaustion
541
+ * isn't starvation) and resumes when some appear. Returns the same object when
542
+ * nothing changed, so callers persist only on transitions.
543
+ */
544
+ declare function stepIntakeClock(state: IntakeClockState, nowMs: number, eligibleNew: number): IntakeClockState;
545
+ declare function intakeReading(state: IntakeClockState, nowMs: number, counts: {
546
+ eligibleNew: number;
547
+ newCandidates: number;
548
+ }, config?: RegulatorConfig['intake']): RegulatorReading;
549
+ /** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
550
+ declare function applyReading(cards: WeightedCard[], reading: RegulatorReading): void;
551
+
472
552
  /**
473
553
  * The most recently constructed pipeline for the current session, or null if
474
554
  * none has been built yet. This is the supported, non-debug accessor for
@@ -491,6 +571,8 @@ interface GeneratorSummary {
491
571
  */
492
572
  interface FilterImpact {
493
573
  name: string;
574
+ /** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
575
+ kind?: FilterKind;
494
576
  boosted: number;
495
577
  penalized: number;
496
578
  passed: number;
@@ -558,6 +640,8 @@ interface PipelineRunReport {
558
640
  nextInLine?: RunReportCard;
559
641
  topGenerated?: RunReportCard;
560
642
  };
643
+ /** The regulator stage's readings: each class's pressure and the multiplier it got. */
644
+ regulators?: RegulatorReading[];
561
645
  /**
562
646
  * Summary of the discarded tail of the candidate pool — cards that were
563
647
  * generated and scored but neither selected nor retained in `cards`.
@@ -799,6 +883,8 @@ interface StudySessionRunSummary {
799
883
  nextInLine?: StudySessionRunCardTrail;
800
884
  topGenerated?: StudySessionRunCardTrail;
801
885
  };
886
+ /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
887
+ regulators?: RegulatorReading[];
802
888
  }
803
889
  /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
804
890
  interface StudySessionRunCard {
@@ -1247,6 +1333,107 @@ interface ClassroomRegistrationDoc {
1247
1333
  registrations: ClassroomRegistration[];
1248
1334
  }
1249
1335
 
1336
+ /**
1337
+ * Shared context available to all filters in a pipeline.
1338
+ *
1339
+ * Built once per getWeightedCards() call and passed to each filter.
1340
+ * This avoids repeated lookups for common data like user ELO.
1341
+ */
1342
+ interface FilterContext {
1343
+ /** User database interface */
1344
+ user: UserDBInterface;
1345
+ /** Course database interface */
1346
+ course: CourseDBInterface;
1347
+ /** User's global ELO score for this course */
1348
+ userElo: number;
1349
+ /** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
1350
+ userCourseElo?: CourseElo;
1351
+ /** Orchestration context for evolutionary weighting */
1352
+ orchestration?: OrchestrationContext;
1353
+ }
1354
+ /**
1355
+ * A filter that transforms a list of weighted cards.
1356
+ *
1357
+ * Filters are pure transforms - they receive cards and context,
1358
+ * and return a modified list of cards. No delegate wrapping,
1359
+ * no side effects beyond provenance tracking.
1360
+ *
1361
+ * ## Implementation Guidelines
1362
+ *
1363
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
1364
+ * entry documenting its decision for each card.
1365
+ *
1366
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
1367
+ * This ensures filter order doesn't matter.
1368
+ *
1369
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
1370
+ * Don't filter it out - let provenance show why it was excluded.
1371
+ *
1372
+ * 4. **Don't sort**: The Pipeline handles final sorting.
1373
+ * Filters just transform scores.
1374
+ *
1375
+ * ## Example Implementation
1376
+ *
1377
+ * ```typescript
1378
+ * const myFilter: CardFilter = {
1379
+ * name: 'My Filter',
1380
+ * async transform(cards, context) {
1381
+ * return cards.map(card => {
1382
+ * const multiplier = computeMultiplier(card, context);
1383
+ * const newScore = card.score * multiplier;
1384
+ * return {
1385
+ * ...card,
1386
+ * score: newScore,
1387
+ * provenance: [...card.provenance, {
1388
+ * strategy: 'myFilter',
1389
+ * strategyName: 'My Filter',
1390
+ * strategyId: 'MY_FILTER',
1391
+ * action: multiplier < 1 ? 'penalized' : 'passed',
1392
+ * score: newScore,
1393
+ * reason: 'Explanation of decision'
1394
+ * }]
1395
+ * };
1396
+ * });
1397
+ * }
1398
+ * };
1399
+ * ```
1400
+ */
1401
+ /**
1402
+ * What a filter's penalties mean. A `gate` says a card isn't ready yet
1403
+ * (prerequisites, lessons, unlocks); a `signal` expresses preference
1404
+ * (priority, interference, ELO distance).
1405
+ */
1406
+ type FilterKind = 'gate' | 'signal';
1407
+ interface CardFilter {
1408
+ /** Human-readable name for this filter */
1409
+ name: string;
1410
+ /**
1411
+ * Regulators lift only new cards that no gate penalized, so pressure can't
1412
+ * override "not ready". Undeclared filters count as gates: a penalty of
1413
+ * unknown meaning shouldn't be overridden by pressure.
1414
+ */
1415
+ kind?: FilterKind;
1416
+ /**
1417
+ * Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
1418
+ * card at 1.0 without a generator, and skip these filters.
1419
+ */
1420
+ liveOnly?: boolean;
1421
+ /**
1422
+ * Transform a list of weighted cards.
1423
+ *
1424
+ * @param cards - Cards to transform (already scored by generator)
1425
+ * @param context - Shared context (user, course, userElo, etc.)
1426
+ * @returns Transformed cards with updated scores and provenance
1427
+ */
1428
+ transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
1429
+ }
1430
+ /**
1431
+ * Factory function type for creating filters from configuration.
1432
+ *
1433
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
1434
+ */
1435
+ type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
1436
+
1250
1437
  /**
1251
1438
  * Type for navigator constructor functions.
1252
1439
  */
@@ -1287,6 +1474,13 @@ declare function hasRegisteredNavigator(implementingClass: string): boolean;
1287
1474
  * @returns The role, or undefined if not registered or no role was specified
1288
1475
  */
1289
1476
  declare function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined;
1477
+ /**
1478
+ * A registered filter's declared kind (see `CardFilter.kind`): the static
1479
+ * `kind` on its class. Undefined if unregistered or undeclared; undeclared
1480
+ * filters count as gates at run time.
1481
+ * @param implementingClass - The class name to look up
1482
+ */
1483
+ declare function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined;
1290
1484
  /**
1291
1485
  * Get all registered navigator names.
1292
1486
  * Useful for debugging and testing.
@@ -1408,6 +1602,17 @@ interface WeightedCard {
1408
1602
  * Used by SessionController to track review outcomes and maintain review state.
1409
1603
  */
1410
1604
  reviewID?: string;
1605
+ /**
1606
+ * The card's global ELO, when the generator already knows it (the ELO
1607
+ * generator reads it during retrieval). Lets the ELO distance filter skip a
1608
+ * fetch.
1609
+ */
1610
+ cardElo?: number;
1611
+ /**
1612
+ * A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
1613
+ * the SRS generator. The review-mass regulator weighs the backlog by it.
1614
+ */
1615
+ reviewUrgency?: number;
1411
1616
  }
1412
1617
  /**
1413
1618
  * Extract card origin from provenance trail.
@@ -1427,7 +1632,8 @@ declare enum Navigators {
1427
1632
  HIERARCHY = "hierarchyDefinition",
1428
1633
  INTERFERENCE = "interferenceMitigator",
1429
1634
  RELATIVE_PRIORITY = "relativePriority",
1430
- USER_TAG_PREFERENCE = "userTagPreference"
1635
+ USER_TAG_PREFERENCE = "userTagPreference",
1636
+ ELO_DISTANCE = "eloDistance"
1431
1637
  }
1432
1638
  /**
1433
1639
  * Role classification for navigation strategies.
@@ -1748,7 +1954,17 @@ interface StudyContentSource {
1748
1954
  * No-op for sources that don't support hints.
1749
1955
  */
1750
1956
  setEphemeralHints?(hints: ReplanHints): void;
1957
+ /**
1958
+ * A card was just presented. `status` is the session item's (`'new'`,
1959
+ * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
1960
+ * presentation to restart their intake valve's clock.
1961
+ */
1962
+ notePresented?(card: {
1963
+ cardId: string;
1964
+ courseId: string;
1965
+ status: string;
1966
+ }): void;
1751
1967
  }
1752
1968
  declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
1753
1969
 
1754
- export { getRegisteredNavigatorRole as $, type UserCourseSetting as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, makeStudySessionId as N, newSessionId as O, type UserHydrationState as P, type UserHydrationStatus as Q, type ReplanHints as R, type StudySessionDoc as S, HYDRATION_MARKER_ID as T, type UserDBInterface as U, type HydrationMarker as V, type WeightedCard as W, type NavigatorConstructor as X, registerNavigator as Y, getRegisteredNavigator as Z, hasRegisteredNavigator as _, type CoursesDBInterface as a, getRegisteredNavigatorNames as a0, initializeNavigatorRegistry as a1, type StrategyContribution as a2, getCardOrigin as a3, Navigators as a4, NavigatorRole as a5, NavigatorRoles as a6, isGenerator as a7, isFilter as a8, type CardGenerator as a9, type GeneratorContext as aa, type CardGeneratorFactory as ab, pipelineDebugAPI as ac, mountPipelineDebugger as ad, getActivePipeline as ae, setDebugSessionId as af, getRunsForSession as ag, drainCapturedRuns as ah, type PipelineRunReport as ai, type RunReportCard as aj, type GeneratorSummary as ak, type FilterImpact as al, type PipelineForecaster as am, type LearnableWeight as an, type OrchestrationContext as ao, computeDeviation as ap, computeSpread as aq, computeEffectiveWeight as ar, createOrchestrationContext as as, type DocumentUpdater as at, newInterval as au, getStreak as av, getLapses as aw, type ScheduledCard as b, type CourseRegistrationDoc as c, type SessionStateSnapshot as d, type StudySessionRunSummary as e, type SessionEloEvent as f, type StudySessionRunCard as g, type StudySessionRunCardTrail as h, type CourseInfo as i, type StudySessionItem as j, type ContentNavigationStrategyData as k, ContentNavigator as l, type StudyContentSource as m, type StudySessionFailedItem as n, type StudySessionFailedNewItem as o, type StudySessionFailedReviewItem as p, type StudySessionNewItem as q, type StudySessionReviewItem as r, isReview as s, type ContentSourceID as t, getStudySource as u, type SessionStateSnapshotProvider as v, type UserDBReader as w, type UserDBWriter as x, type UserDBAuthenticator as y, type UserCourseSettings as z };
1970
+ export { type HydrationMarker as $, type UserDBWriter as A, type UserDBAuthenticator as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSettings as E, type FilterKind as F, type GeneratorResult as G, type UserCourseSetting as H, type UsrCrsDataInterface as I, type ClassroomRegistrationDesignation as J, type ClassroomRegistration as K, type ClassroomRegistrationDoc as L, type SessionTrackingData as M, NavigatorRole as N, type UserConfig as O, type ActivityRecord as P, type CourseRegistration as Q, type RegulatorReading as R, type StudySessionDoc as S, type UserOutcomeRecord as T, type UserDBInterface as U, makeStudySessionId as V, type WeightedCard as W, newSessionId as X, type UserHydrationState as Y, type UserHydrationStatus as Z, HYDRATION_MARKER_ID as _, type CoursesDBInterface as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredFilterKind as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, createOrchestrationContext as aA, DEFAULT_REGULATOR_CONFIG as aB, reviewWeight as aC, reviewMassReading as aD, type IntakeClockState as aE, INTAKE_CLOCK_KEY as aF, resetIntakeClock as aG, frozenMsAt as aH, intakeHours as aI, stepIntakeClock as aJ, intakeReading as aK, applyReading as aL, type DocumentUpdater as aM, newInterval as aN, getStreak as aO, getLapses as aP, Navigators as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardFilter as ae, type FilterContext as af, type CardFilterFactory as ag, type CardGenerator as ah, type GeneratorContext as ai, type CardGeneratorFactory as aj, pipelineDebugAPI as ak, mountPipelineDebugger as al, getActivePipeline as am, setDebugSessionId as an, getRunsForSession as ao, drainCapturedRuns as ap, type PipelineRunReport as aq, type RunReportCard as ar, type GeneratorSummary as as, type FilterImpact as at, type PipelineForecaster as au, type LearnableWeight as av, type OrchestrationContext as aw, computeDeviation as ax, computeSpread as ay, computeEffectiveWeight as az, type ContentNavigationStrategyData as b, type ScheduledCard as c, type CourseRegistrationDoc as d, type SessionStateSnapshot as e, type StudySessionRunSummary as f, type RegulatorName as g, type SessionEloEvent as h, type StudySessionRunCard as i, type StudySessionRunCardTrail as j, type CourseInfo as k, type StudySessionItem as l, ContentNavigator as m, type ReplanHints as n, type StudyContentSource as o, type StudySessionFailedItem as p, type StudySessionFailedNewItem as q, type StudySessionFailedReviewItem as r, type StudySessionNewItem as s, type StudySessionReviewItem as t, isReview as u, type ContentSourceID as v, getStudySource as w, type SessionStateSnapshotProvider as x, type RegulatorConfig as y, type UserDBReader as z };
@@ -469,6 +469,86 @@ interface CardSpaceDiagnosis {
469
469
  elapsedMs: number;
470
470
  }
471
471
 
472
+ type RegulatorName = 'review-mass' | 'intake';
473
+ /** One regulator's reading for one pipeline run. Persisted on run summaries. */
474
+ interface RegulatorReading {
475
+ name: RegulatorName;
476
+ /** The class the multiplier applies to. */
477
+ class: 'review' | 'new';
478
+ /** The valve's urgency: review mass (card-equivalents) or intake hours. */
479
+ urgency: number;
480
+ multiplier: number;
481
+ /** Candidates the multiplier applied to. */
482
+ applied: number;
483
+ inputs: Record<string, number>;
484
+ }
485
+ interface RegulatorConfig {
486
+ reviewMass: {
487
+ /**
488
+ * Unit of mass for reviews without an SRS urgency (from another
489
+ * generator): a filtered score this high weighs 1.
490
+ */
491
+ referenceScore: number;
492
+ /** Mass (card-equivalents) at or below which there's no pressure. */
493
+ healthyMass: number;
494
+ /** Multiplier growth per multiple of `healthyMass` in excess. */
495
+ rate: number;
496
+ };
497
+ intake: {
498
+ /** Multiplier growth per `scaleHours` without a new card. */
499
+ rate: number;
500
+ scaleHours: number;
501
+ };
502
+ }
503
+ /**
504
+ * Defaults. Review mass keeps the SRS generator's former healthy threshold and
505
+ * growth rate (20, ×2), now applied to mass instead of count. Intake doubles
506
+ * per day of servable time without a new card.
507
+ */
508
+ declare const DEFAULT_REGULATOR_CONFIG: RegulatorConfig;
509
+ /**
510
+ * One due review's weight in the mass, in [0, 1]: its SRS urgency times the
511
+ * filters' net effect on it (filtered score ÷ the score it was generated
512
+ * with), so every course signal discounts it. A review without an urgency
513
+ * weighs its filtered score against the reference.
514
+ */
515
+ declare function reviewWeight(card: WeightedCard, generatedScore: number | undefined, referenceScore: number): number;
516
+ /**
517
+ * @param reviews - Due reviews, after filters
518
+ * @param generatedScores - Each card's score as generated, before filters
519
+ */
520
+ declare function reviewMassReading(reviews: WeightedCard[], generatedScores: ReadonlyMap<string, number>, config?: RegulatorConfig['reviewMass']): RegulatorReading;
521
+ /** The intake valve's clock, persisted per user and course (strategy state). */
522
+ interface IntakeClockState {
523
+ /** When a new card was last presented (ISO). */
524
+ lastNewAt: string;
525
+ /** Closed stretches since then during which no eligible new card existed (ms). */
526
+ frozenMs: number;
527
+ /** Start of the current stretch with no eligible new card (ISO), or null. */
528
+ unservableSince: string | null;
529
+ }
530
+ /** Strategy-state key for the intake clock. */
531
+ declare const INTAKE_CLOCK_KEY = "IntakeClock";
532
+ /** A fresh clock: a new card was just presented (or the clock is starting). */
533
+ declare function resetIntakeClock(nowMs: number): IntakeClockState;
534
+ /** Frozen time so far, including an open unservable stretch. */
535
+ declare function frozenMsAt(state: IntakeClockState, nowMs: number): number;
536
+ /** Servable hours since a new card was last presented. */
537
+ declare function intakeHours(state: IntakeClockState, nowMs: number): number;
538
+ /**
539
+ * Advance the clock's freeze bookkeeping for a run that found `eligibleNew`
540
+ * eligible new candidates. The clock freezes while there are none (exhaustion
541
+ * isn't starvation) and resumes when some appear. Returns the same object when
542
+ * nothing changed, so callers persist only on transitions.
543
+ */
544
+ declare function stepIntakeClock(state: IntakeClockState, nowMs: number, eligibleNew: number): IntakeClockState;
545
+ declare function intakeReading(state: IntakeClockState, nowMs: number, counts: {
546
+ eligibleNew: number;
547
+ newCandidates: number;
548
+ }, config?: RegulatorConfig['intake']): RegulatorReading;
549
+ /** Multiply `cards` (in place) by a reading's multiplier, with a provenance entry when it changes them. */
550
+ declare function applyReading(cards: WeightedCard[], reading: RegulatorReading): void;
551
+
472
552
  /**
473
553
  * The most recently constructed pipeline for the current session, or null if
474
554
  * none has been built yet. This is the supported, non-debug accessor for
@@ -491,6 +571,8 @@ interface GeneratorSummary {
491
571
  */
492
572
  interface FilterImpact {
493
573
  name: string;
574
+ /** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
575
+ kind?: FilterKind;
494
576
  boosted: number;
495
577
  penalized: number;
496
578
  passed: number;
@@ -558,6 +640,8 @@ interface PipelineRunReport {
558
640
  nextInLine?: RunReportCard;
559
641
  topGenerated?: RunReportCard;
560
642
  };
643
+ /** The regulator stage's readings: each class's pressure and the multiplier it got. */
644
+ regulators?: RegulatorReading[];
561
645
  /**
562
646
  * Summary of the discarded tail of the candidate pool — cards that were
563
647
  * generated and scored but neither selected nor retained in `cards`.
@@ -799,6 +883,8 @@ interface StudySessionRunSummary {
799
883
  nextInLine?: StudySessionRunCardTrail;
800
884
  topGenerated?: StudySessionRunCardTrail;
801
885
  };
886
+ /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
887
+ regulators?: RegulatorReading[];
802
888
  }
803
889
  /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
804
890
  interface StudySessionRunCard {
@@ -1247,6 +1333,107 @@ interface ClassroomRegistrationDoc {
1247
1333
  registrations: ClassroomRegistration[];
1248
1334
  }
1249
1335
 
1336
+ /**
1337
+ * Shared context available to all filters in a pipeline.
1338
+ *
1339
+ * Built once per getWeightedCards() call and passed to each filter.
1340
+ * This avoids repeated lookups for common data like user ELO.
1341
+ */
1342
+ interface FilterContext {
1343
+ /** User database interface */
1344
+ user: UserDBInterface;
1345
+ /** Course database interface */
1346
+ course: CourseDBInterface;
1347
+ /** User's global ELO score for this course */
1348
+ userElo: number;
1349
+ /** User's full ELO for this course: global and per tag. Absent if it couldn't be read. */
1350
+ userCourseElo?: CourseElo;
1351
+ /** Orchestration context for evolutionary weighting */
1352
+ orchestration?: OrchestrationContext;
1353
+ }
1354
+ /**
1355
+ * A filter that transforms a list of weighted cards.
1356
+ *
1357
+ * Filters are pure transforms - they receive cards and context,
1358
+ * and return a modified list of cards. No delegate wrapping,
1359
+ * no side effects beyond provenance tracking.
1360
+ *
1361
+ * ## Implementation Guidelines
1362
+ *
1363
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
1364
+ * entry documenting its decision for each card.
1365
+ *
1366
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
1367
+ * This ensures filter order doesn't matter.
1368
+ *
1369
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
1370
+ * Don't filter it out - let provenance show why it was excluded.
1371
+ *
1372
+ * 4. **Don't sort**: The Pipeline handles final sorting.
1373
+ * Filters just transform scores.
1374
+ *
1375
+ * ## Example Implementation
1376
+ *
1377
+ * ```typescript
1378
+ * const myFilter: CardFilter = {
1379
+ * name: 'My Filter',
1380
+ * async transform(cards, context) {
1381
+ * return cards.map(card => {
1382
+ * const multiplier = computeMultiplier(card, context);
1383
+ * const newScore = card.score * multiplier;
1384
+ * return {
1385
+ * ...card,
1386
+ * score: newScore,
1387
+ * provenance: [...card.provenance, {
1388
+ * strategy: 'myFilter',
1389
+ * strategyName: 'My Filter',
1390
+ * strategyId: 'MY_FILTER',
1391
+ * action: multiplier < 1 ? 'penalized' : 'passed',
1392
+ * score: newScore,
1393
+ * reason: 'Explanation of decision'
1394
+ * }]
1395
+ * };
1396
+ * });
1397
+ * }
1398
+ * };
1399
+ * ```
1400
+ */
1401
+ /**
1402
+ * What a filter's penalties mean. A `gate` says a card isn't ready yet
1403
+ * (prerequisites, lessons, unlocks); a `signal` expresses preference
1404
+ * (priority, interference, ELO distance).
1405
+ */
1406
+ type FilterKind = 'gate' | 'signal';
1407
+ interface CardFilter {
1408
+ /** Human-readable name for this filter */
1409
+ name: string;
1410
+ /**
1411
+ * Regulators lift only new cards that no gate penalized, so pressure can't
1412
+ * override "not ready". Undeclared filters count as gates: a penalty of
1413
+ * unknown meaning shouldn't be overridden by pressure.
1414
+ */
1415
+ kind?: FilterKind;
1416
+ /**
1417
+ * Applies to live runs only. `forecast` and `diagnoseCardSpace` start every
1418
+ * card at 1.0 without a generator, and skip these filters.
1419
+ */
1420
+ liveOnly?: boolean;
1421
+ /**
1422
+ * Transform a list of weighted cards.
1423
+ *
1424
+ * @param cards - Cards to transform (already scored by generator)
1425
+ * @param context - Shared context (user, course, userElo, etc.)
1426
+ * @returns Transformed cards with updated scores and provenance
1427
+ */
1428
+ transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
1429
+ }
1430
+ /**
1431
+ * Factory function type for creating filters from configuration.
1432
+ *
1433
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
1434
+ */
1435
+ type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
1436
+
1250
1437
  /**
1251
1438
  * Type for navigator constructor functions.
1252
1439
  */
@@ -1287,6 +1474,13 @@ declare function hasRegisteredNavigator(implementingClass: string): boolean;
1287
1474
  * @returns The role, or undefined if not registered or no role was specified
1288
1475
  */
1289
1476
  declare function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined;
1477
+ /**
1478
+ * A registered filter's declared kind (see `CardFilter.kind`): the static
1479
+ * `kind` on its class. Undefined if unregistered or undeclared; undeclared
1480
+ * filters count as gates at run time.
1481
+ * @param implementingClass - The class name to look up
1482
+ */
1483
+ declare function getRegisteredFilterKind(implementingClass: string): FilterKind | undefined;
1290
1484
  /**
1291
1485
  * Get all registered navigator names.
1292
1486
  * Useful for debugging and testing.
@@ -1408,6 +1602,17 @@ interface WeightedCard {
1408
1602
  * Used by SessionController to track review outcomes and maintain review state.
1409
1603
  */
1410
1604
  reviewID?: string;
1605
+ /**
1606
+ * The card's global ELO, when the generator already knows it (the ELO
1607
+ * generator reads it during retrieval). Lets the ELO distance filter skip a
1608
+ * fetch.
1609
+ */
1610
+ cardElo?: number;
1611
+ /**
1612
+ * A review's SRS urgency in [0, 1] (overdueness and interval recency), set by
1613
+ * the SRS generator. The review-mass regulator weighs the backlog by it.
1614
+ */
1615
+ reviewUrgency?: number;
1411
1616
  }
1412
1617
  /**
1413
1618
  * Extract card origin from provenance trail.
@@ -1427,7 +1632,8 @@ declare enum Navigators {
1427
1632
  HIERARCHY = "hierarchyDefinition",
1428
1633
  INTERFERENCE = "interferenceMitigator",
1429
1634
  RELATIVE_PRIORITY = "relativePriority",
1430
- USER_TAG_PREFERENCE = "userTagPreference"
1635
+ USER_TAG_PREFERENCE = "userTagPreference",
1636
+ ELO_DISTANCE = "eloDistance"
1431
1637
  }
1432
1638
  /**
1433
1639
  * Role classification for navigation strategies.
@@ -1748,7 +1954,17 @@ interface StudyContentSource {
1748
1954
  * No-op for sources that don't support hints.
1749
1955
  */
1750
1956
  setEphemeralHints?(hints: ReplanHints): void;
1957
+ /**
1958
+ * A card was just presented. `status` is the session item's (`'new'`,
1959
+ * `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
1960
+ * presentation to restart their intake valve's clock.
1961
+ */
1962
+ notePresented?(card: {
1963
+ cardId: string;
1964
+ courseId: string;
1965
+ status: string;
1966
+ }): void;
1751
1967
  }
1752
1968
  declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
1753
1969
 
1754
- export { getRegisteredNavigatorRole as $, type UserCourseSetting as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, makeStudySessionId as N, newSessionId as O, type UserHydrationState as P, type UserHydrationStatus as Q, type ReplanHints as R, type StudySessionDoc as S, HYDRATION_MARKER_ID as T, type UserDBInterface as U, type HydrationMarker as V, type WeightedCard as W, type NavigatorConstructor as X, registerNavigator as Y, getRegisteredNavigator as Z, hasRegisteredNavigator as _, type CoursesDBInterface as a, getRegisteredNavigatorNames as a0, initializeNavigatorRegistry as a1, type StrategyContribution as a2, getCardOrigin as a3, Navigators as a4, NavigatorRole as a5, NavigatorRoles as a6, isGenerator as a7, isFilter as a8, type CardGenerator as a9, type GeneratorContext as aa, type CardGeneratorFactory as ab, pipelineDebugAPI as ac, mountPipelineDebugger as ad, getActivePipeline as ae, setDebugSessionId as af, getRunsForSession as ag, drainCapturedRuns as ah, type PipelineRunReport as ai, type RunReportCard as aj, type GeneratorSummary as ak, type FilterImpact as al, type PipelineForecaster as am, type LearnableWeight as an, type OrchestrationContext as ao, computeDeviation as ap, computeSpread as aq, computeEffectiveWeight as ar, createOrchestrationContext as as, type DocumentUpdater as at, newInterval as au, getStreak as av, getLapses as aw, type ScheduledCard as b, type CourseRegistrationDoc as c, type SessionStateSnapshot as d, type StudySessionRunSummary as e, type SessionEloEvent as f, type StudySessionRunCard as g, type StudySessionRunCardTrail as h, type CourseInfo as i, type StudySessionItem as j, type ContentNavigationStrategyData as k, ContentNavigator as l, type StudyContentSource as m, type StudySessionFailedItem as n, type StudySessionFailedNewItem as o, type StudySessionFailedReviewItem as p, type StudySessionNewItem as q, type StudySessionReviewItem as r, isReview as s, type ContentSourceID as t, getStudySource as u, type SessionStateSnapshotProvider as v, type UserDBReader as w, type UserDBWriter as x, type UserDBAuthenticator as y, type UserCourseSettings as z };
1970
+ export { type HydrationMarker as $, type UserDBWriter as A, type UserDBAuthenticator as B, type CourseDBInterface as C, type DataLayerResult as D, type UserCourseSettings as E, type FilterKind as F, type GeneratorResult as G, type UserCourseSetting as H, type UsrCrsDataInterface as I, type ClassroomRegistrationDesignation as J, type ClassroomRegistration as K, type ClassroomRegistrationDoc as L, type SessionTrackingData as M, NavigatorRole as N, type UserConfig as O, type ActivityRecord as P, type CourseRegistration as Q, type RegulatorReading as R, type StudySessionDoc as S, type UserOutcomeRecord as T, type UserDBInterface as U, makeStudySessionId as V, type WeightedCard as W, newSessionId as X, type UserHydrationState as Y, type UserHydrationStatus as Z, HYDRATION_MARKER_ID as _, type CoursesDBInterface as a, type NavigatorConstructor as a0, registerNavigator as a1, getRegisteredNavigator as a2, hasRegisteredNavigator as a3, getRegisteredNavigatorRole as a4, getRegisteredFilterKind as a5, getRegisteredNavigatorNames as a6, initializeNavigatorRegistry as a7, type StrategyContribution as a8, getCardOrigin as a9, createOrchestrationContext as aA, DEFAULT_REGULATOR_CONFIG as aB, reviewWeight as aC, reviewMassReading as aD, type IntakeClockState as aE, INTAKE_CLOCK_KEY as aF, resetIntakeClock as aG, frozenMsAt as aH, intakeHours as aI, stepIntakeClock as aJ, intakeReading as aK, applyReading as aL, type DocumentUpdater as aM, newInterval as aN, getStreak as aO, getLapses as aP, Navigators as aa, NavigatorRoles as ab, isGenerator as ac, isFilter as ad, type CardFilter as ae, type FilterContext as af, type CardFilterFactory as ag, type CardGenerator as ah, type GeneratorContext as ai, type CardGeneratorFactory as aj, pipelineDebugAPI as ak, mountPipelineDebugger as al, getActivePipeline as am, setDebugSessionId as an, getRunsForSession as ao, drainCapturedRuns as ap, type PipelineRunReport as aq, type RunReportCard as ar, type GeneratorSummary as as, type FilterImpact as at, type PipelineForecaster as au, type LearnableWeight as av, type OrchestrationContext as aw, computeDeviation as ax, computeSpread as ay, computeEffectiveWeight as az, type ContentNavigationStrategyData as b, type ScheduledCard as c, type CourseRegistrationDoc as d, type SessionStateSnapshot as e, type StudySessionRunSummary as f, type RegulatorName as g, type SessionEloEvent as h, type StudySessionRunCard as i, type StudySessionRunCardTrail as j, type CourseInfo as k, type StudySessionItem as l, ContentNavigator as m, type ReplanHints as n, type StudyContentSource as o, type StudySessionFailedItem as p, type StudySessionFailedNewItem as q, type StudySessionFailedReviewItem as r, type StudySessionNewItem as s, type StudySessionReviewItem as t, isReview as u, type ContentSourceID as v, getStudySource as w, type SessionStateSnapshotProvider as x, type RegulatorConfig as y, type UserDBReader as z };