@vue-skuilder/db 0.2.21 → 0.2.22

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 (48) hide show
  1. package/dist/{contentSource-BMxsujRu.d.cts → contentSource-B1pqryv6.d.ts} +82 -2
  2. package/dist/{contentSource-Bazgkf4C.d.ts → contentSource-CpTxVrFx.d.cts} +82 -2
  3. package/dist/core/index.d.cts +16 -6
  4. package/dist/core/index.d.ts +16 -6
  5. package/dist/core/index.js +79 -4
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +74 -4
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-Bt-D6xas.d.ts → dataLayerProvider-BZqH27f4.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-DifVCcIS.d.cts → dataLayerProvider-D4c7iUc_.d.cts} +1 -1
  11. package/dist/impl/couch/index.d.cts +3 -3
  12. package/dist/impl/couch/index.d.ts +3 -3
  13. package/dist/impl/couch/index.js +63 -4
  14. package/dist/impl/couch/index.js.map +1 -1
  15. package/dist/impl/couch/index.mjs +63 -4
  16. package/dist/impl/couch/index.mjs.map +1 -1
  17. package/dist/impl/static/index.d.cts +4 -4
  18. package/dist/impl/static/index.d.ts +4 -4
  19. package/dist/impl/static/index.js +63 -4
  20. package/dist/impl/static/index.js.map +1 -1
  21. package/dist/impl/static/index.mjs +63 -4
  22. package/dist/impl/static/index.mjs.map +1 -1
  23. package/dist/{index-k9NFHpS1.d.cts → index-DGApnUZ-.d.cts} +1 -1
  24. package/dist/{index-BLLT5BYE.d.ts → index-rmNIwnkV.d.ts} +1 -1
  25. package/dist/index.d.cts +51 -14
  26. package/dist/index.d.ts +51 -14
  27. package/dist/index.js +231 -12
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +226 -12
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/{types-CHgpWQAY.d.ts → types-B-Y3aoi5.d.ts} +1 -1
  32. package/dist/{types-legacy-4tlwHnXo.d.cts → types-legacy-BytY5eAR.d.cts} +9 -1
  33. package/dist/{types-legacy-4tlwHnXo.d.ts → types-legacy-BytY5eAR.d.ts} +9 -1
  34. package/dist/{types-BFUa1pa3.d.cts → types-r6fyuWP2.d.cts} +1 -1
  35. package/dist/util/packer/index.d.cts +3 -3
  36. package/dist/util/packer/index.d.ts +3 -3
  37. package/package.json +3 -3
  38. package/src/core/index.ts +1 -0
  39. package/src/core/interfaces/userDB.ts +7 -0
  40. package/src/core/navigators/PipelineDebugger.ts +41 -1
  41. package/src/core/navigators/index.ts +3 -0
  42. package/src/core/types/studySession.ts +100 -0
  43. package/src/core/types/types-legacy.ts +8 -0
  44. package/src/impl/common/BaseUserDB.ts +36 -0
  45. package/src/study/SessionController.ts +179 -2
  46. package/src/study/SessionDebugger.ts +4 -3
  47. package/src/study/SessionOverlay.ts +1 -0
  48. package/src/study/services/ResponseProcessor.ts +32 -4
@@ -1,4 +1,4 @@
1
- import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-BFUa1pa3.cjs';
1
+ import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-r6fyuWP2.cjs';
2
2
 
