@vue-skuilder/db 0.2.16 → 0.2.18

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.16",
+  "version": "0.2.18",
   "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.18",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -57,10 +57,11 @@
   },
   "devDependencies": {
     "@types/uuid": "^10.0.0",
+    "pouchdb-adapter-memory": "^9.0.0",
     "tsup": "^8.0.2",
     "typescript": "~5.9.3",
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.16"
+  "stableVersion": "0.2.18"
 }

package/src/core/index.ts

@@ -5,6 +5,7 @@ export * from './types/types-legacy';
 export * from './types/user';
 export * from './types/strategyState';
 export * from './types/userOutcome';
+export * from './types/hydration';
 export * from '../util/Loggable';
 export * from './util';
 export * from './navigators';

package/src/core/interfaces/userDB.ts

@@ -9,6 +9,7 @@ import { Moment } from 'moment';
 import { CardHistory, CardRecord, QualifiedCardID } from '../types/types-legacy';
 import { UserOutcomeRecord } from '../types/userOutcome';
 import { UserConfig } from '../types/user';
+import { UserHydrationStatus } from '../types/hydration';
 import { DocumentUpdater } from '@db/study';
 
 /**
@@ -19,6 +20,16 @@ export interface UserDBReader {
   getUsername(): string;
   isLoggedIn(): boolean;
 
+  /**
+   * How far this device's local mirror of the user's data can be trusted.
+   *
+   * Reads answer from the local mirror, so on a device that has never synced
+   * this account "document not found" does not mean "no such data". Anything
+   * that would otherwise interpret an empty read as a new user should check
+   * for `failed` first. See {@link UserHydrationStatus}.
+   */
+  hydrationStatus(): UserHydrationStatus;
+
   /**
    * Get user configuration
    */

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/core/types/hydration.ts

@@ -0,0 +1,78 @@
+/**
+ * User database hydration.
+ *
+ * A logged-in user's data lives in a remote CouchDB `userdb-<hex>` and is
+ * mirrored into a browser-local PouchDB. On a device that has never synced
+ * that account, the local mirror starts EMPTY — and every local read
+ * (`getStrategyState`, `getConfig`, `getCourseRegistrationsDoc`, ...) answers
+ * "no such document", which is indistinguishable from "brand new user".
+ *
+ * Consumers acting on that answer render a new-user experience to an existing
+ * user, and — worse — compute writes from empty state that then lose to the
+ * real remote document at replication time. Hydration closes that window by
+ * pulling the account's documents down BEFORE the user object is handed out.
+ */
+
+/**
+ * Where a user's local database stands relative to its remote counterpart.
+ *
+ * Only `failed` is a blocking condition. `stale` explicitly is not: it means a
+ * full pull completed on this device previously, so local data is real and
+ * merely possibly-behind — live sync closes the gap in the background. That is
+ * the ordinary offline case and it must keep working.
+ */
+export type UserHydrationState =
+  /** Guest, or a data layer with no remote. There is nothing to hydrate from. */
+  | 'not-required'
+  /** Initial pull in flight. */
+  | 'hydrating'
+  /** Initial pull completed this session. Local is a faithful mirror. */
+  | 'hydrated'
+  /**
+   * A previous session completed a full pull on this device (recorded by the
+   * `_local/hydration` marker). Local data is real; live sync is catching up.
+   */
+  | 'stale'
+  /**
+   * No pull has ever completed on this device and one could not be completed
+   * now. Local reads CANNOT be trusted to mean "no data" — callers must not
+   * present a new-user experience or compute writes from what they read.
+   */
+  | 'failed';
+
+/**
+ * Hydration state plus observability detail.
+ *
+ * Shaped to mirror `CourseSyncStatus` in CourseSyncService, which solves the
+ * same problem for course databases.
+ */
+export interface UserHydrationStatus {
+  state: UserHydrationState;
+  /** Documents pulled by the initial replication (set when state is `hydrated`). */
+  docsWritten?: number;
+  /** Wall-clock duration of the initial pull attempt, successful or not. */
+  durationMs?: number;
+  /** Failure detail, set when state is `failed`. */
+  error?: string;
+}
+
+/**
+ * ID of the per-device marker recording that a full pull once completed.
+ *
+ * `_local/*` documents are deliberately excluded from replication by CouchDB
+ * and PouchDB alike, which is exactly the semantics wanted here: the marker
+ * describes THIS device's mirror, and must never travel to another one.
+ */
+export const HYDRATION_MARKER_ID = '_local/hydration';
+
+/**
+ * Payload of {@link HYDRATION_MARKER_ID}.
+ */
+export interface HydrationMarker {
+  _id: typeof HYDRATION_MARKER_ID;
+  _rev?: string;
+  /** Account the mirror was hydrated for — guards against a stale marker after an account switch. */
+  username: string;
+  /** ISO timestamp of the most recent successful full pull. */
+  hydratedAt: string;
+}