@vue-skuilder/db 0.2.16 → 0.2.17

package/dist/core/index.d.cts

@@ -37,6 +37,53 @@ declare function getSrsBacklogDebug(): SrsBacklogDebug[];
 /** Drop all captured snapshots (called on session start, alongside pipeline history). */
 declare function clearSrsBacklogDebug(): void;
 
+/**
+ * A single named pressure reading. The common shape across strategies: a
+ * multiplier that climbs under some accumulated condition (staleness, debt,
+ * blockage), optionally clamped at a cap.
+ */
+interface PressureGaugeDebug {
+    /** Stable identifier within the source (e.g. 'group:intro-core:target'). */
+    id: string;
+    /** Short display label (e.g. 'intro-core targets'). */
+    label: string;
+    /** Current pressure multiplier (×1.0 = no pressure). */
+    multiplier: number;
+    /** Clamp ceiling, if the multiplier is capped. Omit for unbounded. */
+    max?: number;
+    /** One-line context for the reading (counts, mode, staleness). */
+    detail?: string;
+    /** Expandable rows (blocked target ids, per-tag debt ages, ...). */
+    items?: Array<{
+        label: string;
+        value?: string;
+    }>;
+}
+/** One strategy's pressure snapshot for one course, captured once per run. */
+interface StrategyPressureDebug {
+    /** Producer identity — implementingClass name (e.g. 'prescribed'). */
+    source: string;
+    courseId: string;
+    gauges: PressureGaugeDebug[];
+    /**
+     * Highest score this strategy emitted into the candidate pool this run;
+     * null if it emitted nothing. Compare against the supplyQ head score to
+     * read how the pressure is competing for slots (same crossover read as the
+     * SRS panel's `top review`).
+     */
+    topScore?: number | null;
+    /** Label of any one-shot hints emitted alongside the cards this run. */
+    hintsLabel?: string;
+    /** Epoch ms of capture. */
+    timestamp: number;
+}
+/** Called by a strategy once per run. Latest snapshot per (source, course) wins. */
+declare function captureStrategyPressure(snapshot: StrategyPressureDebug): void;
+/** Current pressure snapshot for every source seen, newest-first. */
+declare function getStrategyPressureDebug(): StrategyPressureDebug[];
+/** Drop all captured snapshots (called on session start, alongside pipeline history). */
+declare function clearStrategyPressureDebug(): void;
+
 /**
  * Snapshot of the learning state for a strategy.
  *
@@ -805,4 +852,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, clearSrsBacklogDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, type PressureGaugeDebug, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, 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 };

package/dist/core/index.d.ts

@@ -37,6 +37,53 @@ declare function getSrsBacklogDebug(): SrsBacklogDebug[];
 /** Drop all captured snapshots (called on session start, alongside pipeline history). */
 declare function clearSrsBacklogDebug(): void;
 
