@vue-skuilder/db 0.2.11 → 0.2.12

package/dist/index.d.cts

@@ -1160,6 +1160,18 @@ interface SessionRunReport {
     presentations: CardPresentation[];
     queueSnapshots: QueueSnapshot[];
 }
+/**
+ * Release pipeline run-history / SRS backlog debug memory from the previous
+ * session before this session begins piling new runs on top of it. Must be
+ * called before the first pipeline run of the new session (including the
+ * bootstrap run in prepareSession) — clearing on session START rather than
+ * END keeps post-session inspection, the dominant debugging workflow, fully
+ * functional: a finished session's run history sits intact until the user
+ * actually begins another one. It's a separate call from startSessionTracking
+ * because that function can't run until supplyQ/failedQ are populated by the
+ * bootstrap pipeline run, which would otherwise be cleared out from under it.
+ */
+declare function clearStaleSessionDebugState(): void;
 /**
  * Start tracking a new session.
  */
@@ -1467,4 +1479,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { 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, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { 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, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };

package/dist/index.d.ts

@@ -1160,6 +1160,18 @@ interface SessionRunReport {
     presentations: CardPresentation[];
     queueSnapshots: QueueSnapshot[];
 }
+/**
+ * Release pipeline run-history / SRS backlog debug memory from the previous
+ * session before this session begins piling new runs on top of it. Must be
+ * called before the first pipeline run of the new session (including the
+ * bootstrap run in prepareSession) — clearing on session START rather than
+ * END keeps post-session inspection, the dominant debugging workflow, fully
+ * functional: a finished session's run history sits intact until the user
+ * actually begins another one. It's a separate call from startSessionTracking
+ * because that function can't run until supplyQ/failedQ are populated by the
+ * bootstrap pipeline run, which would otherwise be cleared out from under it.
+ */
+declare function clearStaleSessionDebugState(): void;
 /**
  * Start tracking a new session.
  */
@@ -1467,4 +1479,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { 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, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { 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, ReplanHints, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionControls, type SessionOutcome, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, SrsBacklogDebug, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, clearStaleSessionDebugState, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };

package/dist/index.js

@@ -2918,7 +2918,7 @@ var srs_exports = {};
 __export(srs_exports, {
   default: () => SRSNavigator
 });
-var import_moment3, DEFAULT_HEALTHY_BACKLOG, MAX_BACKLOG_MULTIPLIER, SRSNavigator;
+var import_moment3, DEFAULT_HEALTHY_BACKLOG, BACKLOG_GROWTH_RATE, SRSNavigator;
 var init_srs = __esm({
   "src/core/navigators/generators/srs.ts"() {
     "use strict";
@@ -2927,7 +2927,7 @@ var init_srs = __esm({
     init_SrsDebugger();
     init_logger();
     DEFAULT_HEALTHY_BACKLOG = 20;
-    MAX_BACKLOG_MULTIPLIER = 2;
+    BACKLOG_GROWTH_RATE = 2;
     SRSNavigator = class extends ContentNavigator {
       /** Human-readable name for CardGenerator interface */
       name;
@@ -3049,7 +3049,7 @@ var init_srs = __esm({
           dueNow: dueReviews.length,
           healthyBacklog: this.healthyBacklog,
           backlogMultiplier,
-          maxBacklogMultiplier: MAX_BACKLOG_MULTIPLIER,
+          backlogGrowthRate: BACKLOG_GROWTH_RATE,
           topReviewScore: sorted.length > 0 ? sorted[0].score : null,
           nextDueIn,
           timestamp: Date.now()
@@ -3059,25 +3059,30 @@ var init_srs = __esm({
       /**
        * Compute the multiplicative backlog pressure based on number of due reviews.
        *
-       * ×1.0 at or below the healthy threshold (no boost), increasing linearly above
-       * it and maxing out at MAX_BACKLOG_MULTIPLIER at 3× the healthy backlog.
+       * ×1.0 at or below the healthy threshold (no boost); above it, grows as
+       * BACKLOG_GROWTH_RATE raised to the excess expressed in multiples of the
+       * healthy threshold. Uncapped — self-regulating instead: reviews winning
+       * slots depletes dueCount, which drops the ratio and relaxes the multiplier
+       * next run.
        *
-       * Examples (with default healthyBacklog=20, MAX_BACKLOG_MULTIPLIER=2.0):
-       * - 10 due reviews → ×1.00 (healthy)
-       * - 20 due reviews → ×1.00 (at threshold)
-       * - 40 due reviews → ×1.50 (2x threshold)
-       * - 60 due reviews → ×2.00 (3x threshold, maxed)
+       * Examples (with default healthyBacklog=20, BACKLOG_GROWTH_RATE=1.5):
+       * - 10 due reviews → ×1.00  (healthy)
+       * - 20 due reviews → ×1.00  (at threshold, ratio 0)
+       * - 40 due reviews → ×1.50  (ratio 1, 2x threshold)
+       * - 60 due reviews → ×2.25  (ratio 2, 3x threshold — old hard cap was ×2.00 here)
+       * - 100 due reviews → ×5.06 (ratio 4, 5x threshold)
+       * - 160 due reviews → ×17.09 (ratio 7, 8x threshold)
        *
        * @param dueCount - Number of reviews currently due
-       * @returns Multiplier applied to review urgency (1.0 to MAX_BACKLOG_MULTIPLIER)
+       * @returns Multiplier applied to review urgency (>= 1.0, unbounded)
        */
       computeBacklogMultiplier(dueCount) {
         if (dueCount <= this.healthyBacklog) {
           return 1;
         }
         const excess = dueCount - this.healthyBacklog;
-        const multiplier = 1 + excess / this.healthyBacklog * ((MAX_BACKLOG_MULTIPLIER - 1) / 2);
-        return Math.min(MAX_BACKLOG_MULTIPLIER, multiplier);
+        const ratio = excess / this.healthyBacklog;
+        return Math.pow(BACKLOG_GROWTH_RATE, ratio);
       }
       /**
        * Compute urgency score for a review card.
@@ -3093,17 +3098,17 @@ var init_srs = __esm({
        *    - 180 days → ~0.30
        *
        * 3. Backlog pressure = global *multiplier* when review backlog exceeds the
-       *    healthy threshold (×1.0 healthy → up to MAX_BACKLOG_MULTIPLIER at 3×).
+       *    healthy threshold (×1.0 healthy → exponential growth, uncapped, above it).
        *
        * Combined: (base 0.5 + urgency factors * 0.45) × backlog multiplier.
        * Per-card range before pressure: ~0.57–0.95. NOT clamped to 1.0 — under a
        * heavy backlog reviews scale onto the open scale to compete with (and exceed)
-       * new cards; what keeps them from running away is the bounded multiplier, not
-       * a hard ceiling.
+       * new cards; there's no ceiling at all now, so a bad enough backlog always
+       * wins eventually — self-regulating because winning slots depletes dueCount.
        *
        * @param review - The scheduled card to score
        * @param now - Current time
-       * @param backlogMultiplier - Pre-computed backlog multiplier (1.0 to MAX_BACKLOG_MULTIPLIER)
+       * @param backlogMultiplier - Pre-computed backlog multiplier (>= 1.0, unbounded)
        */
       computeUrgencyScore(review, now, backlogMultiplier) {
         const scheduledAt = import_moment3.default.utc(review.scheduledAt);
@@ -10568,6 +10573,7 @@ __export(index_exports, {
   buildStrategyStateId: () => buildStrategyStateId,
   captureMixerRun: () => captureMixerRun,
   clearSrsBacklogDebug: () => clearSrsBacklogDebug,
+  clearStaleSessionDebugState: () => clearStaleSessionDebugState,
   computeDeviation: () => computeDeviation,
   computeEffectiveWeight: () => computeEffectiveWeight,
   computeOutcomeSignal: () => computeOutcomeSignal,
@@ -13737,12 +13743,12 @@ function hintsHtml(h) {
 function backlogHtml(backlog) {
   if (!backlog.length) return "";
   const rows = backlog.map((b) => {
-    const maxed = b.backlogMultiplier >= b.maxBacklogMultiplier - 1e-9;
-    const multColor = b.backlogMultiplier <= 1 ? "#86efac" : maxed ? "#fca5a5" : "#fcd34d";
-    const headroom = maxed ? "maxed \u2014 boosts decide order until they relax" : b.backlogMultiplier > 1 ? "climbing as backlog grows" : "healthy \u2014 no pressure";
+    const hot = b.backlogMultiplier >= 3;
+    const multColor = b.backlogMultiplier <= 1 ? "#86efac" : hot ? "#fca5a5" : "#fcd34d";
+    const headroom = b.backlogMultiplier > 1 ? `climbing (\xD7${b.backlogGrowthRate.toFixed(2)} per ${b.healthyBacklog}-review excess, unbounded)` : "healthy \u2014 no pressure";
     const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
     const next = b.nextDueIn ? ` <span style="opacity:.6">\xB7 next due ${esc(b.nextDueIn)}</span>` : "";
-    return `<div style="margin-left:6px"><span style="opacity:.7">${esc(b.courseId.slice(0, 8))}</span> due ${b.dueNow}/${b.scheduledTotal} <span style="opacity:.6">(healthy ${b.healthyBacklog})</span>${next}<div style="margin-left:6px">pressure <span style="color:${multColor}">\xD7${b.backlogMultiplier.toFixed(2)}/${b.maxBacklogMultiplier.toFixed(2)}</span> <span style="opacity:.6">${headroom} \xB7 top review ${top}</span></div></div>`;
+    return `<div style="margin-left:6px"><span style="opacity:.7">${esc(b.courseId.slice(0, 8))}</span> due ${b.dueNow}/${b.scheduledTotal} <span style="opacity:.6">(healthy ${b.healthyBacklog})</span>${next}<div style="margin-left:6px">pressure <span style="color:${multColor}">\xD7${b.backlogMultiplier.toFixed(2)}</span> <span style="opacity:.6">${headroom} \xB7 top review ${top}</span></div></div>`;
   }).join("");
   return `<div style="margin-bottom:6px"><div style="color:#93c5fd">review backpressure</div>${rows}</div>`;
 }
@@ -13838,12 +13844,11 @@ function snapshotToText(s) {
     lines.push("");
     lines.push("review backpressure:");
     for (const b of s.reviewBacklog) {
-      const maxed = b.backlogMultiplier >= b.maxBacklogMultiplier - 1e-9;
-      const headroom = maxed ? "maxed (boosts decide order)" : b.backlogMultiplier > 1 ? "climbing" : "healthy";
+      const headroom = b.backlogMultiplier > 1 ? "climbing" : "healthy";
       const top = b.topReviewScore !== null ? b.topReviewScore.toFixed(2) : "\u2014";
       const next = b.nextDueIn ? `, next due ${b.nextDueIn}` : "";
       lines.push(
-        `  ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} (healthy ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)}/${b.maxBacklogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
+        `  ${b.courseId.slice(0, 8)}: due ${b.dueNow}/${b.scheduledTotal} (healthy ${b.healthyBacklog})${next}; pressure \xD7${b.backlogMultiplier.toFixed(2)} ${headroom}; top review ${top}`
       );
     }
   }
@@ -13881,9 +13886,11 @@ function esc(value) {
 var activeSession = null;
 var sessionHistory = [];
 var MAX_HISTORY = 5;
-function startSessionTracking(supplyQLength, failedQLength) {
+function clearStaleSessionDebugState() {
   clearRunHistory();
   clearSrsBacklogDebug();
+}
+function startSessionTracking(supplyQLength, failedQLength) {
   const sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   activeSession = {
     sessionId,
@@ -14365,6 +14372,7 @@ var SessionController = class _SessionController extends Loggable {
         "[SessionController] All content sources must implement getWeightedCards()."
       );
     }
+    clearStaleSessionDebugState();
     const wellIndicated = await this.getWeightedContent();
     this._wellIndicatedRemaining = wellIndicated;
     if (wellIndicated >= 0 && wellIndicated < _SessionController.MIN_WELL_INDICATED) {
@@ -15269,6 +15277,7 @@ init_factory();
   buildStrategyStateId,
   captureMixerRun,
   clearSrsBacklogDebug,
+  clearStaleSessionDebugState,
   computeDeviation,
   computeEffectiveWeight,
   computeOutcomeSignal,