3
3
  /**
4
4
  * Abstraction for file system operations needed by the migrator.
@@ -1,4 +1,4 @@
1
- import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-CHgpWQAY.js';
1
+ import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-B-Y3aoi5.js';
2
2
 
3
3
  /**
4
4
  * Abstraction for file system operations needed by the migrator.
package/dist/index.d.cts CHANGED
@@ -1,15 +1,15 @@
1
- import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-BMxsujRu.cjs';
2
- export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ah as DocumentUpdater, a9 as GeneratorContext, P as HYDRATION_MARKER_ID, Q as HydrationMarker, ab as LearnableWeight, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, ac as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, a1 as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, M as UserOutcomeRecord, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, ai as newInterval, X as registerNavigator } from './contentSource-BMxsujRu.cjs';
3
- import { D as DataLayerProvider } from './dataLayerProvider-DifVCcIS.cjs';
4
- import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.cjs';
5
- export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.cjs';
1
+ import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, t as SessionStateSnapshotProvider, G as GeneratorResult, C as CourseDBInterface } from './contentSource-CpTxVrFx.cjs';
2
+ export { L as ActivityRecord, A as AdminDBInterface, w as AssignedCard, g as AssignedContent, v as AssignedCourse, u as AssignedTag, ae as CardGenerator, ag as CardGeneratorFactory, c as ClassroomDBInterface, H as ClassroomRegistration, F as ClassroomRegistrationDesignation, I as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, M as CourseRegistration, b as CoursesDBInterface, an as DocumentUpdater, af as GeneratorContext, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, ah as LearnableWeight, a0 as NavigatorConstructor, aa as NavigatorRole, ab as NavigatorRoles, a9 as Navigators, ai as OrchestrationContext, j as ScheduledCard, Q as SessionStateSnapshot, J as SessionTrackingData, a7 as StrategyContribution, i as StudentClassroomDBInterface, O as StudySessionDoc, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, P as StudySessionRunSummary, T as TeacherClassroomDBInterface, K as UserConfig, B as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, a as UserDBReader, x as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, N as UserOutcomeRecord, E as UsrCrsDataInterface, aj as computeDeviation, al as computeEffectiveWeight, ak as computeSpread, am as createOrchestrationContext, a8 as getCardOrigin, a2 as getRegisteredNavigator, a5 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, r as getStudySource, a3 as hasRegisteredNavigator, a6 as initializeNavigatorRegistry, ad as isFilter, ac as isGenerator, p as isReview, V as makeStudySessionId, ao as newInterval, X as newSessionId, a1 as registerNavigator } from './contentSource-CpTxVrFx.cjs';
3
+ import { D as DataLayerProvider } from './dataLayerProvider-D4c7iUc_.cjs';
4
+ import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-BytY5eAR.cjs';
5
+ export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-BytY5eAR.cjs';
6
6
  import { SrsBacklogDebug, StrategyPressureDebug, Loggable } from './core/index.cjs';
7
- export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineForecaster, PipelineRunReport, PressureGaugeDebug, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
7
+ export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineForecaster, PipelineRunReport, PressureGaugeDebug, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, drainCapturedRuns, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getRunsForSession, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, setDebugSessionId, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
8
8
  import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
9
- import { S as StaticCourseManifest } from './types-BFUa1pa3.cjs';
10
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-BFUa1pa3.cjs';
11
- import { F as FileSystemAdapter } from './index-k9NFHpS1.cjs';
12
- export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-k9NFHpS1.cjs';
9
+ import { S as StaticCourseManifest } from './types-r6fyuWP2.cjs';
10
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-r6fyuWP2.cjs';
11
+ import { F as FileSystemAdapter } from './index-DGApnUZ-.cjs';
12
+ export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-DGApnUZ-.cjs';
13
13
  import moment from 'moment';
14
14
 
15
15
  /**
@@ -348,6 +348,7 @@ interface SessionDrawnCardDebug {
348
348
  }
349
349
  /** Live snapshot of the controller, read fresh on each overlay tick. */