+/**
+ * A single named pressure reading. The common shape across strategies: a
+ * multiplier that climbs under some accumulated condition (staleness, debt,
+ * blockage), optionally clamped at a cap.
+ */
+interface PressureGaugeDebug {
+    /** Stable identifier within the source (e.g. 'group:intro-core:target'). */
+    id: string;
+    /** Short display label (e.g. 'intro-core targets'). */
+    label: string;
+    /** Current pressure multiplier (×1.0 = no pressure). */
+    multiplier: number;
+    /** Clamp ceiling, if the multiplier is capped. Omit for unbounded. */
+    max?: number;
+    /** One-line context for the reading (counts, mode, staleness). */
+    detail?: string;
+    /** Expandable rows (blocked target ids, per-tag debt ages, ...). */
+    items?: Array<{
+        label: string;
+        value?: string;
+    }>;
+}
+/** One strategy's pressure snapshot for one course, captured once per run. */
+interface StrategyPressureDebug {
+    /** Producer identity — implementingClass name (e.g. 'prescribed'). */
+    source: string;
+    courseId: string;
+    gauges: PressureGaugeDebug[];
+    /**
+     * Highest score this strategy emitted into the candidate pool this run;
+     * null if it emitted nothing. Compare against the supplyQ head score to
+     * read how the pressure is competing for slots (same crossover read as the
+     * SRS panel's `top review`).
+     */
+    topScore?: number | null;
+    /** Label of any one-shot hints emitted alongside the cards this run. */
+    hintsLabel?: string;
+    /** Epoch ms of capture. */
+    timestamp: number;
+}
+/** Called by a strategy once per run. Latest snapshot per (source, course) wins. */
+declare function captureStrategyPressure(snapshot: StrategyPressureDebug): void;
+/** Current pressure snapshot for every source seen, newest-first. */
+declare function getStrategyPressureDebug(): StrategyPressureDebug[];
+/** Drop all captured snapshots (called on session start, alongside pipeline history). */
+declare function clearStrategyPressureDebug(): void;
+
 /**
  * Snapshot of the learning state for a strategy.
  *
@@ -805,4 +852,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, clearSrsBacklogDebug, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, getSrsBacklogDebug, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, type PressureGaugeDebug, QuestionRecord, ReplanHints, type SignalConfig, type SrsBacklogDebug, StrategyContribution, type StrategyLearningState, type StrategyPressureDebug, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, 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 };

package/dist/core/index.js

@@ -1667,6 +1667,30 @@ var init_SrsDebugger = __esm({
   }
 });
 
+// src/core/navigators/StrategyPressureDebugger.ts
+var StrategyPressureDebugger_exports = {};
+__export(StrategyPressureDebugger_exports, {
+  captureStrategyPressure: () => captureStrategyPressure,
+  clearStrategyPressureDebug: () => clearStrategyPressureDebug,
+  getStrategyPressureDebug: () => getStrategyPressureDebug
+});
+function captureStrategyPressure(snapshot) {
+  snapshots2.set(`${snapshot.source}:${snapshot.courseId}`, snapshot);
+}
+function getStrategyPressureDebug() {
+  return [...snapshots2.values()].sort((a, b) => b.timestamp - a.timestamp);
+}
+function clearStrategyPressureDebug() {
+  snapshots2.clear();
+}
+var snapshots2;
+var init_StrategyPressureDebugger = __esm({
+  "src/core/navigators/StrategyPressureDebugger.ts"() {
+    "use strict";
+    snapshots2 = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/core/navigators/generators/CompositeGenerator.ts
 var CompositeGenerator_exports = {};
 __export(CompositeGenerator_exports, {
@@ -2031,6 +2055,13 @@ function shuffleInPlace(arr) {
     [arr[i], arr[j]] = [arr[j], arr[i]];
   }
 }
+function formatAge(ms) {
+  const minutes = Math.max(0, Math.round(ms / 6e4));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.round(hours / 24)}d`;
+}
 function pickTopByScore(cards, limit) {
   return [...cards].sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId)).slice(0, limit);
 }
@@ -2039,6 +2070,7 @@ var init_prescribed = __esm({
   "src/core/navigators/generators/prescribed.ts"() {
     "use strict";
     init_navigators();
+    init_StrategyPressureDebugger();
     init_logger();
     DEFAULT_FRESHNESS_WINDOW = 3;
     DEFAULT_MAX_DIRECT_PER_RUN = 3;
@@ -2115,6 +2147,7 @@ var init_prescribed = __esm({
         const groupRuntimes = [];
         const priorPracticeDebt = progress.practiceDebt ?? {};
         const nextPracticeDebt = {};
+        const practiceDebtsByGroup = /* @__PURE__ */ new Map();
         for (const group of this.config.groups) {
           const runtime = this.buildGroupRuntimeState({
             group,
@@ -2163,7 +2196,7 @@ var init_prescribed = __esm({
             courseId,
             emittedIds
           );
-          const practiceCards = this.buildPracticeCards({
+          const practice = this.buildPracticeCards({
             group,
             courseId,
             emittedIds,
@@ -2176,7 +2209,8 @@ var init_prescribed = __esm({
             priorPracticeDebt,
             nextPracticeDebt
           });
-          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
+          practiceDebtsByGroup.set(group.id, practice.debts);
+          emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practice.cards);
         }
         nextState.practiceDebt = nextPracticeDebt;
         const hintSummary = this.buildSupportHintSummary(groupRuntimes);
@@ -2192,6 +2226,7 @@ var init_prescribed = __esm({
         } else {
           logger.info("[Prescribed] No hints to emit (no blocked targets or no support tags)");
         }
+        this.capturePressureSnapshot(courseId, groupRuntimes, practiceDebtsByGroup, emitted, hints);
         if (emitted.length === 0) {
           logger.info(
             "[Prescribed] 0 cards emitted (all targets blocked, authored/discovered support candidates exhausted)" + (hints ? " \u2014 boost hints emitted but may not survive filters" : "")
@@ -2253,6 +2288,60 @@ var init_prescribed = __esm({
           supportTags: [...supportTags].sort()
         };
       }
+      /**
+       * Translate this run's per-group runtimes and practice debts into gauges on
+       * the generic strategy-pressure debug channel (rendered by the live session
+       * overlay's "strategy backpressure" section).
+       */
+      capturePressureSnapshot(courseId, groupRuntimes, practiceDebtsByGroup, emitted, hints) {
+        const now = Date.now();
+        const gauges = [];
+        for (const runtime of groupRuntimes) {
+          const group = runtime.group;
+          const window2 = group.freshnessWindowSessions ?? DEFAULT_FRESHNESS_WINDOW;
+          gauges.push({
+            id: `group:${group.id}:target`,
+            label: `${group.id} targets`,
+            multiplier: runtime.pressureMultiplier,
+            max: MAX_TARGET_MULTIPLIER,
+            detail: `${runtime.pendingTargets.length} pending (${runtime.surfaceableTargets.length} surfaceable, ${runtime.blockedTargets.length} blocked) \xB7 sinceSurfaced ${runtime.sessionsSinceSurfaced}/${window2}`,
+            items: runtime.blockedTargets.map((cardId) => ({ label: cardId, value: "blocked" }))
+          });
+          if (runtime.blockedTargets.length > 0) {
+            const mode = runtime.supportCandidates.length > 0 ? "direct-support" : runtime.discoveredSupportCandidates.length > 0 ? "inserted-support" : "boost-only";
+            gauges.push({
+              id: `group:${group.id}:support`,
+              label: `${group.id} support`,
+              multiplier: runtime.supportMultiplier,
+              max: MAX_SUPPORT_MULTIPLIER,
+              detail: `mode=${mode} \xB7 ${runtime.supportTags.length} support tag(s)`,
+              items: runtime.supportTags.map((tag) => ({ label: tag }))
+            });
+          }
+          const debts = practiceDebtsByGroup.get(group.id) ?? [];
+          if (debts.length > 0) {
+            gauges.push({
+              id: `group:${group.id}:practice-debt`,
+              label: `${group.id} practice debt`,
+              multiplier: Math.max(...debts.map((d) => d.multiplier)),
+              max: MAX_PRACTICE_MULTIPLIER,
+              detail: `${debts.length} under-practiced skill(s)`,
+              items: debts.map((d) => ({
+                label: d.tag,
+                value: `\xD7${d.multiplier.toFixed(2)} \xB7 open ${formatAge(now - new Date(d.firstOwedAt).getTime())}`
+              }))
+            });
+          }
+        }
+        captureStrategyPressure({
+          source: "prescribed",
+          courseId,
+          gauges,
+          topScore: emitted.length > 0 ? Math.max(...emitted.map((c) => c.score)) : null,
+          hintsLabel: hints?._label,
+          timestamp: now
+        });
+      }
       parseConfig(serializedData) {
         try {
           const parsed = JSON.parse(serializedData);
@@ -2409,6 +2498,7 @@ var init_prescribed = __esm({
           supportTags: [...supportTags],
           pressureMultiplier,
           supportMultiplier,
+          sessionsSinceSurfaced,
           debugVersion: PRESCRIBED_DEBUG_VERSION
         };
       }
@@ -2541,13 +2631,13 @@ var init_prescribed = __esm({
           nextPracticeDebt
         } = args;
         const patterns = group.practiceTagPatterns ?? [];
-        if (patterns.length === 0) return [];
+        if (patterns.length === 0) return { cards: [], debts: [] };
         const practiceMinCount = group.practiceMinCount ?? DEFAULT_PRACTICE_MIN_COUNT;
         const maxPractice = group.maxPracticeCardsPerRun ?? DEFAULT_MAX_PRACTICE_PER_RUN;
         const practiceTags = [...cardsByTag.keys()].filter(
           (tag) => patterns.some((p) => matchesTagPattern(tag, p)) && this.isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) && (userTagElo[tag]?.count ?? 0) < practiceMinCount
         );
-        if (practiceTags.length === 0) return [];
+        if (practiceTags.length === 0) return { cards: [], debts: [] };
         const now = Date.now();
         const DAY_MS = 24 * 60 * 60 * 1e3;
         const tagMultiplier = /* @__PURE__ */ new Map();
@@ -2562,6 +2652,11 @@ var init_prescribed = __esm({
           );
           tagMultiplier.set(tag, mult);
         }
+        const debts = practiceTags.map((tag) => ({
+          tag,
+          multiplier: tagMultiplier.get(tag) ?? PRACTICE_BASE_MULT,
+          firstOwedAt: nextPracticeDebt[tag]
+        })).sort((a, b) => b.multiplier - a.multiplier || a.tag.localeCompare(b.tag));
         const practiceCardIds = this.findDiscoveredSupportCards({
           supportTags: practiceTags,
           cardsByTag,
@@ -2570,7 +2665,7 @@ var init_prescribed = __esm({
           excludedIds: emittedIds,
           limit: maxPractice
         });
-        if (practiceCardIds.length === 0) return [];
+        if (practiceCardIds.length === 0) return { cards: [], debts };
         logger.info(
           `[Prescribed] Group '${group.id}' practice: ${practiceTags.length} unlocked under-practiced skill(s), emitting ${practiceCardIds.length} drill card(s)`
         );
@@ -2600,7 +2695,7 @@ var init_prescribed = __esm({
             ]
           });
         }
-        return cards;
+        return { cards, debts };
       }
       /**
        * True for a skill that was *gated and is now reached*: it has at least one
@@ -5277,6 +5372,7 @@ var init_3 = __esm({
       "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
       "./PipelineDebugger.ts": () => Promise.resolve().then(() => (init_PipelineDebugger(), PipelineDebugger_exports)),
       "./SrsDebugger.ts": () => Promise.resolve().then(() => (init_SrsDebugger(), SrsDebugger_exports)),
+      "./StrategyPressureDebugger.ts": () => Promise.resolve().then(() => (init_StrategyPressureDebugger(), StrategyPressureDebugger_exports)),
       "./defaults.ts": () => Promise.resolve().then(() => (init_defaults(), defaults_exports)),
       "./diversityRerank.ts": () => Promise.resolve().then(() => (init_diversityRerank(), diversityRerank_exports)),
       "./filters/WeightedFilter.ts": () => Promise.resolve().then(() => (init_WeightedFilter(), WeightedFilter_exports)),
@@ -5309,7 +5405,9 @@ __export(navigators_exports, {
   NavigatorRole: () => NavigatorRole,
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
+  captureStrategyPressure: () => captureStrategyPressure,
   clearSrsBacklogDebug: () => clearSrsBacklogDebug,
+  clearStrategyPressureDebug: () => clearStrategyPressureDebug,
   diversityRerank: () => diversityRerank,
   getActivePipeline: () => getActivePipeline,
   getCardOrigin: () => getCardOrigin,
@@ -5317,6 +5415,7 @@ __export(navigators_exports, {
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
   getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
   getSrsBacklogDebug: () => getSrsBacklogDebug,
+  getStrategyPressureDebug: () => getStrategyPressureDebug,
   hasRegisteredNavigator: () => hasRegisteredNavigator,
   initializeNavigatorRegistry: () => initializeNavigatorRegistry,
   isFilter: () => isFilter,
@@ -5399,6 +5498,7 @@ var init_navigators = __esm({
     init_diversityRerank();
     init_PipelineDebugger();
     init_SrsDebugger();
+    init_StrategyPressureDebugger();
     init_logger();
     init_();
     init_2();
@@ -8423,7 +8523,9 @@ __export(core_exports, {
   aggregateOutcomesForGradient: () => aggregateOutcomesForGradient,
   areQuestionRecords: () => areQuestionRecords,
   buildStrategyStateId: () => buildStrategyStateId,
+  captureStrategyPressure: () => captureStrategyPressure,
   clearSrsBacklogDebug: () => clearSrsBacklogDebug,
+  clearStrategyPressureDebug: () => clearStrategyPressureDebug,
   computeDeviation: () => computeDeviation,
   computeEffectiveWeight: () => computeEffectiveWeight,
   computeOutcomeSignal: () => computeOutcomeSignal,
@@ -8440,6 +8542,7 @@ __export(core_exports, {
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
   getRegisteredNavigatorRole: () => getRegisteredNavigatorRole,
   getSrsBacklogDebug: () => getSrsBacklogDebug,
+  getStrategyPressureDebug: () => getStrategyPressureDebug,
   getStudySource: () => getStudySource,
   hasRegisteredNavigator: () => hasRegisteredNavigator,
   importParsedCards: () => importParsedCards,
@@ -8494,7 +8597,9 @@ init_core();
   aggregateOutcomesForGradient,
   areQuestionRecords,
   buildStrategyStateId,
+  captureStrategyPressure,
   clearSrsBacklogDebug,
+  clearStrategyPressureDebug,
   computeDeviation,
   computeEffectiveWeight,
   computeOutcomeSignal,
@@ -8511,6 +8616,7 @@ init_core();
   getRegisteredNavigatorNames,
   getRegisteredNavigatorRole,
   getSrsBacklogDebug,
+  getStrategyPressureDebug,
   getStudySource,
   hasRegisteredNavigator,
   importParsedCards,