@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,4 +1,4 @@
1
- import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-BoFBwvYa.js';
1
+ import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-CqJmbOZN.js';
2
2
  import { C as ClassroomDBInterface, A as AdminDBInterface } from './classroomDB-DLTtLZct.js';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-DpQqTG3m.cjs';
1
+ import { U as UserDBInterface, C as CourseDBInterface, a as CoursesDBInterface } from './contentSource-B6FrSihy.cjs';
2
2
  import { C as ClassroomDBInterface, A as AdminDBInterface } from './classroomDB-DLTtLZct.cjs';
3
3
 
4
4
  /**
@@ -1,6 +1,6 @@
1
1
  import { C as CardData, a as DisplayableData, T as Tag, b as CardRecord, Q as QuestionRecord, c as CardHistory } from '../types-legacy-BkOYOR6U.cjs';
2
- import { S as StudySessionDoc, b as ScheduledCard, c as CourseRegistrationDoc, d as SessionStateSnapshot, e as StudySessionRunSummary } from '../contentSource-DpQqTG3m.cjs';
3
- export { f as SessionEloEvent, g as StudySessionRunCard, h as StudySessionRunCardTrail } from '../contentSource-DpQqTG3m.cjs';
2
+ import { b as ContentNavigationStrategyData, S as StudySessionDoc, c as ScheduledCard, d as CourseRegistrationDoc, e as SessionStateSnapshot, f as StudySessionRunSummary, R as RegulatorReading, F as FilterKind, g as RegulatorName } from '../contentSource-B6FrSihy.cjs';
3
+ export { h as SessionEloEvent, i as StudySessionRunCard, j as StudySessionRunCardTrail } from '../contentSource-B6FrSihy.cjs';
4
4
  import '@vue-skuilder/common';
5
5
  import 'moment';
6
6
 
@@ -15,7 +15,7 @@ type RawDoc = {
15
15
  *
16
16
  * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
17
17
  * `courseId`, `tombstones`, or `course`.
18
- * - v1: adds all four.
18
+ * - v1: adds all four. Later v1 dumps also carry `course.strategies` (optional).
19
19
  */
20
20
  interface LearnerDump {
21
21
  formatVersion?: 1;
@@ -60,6 +60,11 @@ interface CourseSlice {
60
60
  _id: string;
61
61
  taggedCount: number;
62
62
  }>;
63
+ /**
64
+ * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
65
+ * taken (current state, not as of any session). Absent in older dumps.
66
+ */
67
+ strategies?: ContentNavigationStrategyData[];
63
68
  }
64
69
  /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
65
70
  type DatasetRecord = Omit<CardRecord, 'timeStamp'> & Partial<Omit<QuestionRecord, keyof CardRecord>> & {
@@ -101,6 +106,8 @@ interface LearnerDataset {
101
106
  }>;
102
107
  /** Absent when the dump carried no course slice. */
103
108
  cards?: Map<string, CardSummary>;
109
+ /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
110
+ strategies?: ContentNavigationStrategyData[];
104
111
  }
105
112
  /**
106
113
  * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
@@ -145,8 +152,9 @@ declare function userDbName(username: string): string;
145
152
  /**
146
153
  * Read one learner's records for one course into a {@link LearnerDump}: the
147
154
  * whole user DB, its tombstones, and (by default) the course cards the user
148
- * has touched, with their displayable data and tags. Needs admin rights on
149
- * the couch, via basic auth or the browser's session cookie.
155
+ * has touched, with their displayable data and tags, plus the course's strategy
156
+ * docs. Needs admin rights on the couch, via basic auth or the browser's
157
+ * session cookie.
150
158
  */
151
159
  declare function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump>;
152
160
 
@@ -354,6 +362,8 @@ declare function fmtDelta(d: number | null): string;
354
362
  /** 45s, 3m20s, 1.5h. */
355
363
  declare function fmtDuration(seconds: number): string;
356
364
  declare function fmtAnswer(a: unknown, max?: number): string;
365
+ /** One regulator reading as a line: its urgency, inputs, and multiplier. */
366
+ declare function regulatorText(r: RegulatorReading): string;
357
367
  /** One run as a compact text block. */
358
368
  declare function runText(run: StudySessionRunSummary): string;
359
369
  /** Per-tag ELO deltas worth showing inline: scored, non-zero, at most four. */
@@ -367,4 +377,67 @@ declare function sessionText(username: string, detail: SessionDetail, extras?: {
367
377
  eloLedger?: EloLedger | null;
368
378
  }, interp?: DiagnosticsInterpreters): string;