350
350
  interface SessionDebugSnapshot {
351
+ sessionId: string;
351
352
  secondsRemaining: number;
352
353
  hasCardGuarantee: boolean;
353
354
  minCardsGuarantee: number;
@@ -662,6 +663,24 @@ declare class SessionController<TView = unknown> extends Loggable {
662
663
  * `this`; constructed once so observers can rely on referential identity.
663
664
  */
664
665
  private _sessionControls;
666
+ /**
667
+ * Minted at construction so the bootstrap pipeline run in `prepareSession()`
668
+ * can carry it. Stamped onto every CardRecord and pipeline run this session.
669
+ */
670
+ readonly sessionId: string;
671
+ /** Host-supplied. Without it, no durable session doc is written. */
672
+ private _courseId?;
673
+ private _stateSnapshotProvider?;
674
+ private _sessionDoc;
675
+ /**
676
+ * Awaited by the close path — the open write is slow (time-boxed snapshot)
677
+ * and would otherwise land last, leaving a finished session marked `open`.
678
+ */
679
+ private _openDocPromise;
680
+ private _runLog;
681
+ private static readonly MAX_LOGGED_RUNS;
682
+ /** Guards `endSession()` against the several termination paths racing it. */
683
+ private _sessionClosed;
665
684
  private startTime;
666
685
  private endTime;
667
686
  private _secondsRemaining;
@@ -685,6 +704,9 @@ declare class SessionController<TView = unknown> extends Loggable {
685
704
  constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
686
705
  defaultBatchLimit?: number;
687
706
  outcomeObservers?: OutcomeObserver[];
707
+ /** Omit to run without durable session recording. */
708
+ courseId?: string;
709
+ stateSnapshotProvider?: SessionStateSnapshotProvider;
688
710
  });
689
711
  private tick;
690
712
  /**
@@ -696,6 +718,12 @@ declare class SessionController<TView = unknown> extends Loggable {
696
718
  */
697
719
  private estimateCleanupTime;
698
720
  prepareSession(): Promise<void>;
721
+ /** Label the runs the last plan produced. The pipeline can't know the why. */
722
+ private _recordRuns;
723
+ /** Time-boxed and isolated — a bad provider degrades the record, not the session. */
724
+ private _captureState;
725
+ /** Writing at open is what makes an unclosed session visible at all. */
726
+ private _openSessionDoc;
699
727
  /**
700
728
  * Request a mid-session replan. Re-runs the pipeline with current user state
701
729
  * and atomically replaces (or merges into) the supplyQ contents. Safe to call
@@ -959,6 +987,8 @@ declare class SessionController<TView = unknown> extends Loggable {
959
987
  */
960
988
  private _shouldInterleaveFailed;
961
989
  nextCard(action?: SessionAction): Promise<HydratedCard<TView> | null>;
990
+ /** Not awaited — the host renders the end screen off `nextCard()`'s null. */
991
+ private _terminate;
962
992
  /**
963
993
  * Public API for processing user responses to cards.
964
994
  * @param cardRecord User's response record
@@ -995,7 +1025,12 @@ declare class SessionController<TView = unknown> extends Loggable {
995
1025
  * This method aggregates all responses from the session and records a
996
1026
  * UserOutcomeRecord if evolutionary orchestration is enabled.
997
1027
  */
998
- endSession(): Promise<void>;
1028
+ /**
1029
+ * Idempotent. Called from every `nextCard()` path that returns null; hosts
1030
+ * should also call it with `'abandoned'` when tearing down mid-session.
1031
+ */
1032
+ endSession(reason?: 'closed' | 'abandoned'): Promise<void>;
1033
+ private _closeSessionDoc;
999
1034
  }
1000
1035
 
1001
1036
  /**
@@ -1205,9 +1240,11 @@ interface SessionRunReport {
1205
1240
  */
1206
1241
  declare function clearStaleSessionDebugState(): void;
1207
1242
  /**
1208
- * Start tracking a new session.
1243
+ * Start tracking a new session. The id is owned by `SessionController` — it is
1244
+ * minted at construction so pipeline runs from `prepareSession()` onward can
1245
+ * carry it.
1209
1246
  */
1210
- declare function startSessionTracking(supplyQLength: number, failedQLength: number): void;
1247
+ declare function startSessionTracking(sessionId: string, supplyQLength: number, failedQLength: number): void;
1211
1248
  /**
1212
1249
  * Record a card presentation.
1213
1250
  */
@@ -1523,4 +1560,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
1523
1560
  entitlements: UserEntitlements;
1524
1561
  }
1525
1562
 
