@vue-skuilder/db 0.2.16 → 0.2.17

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.2.16",
+    "@vue-skuilder/common": "0.2.17",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.16"
+  "stableVersion": "0.2.17"
 }

package/src/core/navigators/StrategyPressureDebugger.ts

@@ -0,0 +1,76 @@
+// ============================================================================
+// STRATEGY PRESSURE DEBUGGER
+// ============================================================================
+//
+// A generic, semi-structured capture channel for the backpressures that
+// navigation strategies exert on the pipeline — the general-purpose sibling
+// of SrsDebugger's bespoke review-backlog capture.
+//
+// Any strategy (built-in or consumer-registered via `registerNavigator`) may
+// push a snapshot of its current pressure state once per run. The live
+// session overlay renders every captured source in a "strategy backpressure"
+// section without knowing producer semantics: each snapshot is a list of
+// *gauges* — named multipliers, optionally capped, with human-readable detail
+// and expandable item lists (blocked targets, per-tag debt ages, ...).
+//
+// Mirrors SrsDebugger's lifecycle: latest snapshot per (source, course) wins;
+// the controller reads via getDebugSnapshot() with no DB load; cleared on
+// session start alongside the pipeline run history.
+//
+// ============================================================================
+
+/**
+ * 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.
+ */
+export 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. */
+export 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;
+}
+
+const snapshots = new Map<string, StrategyPressureDebug>();
+
+/** Called by a strategy once per run. Latest snapshot per (source, course) wins. */
+export function captureStrategyPressure(snapshot: StrategyPressureDebug): void {
+  snapshots.set(`${snapshot.source}:${snapshot.courseId}`, snapshot);
+}
+
+/** Current pressure snapshot for every source seen, newest-first. */
+export function getStrategyPressureDebug(): StrategyPressureDebug[] {
+  return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
+}
+
+/** Drop all captured snapshots (called on session start, alongside pipeline history). */
+export function clearStrategyPressureDebug(): void {
+  snapshots.clear();
+}

package/src/core/navigators/generators/prescribed.ts

@@ -4,6 +4,10 @@ import { ContentNavigator } from '../index';
 import type { WeightedCard } from '../index';
 import type { ContentNavigationStrategyData } from '../../types/contentNavigationStrategy';
 import type { CardGenerator, GeneratorContext, GeneratorResult, ReplanHints } from './types';
+import {
+  captureStrategyPressure,
+  type PressureGaugeDebug,
+} from '../StrategyPressureDebugger';
 import { logger } from '@db/util/logger';
 
 // ============================================================================
@@ -115,9 +119,19 @@ interface GroupRuntimeState {
   supportTags: string[];
   pressureMultiplier: number;
   supportMultiplier: number;
+  /** Carried-forward staleness count driving the pressure multipliers. */
+  sessionsSinceSurfaced: number;
   debugVersion: string;
 }
 
+/** One open practice debt, surfaced for the strategy-pressure debug channel. */
+interface PracticeDebtDebug {
+  tag: string;
+  multiplier: number;
+  /** ISO timestamp when the skill first appeared unlocked-but-under-practiced. */
+  firstOwedAt: string;
+}
+
 interface HintEmissionSummary {
   boostTags: Record<string, number>;
   blockedTargetIds: string[];
@@ -199,6 +213,15 @@ function shuffleInPlace<T>(arr: T[]): void {
   }
 }
 
+/** Compact age string for debt-open durations: 42m / 7h / 3d. */
+function formatAge(ms: number): string {
+  const minutes = Math.max(0, Math.round(ms / 60000));
+  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: WeightedCard[], limit: number): WeightedCard[] {
   return [...cards]
     .sort((a, b) => b.score - a.score || a.cardId.localeCompare(b.cardId))
@@ -293,6 +316,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     // under-practiced, dropped once it's discharged (see buildPracticeCards).
     const priorPracticeDebt = progress.practiceDebt ?? {};
     const nextPracticeDebt: Record<string, string> = {};
+    const practiceDebtsByGroup = new Map<string, PracticeDebtDebug[]>();
 
     for (const group of this.config.groups) {
       const runtime = this.buildGroupRuntimeState({
@@ -358,7 +382,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         courseId,
         emittedIds
       );
-      const practiceCards = this.buildPracticeCards({
+      const practice = this.buildPracticeCards({
         group,
         courseId,
         emittedIds,
@@ -371,8 +395,9 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         priorPracticeDebt,
         nextPracticeDebt,
       });
+      practiceDebtsByGroup.set(group.id, practice.debts);
 
-      emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
+      emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practice.cards);
     }
 
     // Persist the carried-forward practice debt (self-pruned: discharged skills
@@ -401,6 +426,11 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       logger.info('[Prescribed] No hints to emit (no blocked targets or no support tags)');
     }
 
+    // Push this run's pressure state to the live-overlay debug channel. Done
+    // before the empty-emission return — an all-blocked run is exactly the
+    // state the overlay most needs to show.
+    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)' +
@@ -481,6 +511,80 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     };
   }
 