369
379
 
370
- export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, type LearnerDataset, type LearnerDump, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunSummary, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fromDump, isSkillTag, parseLearnerDump, recordPerformance, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };
380
+ /** One generator across persisted runs. */
381
+ interface GeneratorRunStat {
382
+ /** The name runs report it under (its strategy doc's name). */
383
+ name: string;
384
+ /** Runs it emitted at least one candidate in. */
385
+ runs: number;
386
+ /** Mean candidates per run, over the runs it appeared in. */
387
+ meanCards: number;
388
+ meanNew: number;
389
+ meanReview: number;
390
+ topScoreMax: number;
391
+ /** Top score in the most recent run it appeared in. */
392
+ topScoreLast: number;
393
+ /** Selected cards it originated (first provenance entry), over runs that persist selection. */
394
+ selected: number;
395
+ /** First attempts at those cards in the same session. */
396
+ firstAttempts: number;
397
+ firstAttemptsCorrect: number;
398
+ }
399
+ /** One filter across persisted runs: candidate counts summed over runs. */
400
+ interface FilterRunStat {
401
+ name: string;
402
+ /** As recorded by the most recent run that recorded it (0.2.29+). */
403
+ kind?: FilterKind;
404
+ runs: number;
405
+ boosted: number;
406
+ penalized: number;
407
+ passed: number;
408
+ removed: number;
409
+ }
410
+ /** One regulator across persisted runs (0.2.29+). */
411
+ interface RegulatorRunStat {
412
+ name: RegulatorName;
413
+ class: RegulatorReading['class'];
414
+ runs: number;
415
+ meanMultiplier: number;
416
+ maxMultiplier: number;
417
+ /** Runs where the multiplier was above 1. */
418
+ runsActive: number;
419
+ /** The most recent reading. */
420
+ last: RegulatorReading;
421
+ }
422
+ interface PipelineRunStats {
423
+ sessions: number;
424
+ runs: number;
425
+ /** Runs that persist their selected cards. Selection and outcome counts cover only these. */
426
+ runsWithSelection: number;
427
+ firstRunAt?: string;
428
+ lastRunAt?: string;
429
+ /** Busiest first. */
430
+ generators: GeneratorRunStat[];
431
+ /** By name. */
432
+ filters: FilterRunStat[];
433
+ /** Empty before 0.2.29. */
434
+ regulators: RegulatorRunStat[];
435
+ /** Selected cards with no originating generator: cards forced in by `requireCards`. */
436
+ selectedUnattributed: number;
437
+ }
438
+ /** Aggregate a learner's persisted pipeline runs, optionally only sessions started at or after `since` (ISO). */
439
+ declare function pipelineRunStats(ds: LearnerDataset, opts?: {
440
+ since?: string;
441
+ }): PipelineRunStats;
442
+
443
+ export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, FilterKind, type FilterRunStat, type GeneratorRunStat, type LearnerDataset, type LearnerDump, type PipelineRunStats, RegulatorName, RegulatorReading, type RegulatorRunStat, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunSummary, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fromDump, isSkillTag, parseLearnerDump, pipelineRunStats, recordPerformance, regulatorText, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };
@@ -1,6 +1,6 @@
1
1
  import { C as CardData, a as DisplayableData, T as Tag, b as CardRecord, Q as QuestionRecord, c as CardHistory } from '../types-legacy-BkOYOR6U.js';
2
- import { S as StudySessionDoc, b as ScheduledCard, c as CourseRegistrationDoc, d as SessionStateSnapshot, e as StudySessionRunSummary } from '../contentSource-BoFBwvYa.js';
3
- export { f as SessionEloEvent, g as StudySessionRunCard, h as StudySessionRunCardTrail } from '../contentSource-BoFBwvYa.js';
2
+ import { b as ContentNavigationStrategyData, S as StudySessionDoc, c as ScheduledCard, d as CourseRegistrationDoc, e as SessionStateSnapshot, f as StudySessionRunSummary, R as RegulatorReading, F as FilterKind, g as RegulatorName } from '../contentSource-CqJmbOZN.js';
3
+ export { h as SessionEloEvent, i as StudySessionRunCard, j as StudySessionRunCardTrail } from '../contentSource-CqJmbOZN.js';
4
4
  import '@vue-skuilder/common';
5
5
  import 'moment';
6
6
 