1526
- export { type ActiveSessionHandle, type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, REVIEW_TIME_FORMAT, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionDebugSnapshot, type SessionDebugTarget, type SessionDrawnCardDebug, type SessionOutcome, type SessionQueueDebug, type SessionQueueItemDebug, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StrategyPressureDebug, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getActiveController, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, makeScheduledCardId, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerActiveController, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, toggleSessionOverlay, validateMigration, validateStaticCourse };
1563
+ export { type ActiveSessionHandle, type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, REVIEW_TIME_FORMAT, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionDebugSnapshot, type SessionDebugTarget, type SessionDrawnCardDebug, type SessionOutcome, type SessionQueueDebug, type SessionQueueItemDebug, type SessionRunReport, SessionStateSnapshotProvider, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StrategyPressureDebug, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getActiveController, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, makeScheduledCardId, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerActiveController, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, toggleSessionOverlay, validateMigration, validateStaticCourse };
package/dist/index.d.ts CHANGED
@@ -1,15 +1,15 @@
1
- import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-Bazgkf4C.js';
2
- export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ah as DocumentUpdater, a9 as GeneratorContext, P as HYDRATION_MARKER_ID, Q as HydrationMarker, ab as LearnableWeight, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, ac as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, a1 as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, M as UserOutcomeRecord, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, ai as newInterval, X as registerNavigator } from './contentSource-Bazgkf4C.js';
3
- import { D as DataLayerProvider } from './dataLayerProvider-Bt-D6xas.js';
4
- import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.js';
5
- export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.js';
1
+ import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, t as SessionStateSnapshotProvider, G as GeneratorResult, C as CourseDBInterface } from './contentSource-B1pqryv6.js';
2
+ export { L as ActivityRecord, A as AdminDBInterface, w as AssignedCard, g as AssignedContent, v as AssignedCourse, u as AssignedTag, ae as CardGenerator, ag as CardGeneratorFactory, c as ClassroomDBInterface, H as ClassroomRegistration, F as ClassroomRegistrationDesignation, I as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, M as CourseRegistration, b as CoursesDBInterface, an as DocumentUpdater, af as GeneratorContext, _ as HYDRATION_MARKER_ID, $ as HydrationMarker, ah as LearnableWeight, a0 as NavigatorConstructor, aa as NavigatorRole, ab as NavigatorRoles, a9 as Navigators, ai as OrchestrationContext, j as ScheduledCard, Q as SessionStateSnapshot, J as SessionTrackingData, a7 as StrategyContribution, i as StudentClassroomDBInterface, O as StudySessionDoc, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, P as StudySessionRunSummary, T as TeacherClassroomDBInterface, K as UserConfig, B as UserCourseSetting, z as UserCourseSettings, y as UserDBAuthenticator, a as UserDBReader, x as UserDBWriter, Y as UserHydrationState, Z as UserHydrationStatus, N as UserOutcomeRecord, E as UsrCrsDataInterface, aj as computeDeviation, al as computeEffectiveWeight, ak as computeSpread, am as createOrchestrationContext, a8 as getCardOrigin, a2 as getRegisteredNavigator, a5 as getRegisteredNavigatorNames, a4 as getRegisteredNavigatorRole, r as getStudySource, a3 as hasRegisteredNavigator, a6 as initializeNavigatorRegistry, ad as isFilter, ac as isGenerator, p as isReview, V as makeStudySessionId, ao as newInterval, X as newSessionId, a1 as registerNavigator } from './contentSource-B1pqryv6.js';
3
+ import { D as DataLayerProvider } from './dataLayerProvider-BZqH27f4.js';
4
+ import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-BytY5eAR.js';
5
+ export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-BytY5eAR.js';
6
6
  import { SrsBacklogDebug, StrategyPressureDebug, Loggable } from './core/index.js';
7
- export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineForecaster, PipelineRunReport, PressureGaugeDebug, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.js';
7
+ export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineForecaster, PipelineRunReport, PressureGaugeDebug, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, captureStrategyPressure, clearSrsBacklogDebug, clearStrategyPressureDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, drainCapturedRuns, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getRunsForSession, getSrsBacklogDebug, getStrategyPressureDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, setDebugSessionId, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.js';
8
8
  import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
9
- import { S as StaticCourseManifest } from './types-CHgpWQAY.js';
10
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CHgpWQAY.js';
11
- import { F as FileSystemAdapter } from './index-BLLT5BYE.js';
12
- export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-BLLT5BYE.js';
9
+ import { S as StaticCourseManifest } from './types-B-Y3aoi5.js';
10
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-B-Y3aoi5.js';
11
+ import { F as FileSystemAdapter } from './index-rmNIwnkV.js';
12
+ export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-rmNIwnkV.js';
13
13
  import moment from 'moment';
14
14
 
15
15
  /**
@@ -348,6 +348,7 @@ interface SessionDrawnCardDebug {
348
348
  }
349
349
  /** Live snapshot of the controller, read fresh on each overlay tick. */
