@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.
- package/dist/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
- package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
- package/dist/core/index.d.cts +13 -90
- package/dist/core/index.d.ts +13 -90
- package/dist/core/index.js +587 -179
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +586 -179
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
- package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
- package/dist/diagnostics/index.d.cts +79 -6
- package/dist/diagnostics/index.d.ts +79 -6
- package/dist/diagnostics/index.js +158 -4
- package/dist/diagnostics/index.js.map +1 -1
- package/dist/diagnostics/index.mjs +156 -4
- package/dist/diagnostics/index.mjs.map +1 -1
- package/dist/impl/couch/index.d.cts +11 -2
- package/dist/impl/couch/index.d.ts +11 -2
- package/dist/impl/couch/index.js +585 -179
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +585 -179
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +8 -2
- package/dist/impl/static/index.d.ts +8 -2
- package/dist/impl/static/index.js +582 -179
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +582 -179
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/index.d.cts +66 -5
- package/dist/index.d.ts +66 -5
- package/dist/index.js +635 -180
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +622 -180
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
- package/src/core/interfaces/contentSource.ts +7 -0
- package/src/core/navigators/Pipeline.ts +145 -13
- package/src/core/navigators/PipelineAssembler.ts +19 -40
- package/src/core/navigators/PipelineDebugger.ts +11 -2
- package/src/core/navigators/SrsDebugger.ts +37 -12
- package/src/core/navigators/defaults.ts +29 -5
- package/src/core/navigators/filters/WeightedFilter.ts +5 -1
- package/src/core/navigators/filters/eloDistance.ts +261 -76
- package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
- package/src/core/navigators/filters/index.ts +2 -2
- package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
- package/src/core/navigators/filters/relativePriority.ts +5 -1
- package/src/core/navigators/filters/types.ts +24 -1
- package/src/core/navigators/filters/userTagPreference.ts +5 -1
- package/src/core/navigators/generators/elo.ts +23 -53
- package/src/core/navigators/generators/srs.ts +27 -124
- package/src/core/navigators/index.ts +31 -5
- package/src/core/navigators/pipelinePlan.ts +245 -0
- package/src/core/navigators/regulators.ts +230 -0
- package/src/core/types/studySession.ts +3 -0
- package/src/diagnostics/dataset.ts +13 -2
- package/src/diagnostics/index.ts +3 -0
- package/src/diagnostics/loader.ts +5 -2
- package/src/diagnostics/pipeline.ts +236 -0
- package/src/diagnostics/text.ts +26 -3
- package/src/impl/couch/courseDB.ts +13 -0
- package/src/impl/static/courseDB.ts +9 -0
- package/src/index.ts +4 -0
- package/src/study/SessionController.ts +20 -0
- package/src/study/SessionOverlay.ts +7 -4
- package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
- 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 {
|
|
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 {
|
|
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 };
|