+  /**
+   * 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).
+   */
+  private capturePressureSnapshot(
+    courseId: string,
+    groupRuntimes: GroupRuntimeState[],
+    practiceDebtsByGroup: Map<string, PracticeDebtDebug[]>,
+    emitted: WeightedCard[],
+    hints: ReplanHints | undefined
+  ): void {
+    const now = Date.now();
+    const gauges: PressureGaugeDebug[] = [];
+
+    for (const runtime of groupRuntimes) {
+      const group = runtime.group;
+      const window = 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) · ` +
+          `sinceSurfaced ${runtime.sessionsSinceSurfaced}/${window}`,
+        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} · ${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: `×${d.multiplier.toFixed(2)} · 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,
+    });
+  }
+
   private parseConfig(serializedData: string): PrescribedConfig {
     try {
       const parsed = JSON.parse(serializedData) as { groups?: unknown[] };
@@ -693,6 +797,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       supportTags: [...supportTags],
       pressureMultiplier,
       supportMultiplier,
+      sessionsSinceSurfaced,
       debugVersion: PRESCRIBED_DEBUG_VERSION,
     };
   }
@@ -875,7 +980,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     seenIds: Set<string>;
     priorPracticeDebt: Record<string, string>;
     nextPracticeDebt: Record<string, string>;
-  }): WeightedCard[] {
+  }): { cards: WeightedCard[]; debts: PracticeDebtDebug[] } {
     const {
       group,
       courseId,
@@ -891,7 +996,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     } = 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;
@@ -903,7 +1008,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         (userTagElo[tag]?.count ?? 0) < practiceMinCount
     );
 
-    if (practiceTags.length === 0) return [];
+    if (practiceTags.length === 0) return { cards: [], debts: [] };
 
     // Carry forward (or open) each under-practiced skill's debt age, and derive
     // its practice multiplier: base + staleness-since-first-owed, clamped. Done
@@ -924,6 +1029,16 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       tagMultiplier.set(tag, mult);
     }
 