350
350
  interface SessionDebugSnapshot {
351
+ sessionId: string;
351
352
  secondsRemaining: number;
352
353
  hasCardGuarantee: boolean;
353
354
  minCardsGuarantee: number;
@@ -662,6 +663,24 @@ declare class SessionController<TView = unknown> extends Loggable {
662
663
  * `this`; constructed once so observers can rely on referential identity.
663
664
  */
664
665
  private _sessionControls;
666
+ /**
667
+ * Minted at construction so the bootstrap pipeline run in `prepareSession()`
668
+ * can carry it. Stamped onto every CardRecord and pipeline run this session.
669
+ */
670
+ readonly sessionId: string;
671
+ /** Host-supplied. Without it, no durable session doc is written. */
672
+ private _courseId?;
673
+ private _stateSnapshotProvider?;
674
+ private _sessionDoc;
675
+ /**
676
+ * Awaited by the close path — the open write is slow (time-boxed snapshot)
677
+ * and would otherwise land last, leaving a finished session marked `open`.
678
+ */
679
+ private _openDocPromise;
680
+ private _runLog;
681
+ private static readonly MAX_LOGGED_RUNS;
682
+ /** Guards `endSession()` against the several termination paths racing it. */
683
+ private _sessionClosed;
665
684
  private startTime;
666
685
  private endTime;
667
686
  private _secondsRemaining;
@@ -685,6 +704,9 @@ declare class SessionController<TView = unknown> extends Loggable {
685
704
  constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
686
705
  defaultBatchLimit?: number;
687
706
  outcomeObservers?: OutcomeObserver[];
707
+ /** Omit to run without durable session recording. */
708
+ courseId?: string;
709
+ stateSnapshotProvider?: SessionStateSnapshotProvider;
688
710
  });
689
711
  private tick;
690
712
  /**
@@ -696,6 +718,12 @@ declare class SessionController<TView = unknown> extends Loggable {
696
718
  */
697
719
  private estimateCleanupTime;
698
720
  prepareSession(): Promise<void>;
721
+ /** Label the runs the last plan produced. The pipeline can't know the why. */
722
+ private _recordRuns;
723
+ /** Time-boxed and isolated — a bad provider degrades the record, not the session. */
724
+ private _captureState;
725
+ /** Writing at open is what makes an unclosed session visible at all. */
726
+ private _openSessionDoc;
699
727
  /**
700
728
  * Request a mid-session replan. Re-runs the pipeline with current user state
701
729
  * and atomically replaces (or merges into) the supplyQ contents. Safe to call
@@ -959,6 +987,8 @@ declare class SessionController<TView = unknown> extends Loggable {
959
987
  */
960
988
  private _shouldInterleaveFailed;
961
989
  nextCard(action?: SessionAction): Promise<HydratedCard<TView> | null>;
990
+ /** Not awaited — the host renders the end screen off `nextCard()`'s null. */
991
+ private _terminate;
962
992
  /**
963
993
  * Public API for processing user responses to cards.
964
994
  * @param cardRecord User's response record
@@ -995,7 +1025,12 @@ declare class SessionController<TView = unknown> extends Loggable {
995
1025
  * This method aggregates all responses from the session and records a
996
1026
  * UserOutcomeRecord if evolutionary orchestration is enabled.
997
1027
  */
998
- endSession(): Promise<void>;
1028
+ /**
1029
+ * Idempotent. Called from every `nextCard()` path that returns null; hosts
1030
+ * should also call it with `'abandoned'` when tearing down mid-session.
1031
+ */
1032
+ endSession(reason?: 'closed' | 'abandoned'): Promise<void>;
1033
+ private _closeSessionDoc;
999
1034
  }
1000
1035
 
1001
1036
  /**
@@ -1205,9 +1240,11 @@ interface SessionRunReport {
1205
1240
  */
1206
1241
  declare function clearStaleSessionDebugState(): void;
1207
1242
  /**
1208
- * Start tracking a new session.
1243
+ * Start tracking a new session. The id is owned by `SessionController` — it is
1244
+ * minted at construction so pipeline runs from `prepareSession()` onward can
1245
+ * carry it.
1209
1246
  */
1210
- declare function startSessionTracking(supplyQLength: number, failedQLength: number): void;
1247
+ declare function startSessionTracking(sessionId: string, supplyQLength: number, failedQLength: number): void;
1211
1248
  /**
1212
1249
  * Record a card presentation.
1213
1250
  */
@@ -1523,4 +1560,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
1523
1560
  entitlements: UserEntitlements;
1524
1561
  }
1525
1562
 
1526
- export { type ActiveSessionHandle, type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, REVIEW_TIME_FORMAT, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionDebugSnapshot, type SessionDebugTarget, type SessionDrawnCardDebug, type SessionOutcome, type SessionQueueDebug, type SessionQueueItemDebug, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StrategyPressureDebug, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getActiveController, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, makeScheduledCardId, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerActiveController, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, toggleSessionOverlay, validateMigration, validateStaticCourse };
1563
+ export { type ActiveSessionHandle, type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, GeneratorResult, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type OutcomeObserver, type ProcessedDataShape, type ProcessedQuestionData, QuestionRecord, type QueueSnapshot, QuotaRoundRobinMixer, REVIEW_TIME_FORMAT, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionDebugSnapshot, type SessionDebugTarget, type SessionDrawnCardDebug, type SessionOutcome, type SessionQueueDebug, type SessionQueueItemDebug, type SessionRunReport, SessionStateSnapshotProvider, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StrategyPressureDebug, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getActiveController, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, makeScheduledCardId, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerActiveController, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, toggleSessionOverlay, validateMigration, validateStaticCourse };