@@ -15,7 +15,7 @@ type RawDoc = {
15
15
  *
16
16
  * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
17
17
  * `courseId`, `tombstones`, or `course`.
18
- * - v1: adds all four.
18
+ * - v1: adds all four. Later v1 dumps also carry `course.strategies` (optional).
19
19
  */
20
20
  interface LearnerDump {
21
21
  formatVersion?: 1;
@@ -60,6 +60,11 @@ interface CourseSlice {
60
60
  _id: string;
61
61
  taggedCount: number;
62
62
  }>;
63
+ /**
64
+ * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
65
+ * taken (current state, not as of any session). Absent in older dumps.
66
+ */
67
+ strategies?: ContentNavigationStrategyData[];
63
68
  }
64
69
  /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
65
70
  type DatasetRecord = Omit<CardRecord, 'timeStamp'> & Partial<Omit<QuestionRecord, keyof CardRecord>> & {
@@ -101,6 +106,8 @@ interface LearnerDataset {
101
106
  }>;
102
107
  /** Absent when the dump carried no course slice. */
103
108
  cards?: Map<string, CardSummary>;
109
+ /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
110
+ strategies?: ContentNavigationStrategyData[];
104
111
  }
105
112
  /**
106
113
  * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
@@ -145,8 +152,9 @@ declare function userDbName(username: string): string;
145
152
  /**
146
153
  * Read one learner's records for one course into a {@link LearnerDump}: the
147
154
  * whole user DB, its tombstones, and (by default) the course cards the user
148
- * has touched, with their displayable data and tags. Needs admin rights on
149
- * the couch, via basic auth or the browser's session cookie.
155
+ * has touched, with their displayable data and tags, plus the course's strategy
156
+ * docs. Needs admin rights on the couch, via basic auth or the browser's
157
+ * session cookie.
150
158
  */
151
159
  declare function fetchLearnerDump(opts: FetchLearnerDumpOptions): Promise<LearnerDump>;
152
160
 
@@ -354,6 +362,8 @@ declare function fmtDelta(d: number | null): string;
354
362
  /** 45s, 3m20s, 1.5h. */
355
363
  declare function fmtDuration(seconds: number): string;
356
364
  declare function fmtAnswer(a: unknown, max?: number): string;
365
+ /** One regulator reading as a line: its urgency, inputs, and multiplier. */
366
+ declare function regulatorText(r: RegulatorReading): string;
357
367
  /** One run as a compact text block. */
358
368
  declare function runText(run: StudySessionRunSummary): string;
359
369
  /** Per-tag ELO deltas worth showing inline: scored, non-zero, at most four. */
@@ -367,4 +377,67 @@ declare function sessionText(username: string, detail: SessionDetail, extras?: {
367
377
  eloLedger?: EloLedger | null;
368
378
  }, interp?: DiagnosticsInterpreters): string;
369
379
 
370
- export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, type LearnerDataset, type LearnerDump, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunSummary, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fromDump, isSkillTag, parseLearnerDump, recordPerformance, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };
380
+ /** One generator across persisted runs. */
381
+ interface GeneratorRunStat {
382
+ /** The name runs report it under (its strategy doc's name). */
383
+ name: string;
384
+ /** Runs it emitted at least one candidate in. */
385
+ runs: number;
386
+ /** Mean candidates per run, over the runs it appeared in. */
387
+ meanCards: number;
388
+ meanNew: number;
389
+ meanReview: number;
390
+ topScoreMax: number;
391
+ /** Top score in the most recent run it appeared in. */
392
+ topScoreLast: number;
393
+ /** Selected cards it originated (first provenance entry), over runs that persist selection. */
394
+ selected: number;
395
+ /** First attempts at those cards in the same session. */
396
+ firstAttempts: number;
397
+ firstAttemptsCorrect: number;
398
+ }
399
+ /** One filter across persisted runs: candidate counts summed over runs. */
400
+ interface FilterRunStat {
401
+ name: string;
402
+ /** As recorded by the most recent run that recorded it (0.2.29+). */
403
+ kind?: FilterKind;
404
+ runs: number;
405
+ boosted: number;
406
+ penalized: number;
407
+ passed: number;
408
+ removed: number;
409
+ }
410
+ /** One regulator across persisted runs (0.2.29+). */
411
+ interface RegulatorRunStat {
412
+ name: RegulatorName;
413
+ class: RegulatorReading['class'];
414
+ runs: number;
415
+ meanMultiplier: number;
416
+ maxMultiplier: number;
417
+ /** Runs where the multiplier was above 1. */
418
+ runsActive: number;
419
+ /** The most recent reading. */
420
+ last: RegulatorReading;
421
+ }
422
+ interface PipelineRunStats {
423
+ sessions: number;
424
+ runs: number;
425
+ /** Runs that persist their selected cards. Selection and outcome counts cover only these. */
426
+ runsWithSelection: number;
427
+ firstRunAt?: string;
428
+ lastRunAt?: string;
429
+ /** Busiest first. */
430
+ generators: GeneratorRunStat[];
431
+ /** By name. */
432
+ filters: FilterRunStat[];
433
+ /** Empty before 0.2.29. */
434
+ regulators: RegulatorRunStat[];
435
+ /** Selected cards with no originating generator: cards forced in by `requireCards`. */
436
+ selectedUnattributed: number;
437
+ }
438
+ /** Aggregate a learner's persisted pipeline runs, optionally only sessions started at or after `since` (ISO). */
439
+ declare function pipelineRunStats(ds: LearnerDataset, opts?: {
440
+ since?: string;
441
+ }): PipelineRunStats;
442
+
443
+ export { type CardDossier, type CardSummary, type CouchAuth, type CourseSlice, type DatasetCardHistory, type DatasetRecord, type DiagnosticsInterpreters, type EloLedger, type FetchLearnerDumpOptions, FilterKind, type FilterRunStat, type GeneratorRunStat, type LearnerDataset, type LearnerDump, type PipelineRunStats, RegulatorName, RegulatorReading, type RegulatorRunStat, type ResponseEloDelta, SESSION_FLAGS, SESSION_FLAG_THRESHOLDS, type ServedTagStat, type SessionDetail, type SessionFlag, type SessionStateRow, SessionStateSnapshot, type SessionSummary, StudySessionDoc, StudySessionRunSummary, type TimelineEntry, type TimelineResponse, type TimelineRun, cardDossiers, dumpFileName, eloLedger, fetchLearnerDump, fmtAnswer, fmtDelta, fmtDuration, fromDump, isSkillTag, parseLearnerDump, pipelineRunStats, recordPerformance, regulatorText, runText, scoredTagDeltas, servedTags, sessionDetail, sessionText, shortTag, summarizeSession, summarizeSessions, toIsoTimestamp, userDbName };
@@ -32,7 +32,9 @@ __export(diagnostics_exports, {
32
32
  fromDump: () => fromDump,
33
33
  isSkillTag: () => isSkillTag,
34
34
  parseLearnerDump: () => parseLearnerDump,
35
+ pipelineRunStats: () => pipelineRunStats,
35
36
  recordPerformance: () => recordPerformance,
37
+ regulatorText: () => regulatorText,
36
38
  runText: () => runText,
37
39
  scoredTagDeltas: () => scoredTagDeltas,
38
40
  servedTags: () => servedTags,
@@ -147,7 +149,10 @@ function fromDump(dump, courseId) {
147
149
  registration,
148
150
  strategyState,
149
151
  tombstones: (dump.tombstones ?? []).map(({ id, seq }) => ({ id, seq })),
150
- ...dump.course && dump.course.courseId === course ? { cards: summarizeCards(dump.course) } : {}
152
+ ...dump.course && dump.course.courseId === course ? {
153
+ cards: summarizeCards(dump.course),
154
+ ...dump.course.strategies ? { strategies: dump.course.strategies } : {}
155
+ } : {}
151
156
  };
152
157
  }
153
158
 
@@ -261,13 +266,15 @@ async function fetchLearnerDump(opts) {
261
266
  taggedCards: scope === "all" ? tagged : tagged.filter((id) => cardIds.has(id))
262
267
  };
263
268
  }).filter((t) => scope === "all" || t.taggedCards.length > 0);