+    // Debug view of every open debt (built before the emission early-return so
+    // the pressure channel sees debts even on runs that emit no drill cards).
+    const debts: PracticeDebtDebug[] = 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));
+
     // Reuse the diversity-aware tag→cards collector (stem-dedup + shuffle).
     const practiceCardIds = this.findDiscoveredSupportCards({
       supportTags: practiceTags,
@@ -934,7 +1049,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       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 ` +
@@ -974,7 +1089,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
       });
     }
 
-    return cards;
+    return { cards, debts };
   }
 
   /**

package/src/core/navigators/index.ts

@@ -33,6 +33,18 @@ export {
   type SrsBacklogDebug,
 } from './SrsDebugger';
 
+// Re-export the generic strategy-pressure debug channel. `captureStrategyPressure`
+// is part of the consumer surface: client-defined strategies (registered via
+// registerNavigator) push their backpressure state through it for the live
+// session overlay.
+export {
+  captureStrategyPressure,
+  getStrategyPressureDebug,
+  clearStrategyPressureDebug,
+  type StrategyPressureDebug,
+  type PressureGaugeDebug,
+} from './StrategyPressureDebugger';
+
 import { LearnableWeight } from '../types/contentNavigationStrategy';
 export type { ContentNavigationStrategyData, LearnableWeight } from '../types/contentNavigationStrategy';
 import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';

package/src/study/SessionController.ts

@@ -15,7 +15,12 @@ import {
 import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord, isQuestionRecord } from '@db/core';
 import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
-import { getCardOrigin, WeightedCard, getSrsBacklogDebug } from '@db/core/navigators';
+import {
+  getCardOrigin,
+  WeightedCard,
+  getSrsBacklogDebug,
+  getStrategyPressureDebug,
+} from '@db/core/navigators';
 import { ReplanHints } from '@db/core/navigators/generators/types';
 import { mergeHints } from '@db/core/navigators/Pipeline';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
@@ -763,6 +768,7 @@ export class SessionController<TView = unknown> extends Loggable {
       supplyQ: describe(this.supplyQ),
       failedQ: describe(this.failedQ),
       reviewBacklog: getSrsBacklogDebug(),
+      strategyPressure: getStrategyPressureDebug(),
       drawnCards,
     };
   }

package/src/study/SessionDebugger.ts

@@ -1,6 +1,7 @@
 import { logger } from '../util/logger';
 import { clearRunHistory as clearPipelineRunHistory } from '../core/navigators/PipelineDebugger';
 import { clearSrsBacklogDebug } from '../core/navigators/SrsDebugger';
+import { clearStrategyPressureDebug } from '../core/navigators/StrategyPressureDebugger';
 import { toggleSessionOverlay } from './SessionOverlay';
 
 // ============================================================================
@@ -82,6 +83,7 @@ const MAX_HISTORY = 5;
 export function clearStaleSessionDebugState(): void {
   clearPipelineRunHistory();
   clearSrsBacklogDebug();
+  clearStrategyPressureDebug();
 }
 
 /**

package/src/study/SessionOverlay.ts

@@ -1,6 +1,10 @@
 import { logger } from '../util/logger';
 import type { ReplanHints } from '@db/core/navigators/generators/types';
 import type { SrsBacklogDebug } from '@db/core/navigators/SrsDebugger';
+import type {
+  StrategyPressureDebug,
+  PressureGaugeDebug,
+} from '@db/core/navigators/StrategyPressureDebugger';
 
 // ============================================================================
 // SESSION OVERLAY
@@ -72,6 +76,8 @@ export interface SessionDebugSnapshot {
   failedQ: SessionQueueDebug;
   /** SRS backlog state per course (drives the "is review starvation permanent?" read). */
   reviewBacklog: SrsBacklogDebug[];
+  /** Per-strategy backpressure gauges (prescribed pressure, practice debt, ...). */
+  strategyPressure: StrategyPressureDebug[];
   /** Every card the learner has interacted with this session, draw order. */
   drawnCards: SessionDrawnCardDebug[];
 }
@@ -241,6 +247,7 @@ function render(): void {
     metaHtml(s) +
     hintsHtml(s.sessionHints) +
     backlogHtml(s.reviewBacklog) +
+    strategyPressureHtml(s.strategyPressure) +
     queueHtml('supplyQ', 'supplyQ', s.supplyQ) +
     queueHtml('failedQ', 'failedQ', s.failedQ) +
     drawnHtml('drawn', s.drawnCards);
@@ -416,6 +423,93 @@ function backlogHtml(backlog: SrsBacklogDebug[]): string {
   );
 }
 
+/**
+ * Colour for a pressure multiplier. Green at ×1.0 (no pressure); when the
+ * gauge is capped, amber → red by fraction of headroom used; when unbounded,
+ * fall back to the SRS panel's absolute threshold (×3 = hot).
+ */
+function pressureColor(multiplier: number, max?: number): string {
+  if (multiplier <= 1.001) return '#86efac';
+  if (max !== undefined && max > 1) {
+    return (multiplier - 1) / (max - 1) >= 0.75 ? '#fca5a5' : '#fcd34d';
+  }
+  return multiplier >= 3 ? '#fca5a5' : '#fcd34d';
+}
+
+/** data-q keys land in HTML attributes; strip anything outside a safe set. */
+function toggleKey(raw: string): string {
+  return raw.replace(/[^\w:.|-]/g, '_');
+}
+
+/**
+ * One gauge row: `label ×2.50/8 — detail`, with an item list underneath that
+ * mirrors the queues' collapse behaviour (INLINE_THRESHOLD shown, "+N more"
+ * expands).
+ */
+function gaugeHtml(sectionKey: string, g: PressureGaugeDebug): string {
+  const cap = g.max !== undefined ? `<span style="opacity:.5">/${g.max}</span>` : '';
+  const detail = g.detail ? ` <span style="opacity:.6">${esc(g.detail)}</span>` : '';
+  let html =
+    `<div style="margin-left:6px">${esc(g.label)} ` +
+    `<span style="color:${pressureColor(g.multiplier, g.max)}">×${g.multiplier.toFixed(2)}</span>` +
+    `${cap}${detail}`;
+
+  const items = g.items ?? [];
+  if (items.length > 0) {
+    const key = toggleKey(`sp|${sectionKey}|${g.id}`);
+    const isOpen = !!expanded[key];
+    const shown = isOpen ? items : items.slice(0, INLINE_THRESHOLD);
+    html +=
+      `<div style="margin-left:6px">` +
+      shown
+        .map(
+          (it) =>
+            `<div style="white-space:nowrap;opacity:.75">${esc(it.label)}` +
+            `${it.value ? ` <span style="opacity:.6">${esc(it.value)}</span>` : ''}</div>`
+        )
+        .join('');
+    if (items.length > INLINE_THRESHOLD) {
+      const footer = isOpen ? '▾ show less' : `… +${items.length - shown.length} more`;
+      html += `<div data-q="${key}" style="cursor:pointer;opacity:.6">${footer}</div>`;
+    }
+    html += `</div>`;
+  }
+
+  return html + `</div>`;
+}
+
+/**
+ * Strategy backpressure panel — the generic counterpart of the SRS panel
+ * above, fed by `captureStrategyPressure` pushes from navigation strategies
+ * (built-in prescribed, or consumer-registered). Per source: gauge rows with
+ * cap-aware colour, then a `top score` line that reads against the supplyQ
+ * head exactly like the SRS panel's `top review`.
+ */
+function strategyPressureHtml(list: StrategyPressureDebug[]): string {
+  if (!list.length) return '';
+  const sections = list
+    .map((s) => {
+      const sectionKey = `${s.source}:${s.courseId.slice(0, 8)}`;
+      const top = s.topScore !== null && s.topScore !== undefined ? s.topScore.toFixed(2) : '—';
+      const hints = s.hintsLabel
+        ? `<div style="margin-left:6px;opacity:.6">hints: ${esc(s.hintsLabel)}</div>`
+        : '';
+      return (
+        `<div style="margin-left:6px">` +
+        `<span style="opacity:.7">${esc(s.source)} · ${esc(s.courseId.slice(0, 8))}</span>` +
+        ` <span style="opacity:.6">top score ${top}</span>` +
+        s.gauges.map((g) => gaugeHtml(sectionKey, g)).join('') +
+        hints +
+        `</div>`
+      );
+    })
+    .join('');
+  return (
+    `<div style="margin-bottom:6px">` +
+    `<div style="color:#fdba74">strategy backpressure</div>${sections}</div>`
+  );
+}
+
 /** Format a rank score for display: finite → 2dp, `+INF` → REQ (required). */
 function fmtScore(score?: number): string {
   if (score === undefined) return '';
@@ -564,6 +658,25 @@ function snapshotToText(s: SessionDebugSnapshot | null): string {
     }
   }
 
+  if (s.strategyPressure.length) {
+    lines.push('');
+    lines.push('strategy backpressure:');
+    for (const sp of s.strategyPressure) {
+      const top = sp.topScore !== null && sp.topScore !== undefined ? sp.topScore.toFixed(2) : '—';
+      lines.push(`  ${sp.source} (${sp.courseId.slice(0, 8)}): top score ${top}`);
+      for (const g of sp.gauges) {
+        const cap = g.max !== undefined ? `/${g.max}` : '';
+        lines.push(
+          `    ${g.label} ×${g.multiplier.toFixed(2)}${cap}${g.detail ? ` — ${g.detail}` : ''}`
+        );
+        for (const it of g.items ?? []) {
+          lines.push(`      ${it.label}${it.value ? ` (${it.value})` : ''}`);
+        }
+      }
+      if (sp.hintsLabel) lines.push(`    hints: ${sp.hintsLabel}`);
+    }
+  }
+
   const queueText = (label: string, q: SessionQueueDebug) => {
     lines.push('');
     lines.push(`${label}: ${q.length} (drawn ${q.dequeueCount})`);