269
+ const strategies = await couch.byPrefix(courseDb, "NAVIGATION_STRATEGY");
264
270
  course = {
265
271
  courseId: opts.courseId,
266
272
  source: `${couch.base}/${courseDb}`,
267
273
  scope,
268
274
  cards,
269
275
  displayableData,
270
- tags
276
+ tags,
277
+ strategies
271
278
  };
272
279
  }
273
280
  return {
@@ -605,6 +612,14 @@ function trailText(label, t) {
605
612
  }
606
613
  return lines;
607
614
  }
615
+ function regulatorText(r) {
616
+ const i = r.inputs;
617
+ if (r.name === "review-mass") {
618
+ return `review mass ${r.urgency.toFixed(1)} over ${i.due ?? r.applied} due (healthy ${i.healthyMass}) \u2192 \xD7${r.multiplier.toFixed(2)}`;
619
+ }
620
+ const frozen = i.frozenHours ? `, ${i.frozenHours.toFixed(1)}h frozen` : "";
621
+ return `intake ${r.urgency.toFixed(1)}h since a new card${frozen}; ${i.eligibleNew ?? r.applied}/${i.newCandidates ?? "?"} new eligible \u2192 \xD7${r.multiplier.toFixed(2)}`;
622
+ }
608
623
  function runText(run) {
609
624
  const L = [];
610
625
  L.push(
@@ -623,10 +638,14 @@ function runText(run) {
623
638
  L.push(" filters:");
624
639
  for (const f of run.filters) {
625
640
  L.push(
626
- ` - ${f.name}: +${f.boosted} boosted, -${f.penalized} penalized, ${f.passed} passed, ${f.removed} removed`
641
+ ` - ${f.name}${f.kind ? ` (${f.kind})` : ""}: +${f.boosted} boosted, -${f.penalized} penalized, ${f.passed} passed, ${f.removed} removed`
627
642
  );
628
643
  }
629
644
  }
645
+ if (run.regulators?.length) {
646
+ L.push(" regulators:");
647
+ for (const r of run.regulators) L.push(` - ${regulatorText(r)}`);
648
+ }
630
649
  if (run.hints) L.push(` hints: ${JSON.stringify(run.hints)}`);
631
650
  if (run.cards?.length) {
632
651
  L.push(" selection (\u2713 selected, \xB7 runner-up):");
@@ -676,7 +695,9 @@ function sessionText(username, detail, extras = {}, interp) {
676
695
  L.push('- RUN "generated N \u2192 selected M (a new, b review)": the pipeline produced N');
677
696
  L.push(' candidates and chose M. "nothing survived" = generated > 0 but 0 selected.');
678
697
  L.push(" Bootstrap runs fire before card #1; replans are interleaved by time.");
679
- L.push("- generators: each source's contribution. filters: how each reshaped scores.");
698
+ L.push("- generators: each source's contribution. filters: how each reshaped scores");
699
+ L.push(" (gate: not ready yet; signal: preference). regulators: the pressure on each class,");
700
+ L.push(" review mass (due reviews by value) and intake (hours since a new card).");
680
701
  L.push(" hints: the ReplanHints the navigator was told (_label = replan reason).");
681
702
  L.push(' selection: the chosen cards and top runners-up. "next new in line" / "top-generated');
682
703
  L.push(' new (sunk)": the unselected new cards worth explaining, with each score change.');
@@ -749,6 +770,137 @@ function sessionText(username, detail, extras = {}, interp) {
749
770
  }
750
771
  return L.join("\n");
751
772
  }
773
+
774
+ // src/diagnostics/pipeline.ts
775
+ function pipelineRunStats(ds, opts = {}) {
776
+ const sessions = ds.sessions.filter((s) => !opts.since || s.startTime >= opts.since);
777
+ const recordsBySession = /* @__PURE__ */ new Map();
778
+ for (const h of ds.cardHistories) {
779
+ for (const record of h.records) {
780
+ if (!record.sessionId) continue;
781
+ const list = recordsBySession.get(record.sessionId) ?? [];
782
+ list.push({ cardId: h.cardID, record });
783
+ recordsBySession.set(record.sessionId, list);
784
+ }
785
+ }
786
+ const gens = /* @__PURE__ */ new Map();
787
+ const gen = (name) => {
788
+ let g = gens.get(name);
789
+ if (!g) {
790
+ g = {
791
+ name,
792
+ runs: 0,
793
+ cards: 0,
794
+ newCards: 0,
795
+ reviewCards: 0,
796
+ topScoreMax: 0,
797
+ topScoreLast: 0,
798
+ selected: 0,
799
+ firstAttempts: 0,
800
+ firstAttemptsCorrect: 0
801
+ };
802
+ gens.set(name, g);
803
+ }
804
+ return g;
805
+ };
806
+ const filters = /* @__PURE__ */ new Map();
807
+ const regulators = /* @__PURE__ */ new Map();
808
+ let runs = 0;
809
+ let runsWithSelection = 0;
810
+ let selectedUnattributed = 0;
811
+ let firstRunAt;
812
+ let lastRunAt;
813
+ for (const session of sessions) {
814
+ const originBySelectedCard = /* @__PURE__ */ new Map();
815
+ for (const run of session.runs ?? []) {
816
+ runs++;
817
+ if (!firstRunAt || run.at < firstRunAt) firstRunAt = run.at;
818
+ if (!lastRunAt || run.at > lastRunAt) lastRunAt = run.at;
819
+ for (const s of run.generators ?? []) {
820
+ const g = gen(s.name);
821
+ g.runs++;
822
+ g.cards += s.cardCount;
823
+ g.newCards += s.newCount;
824
+ g.reviewCards += s.reviewCount;
825
+ g.topScoreMax = Math.max(g.topScoreMax, s.topScore);
826
+ g.topScoreLast = s.topScore;
827
+ }
828
+ for (const f of run.filters ?? []) {
829
+ const acc = filters.get(f.name) ?? {
830
+ name: f.name,
831
+ runs: 0,
832
+ boosted: 0,
833
+ penalized: 0,
834
+ passed: 0,
835
+ removed: 0
836
+ };
837
+ acc.runs++;
838
+ if (f.kind) acc.kind = f.kind;
839
+ acc.boosted += f.boosted;
840
+ acc.penalized += f.penalized;
841
+ acc.passed += f.passed;
842
+ acc.removed += f.removed;
843
+ filters.set(f.name, acc);
844
+ }
845
+ for (const r of run.regulators ?? []) {
846
+ const acc = regulators.get(r.name) ?? {
847
+ name: r.name,
848
+ class: r.class,
849
+ runs: 0,
850
+ meanMultiplier: 0,
851
+ maxMultiplier: 0,
852
+ runsActive: 0,
853
+ last: r,
854
+ sumMultiplier: 0
855
+ };
856
+ acc.runs++;
857
+ acc.sumMultiplier += r.multiplier;
858
+ acc.maxMultiplier = Math.max(acc.maxMultiplier, r.multiplier);
859
+ if (r.multiplier > 1) acc.runsActive++;
860
+ acc.last = r;
861
+ regulators.set(r.name, acc);
862
+ }
863
+ if (run.cards) {
864
+ runsWithSelection++;
865
+ for (const c of run.cards) {
866
+ if (!c.selected) continue;
867
+ if (!c.generator) {
868
+ selectedUnattributed++;
869
+ continue;
870
+ }
871
+ gen(c.generator).selected++;
872
+ if (!originBySelectedCard.has(c.cardId)) originBySelectedCard.set(c.cardId, c.generator);
873
+ }
874
+ }
875
+ }
876
+ for (const { cardId, record } of recordsBySession.get(session.sessionId) ?? []) {
877
+ const origin = originBySelectedCard.get(cardId);
878
+ if (!origin || record.priorAttemps !== 0) continue;
879
+ const g = gen(origin);
880
+ g.firstAttempts++;
881
+ if (record.isCorrect === true) g.firstAttemptsCorrect++;
882
+ }
883
+ }
884
+ return {
885
+ sessions: sessions.length,
886
+ runs,
887
+ runsWithSelection,
888
+ firstRunAt,
889
+ lastRunAt,
890
+ generators: [...gens.values()].map(({ cards, newCards, reviewCards, ...g }) => ({
891
+ ...g,
892
+ meanCards: g.runs ? cards / g.runs : 0,
893
+ meanNew: g.runs ? newCards / g.runs : 0,
894
+ meanReview: g.runs ? reviewCards / g.runs : 0
895
+ })).sort((a, b) => b.runs - a.runs || a.name.localeCompare(b.name)),
896
+ filters: [...filters.values()].sort((a, b) => a.name.localeCompare(b.name)),
897
+ regulators: [...regulators.values()].map(({ sumMultiplier, ...r }) => ({
898
+ ...r,
899
+ meanMultiplier: r.runs ? sumMultiplier / r.runs : 0
900
+ })),
901
+ selectedUnattributed
902
+ };
903
+ }
752
904
  // Annotate the CommonJS export names for ESM import in node:
753
905
  0 && (module.exports = {
754
906
  SESSION_FLAGS,
@@ -763,7 +915,9 @@ function sessionText(username, detail, extras = {}, interp) {
763
915
  fromDump,
764
916
  isSkillTag,
765
917
  parseLearnerDump,
918
+ pipelineRunStats,
766
919
  recordPerformance,
920
+ regulatorText,
767
921
  runText,
768
922
  scoredTagDeltas,
769
923
  servedTags,