@vue-skuilder/db 0.2.16 → 0.2.18

package/src/impl/common/BaseUserDB.ts

@@ -1,4 +1,12 @@
-import { DocType, DocTypePrefixes, StrategyStateDoc, buildStrategyStateId } from '@db/core';
+import {
+  DocType,
+  DocTypePrefixes,
+  StrategyStateDoc,
+  buildStrategyStateId,
+  HYDRATION_MARKER_ID,
+  type HydrationMarker,
+  type UserHydrationStatus,
+} from '@db/core';
 import { getCardHistoryID } from '@db/core/util';
 import { CourseElo, Status } from '@vue-skuilder/common';
 import moment, { Moment } from 'moment';
@@ -50,6 +58,35 @@ interface DesignDoc {
   };
 }
 
+/**
+ * Ceiling on the initial pull of a user's data before we give up and report
+ * `failed`. Generous relative to the expected payload (a user database is a
+ * config doc, registrations, strategy state, and per-card history), so hitting
+ * it indicates a genuinely unusable connection rather than a large account.
+ */
+const HYDRATION_TIMEOUT_MS = 15_000;
+
+/**
+ * Reject if `p` has not settled within `ms`.
+ *
+ * Note the underlying work is not cancelled by this — callers that need the
+ * operation stopped must do so themselves.
+ */
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  return Promise.race([
+    p,
+    new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    }),
+  ]).finally(() => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }) as Promise<T>;
+}
+
 /**
  * Base user database implementation that uses a pluggable sync strategy.
  * Handles local storage operations and delegates sync/remote operations to the strategy.
@@ -87,9 +124,34 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
   private localDB!: PouchDB.Database;
   private remoteDB!: PouchDB.Database;
   private writeDB!: PouchDB.Database; // Database to use for write operations (local-first approach)
-
   private updateQueue!: UpdateQueue;
 
+  private _hydration: UserHydrationStatus = { state: 'not-required' };
+
+  /**
+   * How far the local mirror can be trusted. See {@link UserHydrationStatus}.
+   *
+   * Consumers that would otherwise read a 404 as "new user" — onboarding
+   * gates, first-run experiences, progress dashboards — should check for
+   * `failed` and present a retry affordance rather than an empty state.
+   */
+  public hydrationStatus(): UserHydrationStatus {
+    return { ...this._hydration };
+  }
+
+  /**
+   * Whether a missing document may be treated as genuinely absent, allowing
+   * callers to create it with defaults.
+   *
+   * False only when hydration failed or is still running: a 404 then may just
+   * mean "not pulled down yet", and materializing a default would both lie to
+   * the user and, once live sync starts, push a rev-1 document that loses to
+   * the real one — silently discarding it.
+   */
+  private canMaterializeDefaults(): boolean {
+    return this._hydration.state !== 'failed' && this._hydration.state !== 'hydrating';
+  }
+
   public async createAccount(
     username: string,
     password: string
@@ -257,6 +319,14 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       if (err.status === 404) {
+        if (!this.canMaterializeDefaults()) {
+          throw new Error(
+            `Cannot read course registrations for ${this._username}: the local mirror is ` +
+              `unavailable (hydration state '${this._hydration.state}'). Refusing to create an ` +
+              `empty registration doc — that would report an existing user as unregistered, and ` +
+              `then lose to their real document once sync resumes.`
+          );
+        }
         await this.localDB.put<CourseRegistrationDoc>({
           _id: BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
           courses: [],
@@ -556,6 +626,13 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       if (err.name && err.name === 'not_found') {
+        if (!this.canMaterializeDefaults()) {
+          throw new Error(
+            `Cannot read config for ${this._username}: the local mirror is unavailable ` +
+              `(hydration state '${this._hydration.state}'). Refusing to write a default config ` +
+              `over what may be an existing one.`
+          );
+        }
         await this.localDB.put<UserConfig>(defaultConfig);
         return this.getConfig();
       } else {
@@ -643,8 +720,24 @@ Currently logged-in as ${this._username}.`
       return;
     }
 
+    // Cancel replication left over from the previous identity BEFORE rebinding
+    // the DB handles below. init() runs on every identity change (login,
+    // logout, account creation, data reset), and each one points localDB /
+    // remoteDB somewhere new — so without this, the prior sync keeps running
+    // against handles nobody holds a reference to anymore.
+    //
+    // Logout is the case that bites: the guest branch of startSync() never
+    // replaces the handle (it only ever assigns when a sync is actually
+    // started), so the departing user's live sync survived indefinitely. Its
+    // session cookie is gone by then, leaving it to 401-and-retry forever.
+    this.syncStrategy.stopSync?.();
+
     this.setDBandQ();
 
+    // Populate the local mirror BEFORE anything can read it, and before live
+    // sync can push local state upward. See hydrateLocalMirror().
+    await this.hydrateLocalMirror();
+
     this.syncStrategy.startSync(this.localDB, this.remoteDB);
     this.applyDesignDocs().catch((error) => {
       log(`Error in applyDesignDocs background task: ${error}`);
@@ -661,6 +754,104 @@ Currently logged-in as ${this._username}.`
     BaseUser._initialized = true;
   }
 
+  /**
+   * Pull this account's documents into the local mirror, if that hasn't
+   * happened on this device before.
+   *
+   * Runs between setDBandQ() and startSync() — after the handles exist, before
+   * anything can observe an empty local DB or replicate one upward.
+   *
+   * Never throws: a failure is recorded as `failed` state and reported through
+   * hydrationStatus(), because throwing here would abort init() and leave
+   * BaseUser._initialized false forever (BaseUser.instance() polls it with no
+   * ceiling). Callers decide what a failure means for them.
+   */
+  private async hydrateLocalMirror(): Promise<void> {
+    // Guests and static-mode users have no remote — setupRemoteDB() hands back
+    // the local database itself, so there is nothing to pull from.
+    if (this.localDB.name === this.remoteDB.name || !this.syncStrategy.hydrate) {
+      this._hydration = { state: 'not-required' };
+      return;
+    }
+
+    if (await this.hasHydrationMarker()) {
+      // A full pull already completed on this device, so local reads return
+      // real data and live sync will close any gap. Blocking here would break
+      // offline startup to re-fetch what we already have.
+      this._hydration = { state: 'stale' };
+      return;
+    }
+
+    this._hydration = { state: 'hydrating' };
+    const start = Date.now();
+
+    try {
+      const { docsWritten } = await withTimeout(
+        this.syncStrategy.hydrate(this.localDB, this.remoteDB),
+        HYDRATION_TIMEOUT_MS,
+        `Hydration of local mirror for ${this._username}`
+      );
+      await this.writeHydrationMarker();
+      this._hydration = {
+        state: 'hydrated',
+        docsWritten,
+        durationMs: Date.now() - start,
+      };
+      log(
+        `Hydrated local mirror for ${this._username}: ` +
+          `${docsWritten} docs in ${this._hydration.durationMs}ms`
+      );
+    } catch (e) {
+      // Cancel the pull if it is merely slow rather than dead — otherwise it
+      // races the live sync we are about to start over the same documents.
+      this.syncStrategy.stopSync?.();
+      this._hydration = {
+        state: 'failed',
+        durationMs: Date.now() - start,
+        error: e instanceof Error ? e.message : String(e),
+      };
+      logger.error(`Failed to hydrate local mirror for ${this._username}:`, e);
+    }
+  }
+
+  /**
+   * Has a full pull completed on this device for the CURRENT account?
+   *
+   * The marker is a `_local/` document, which never replicates — so its
+   * presence describes this device's mirror and cannot arrive from elsewhere.
+   */
+  private async hasHydrationMarker(): Promise<boolean> {
+    try {
+      const marker = await this.localDB.get<HydrationMarker>(HYDRATION_MARKER_ID);
+      return marker.username === this._username;
+    } catch {
+      // Absent, or unreadable — either way, treat as never hydrated. The cost
+      // of a false negative is one redundant pull.
+      return false;
+    }
+  }
+
+  private async writeHydrationMarker(): Promise<void> {
+    try {
+      let existingRev: string | undefined;
+      try {
+        existingRev = (await this.localDB.get<HydrationMarker>(HYDRATION_MARKER_ID))._rev;
+      } catch {
+        // First hydration on this device.
+      }
+
+      await this.localDB.put<HydrationMarker>({
+        _id: HYDRATION_MARKER_ID,
+        _rev: existingRev,
+        username: this._username,
+        hydratedAt: new Date().toISOString(),
+      });
+    } catch (e) {
+      // Costs a redundant pull on next startup, not correctness.
+      logger.warn(`Could not write hydration marker for ${this._username}: ${e}`);
+    }
+  }
+
   private static designDocs: DesignDoc[] = [
     {
       _id: '_design/reviewCards',
@@ -1083,6 +1274,15 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       if (err.status === 404) {
+        // `null` here means "this user has no such state" — a first-run signal
+        // consumers act on. When the mirror is untrusted we cannot honestly say
+        // that, so fail instead of reporting an established user as new.
+        if (!this.canMaterializeDefaults()) {
+          throw new Error(
+            `Cannot read strategy state '${strategyKey}' for ${this._username}: the local mirror ` +
+              `is unavailable (hydration state '${this._hydration.state}').`
+          );
+        }
         return null;
       }
       throw e;

package/src/impl/common/SyncStrategy.ts

@@ -21,6 +21,25 @@ export interface SyncStrategy {
    */
   getWriteDB?(username: string): PouchDB.Database;
 
+  /**
+   * Pull the remote database into the local one and RESOLVE WHEN DONE.
+   *
+   * Distinct from startSync(): this is a one-shot, awaitable catch-up used to
+   * populate an empty local mirror before the user object is handed out. A
+   * strategy that omits it declares that it has no remote worth waiting for.
+   *
+   * Mechanism only — BaseUser owns the policy (whether to run it, timeout,
+   * marker bookkeeping, resulting hydration state).
+   *
+   * @param localDB The local PouchDB instance
+   * @param remoteDB The remote PouchDB instance
+   * @returns Count of documents written locally
+   */
+  hydrate?(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database
+  ): Promise<{ docsWritten: number }>;
+
   /**
    * Start synchronization between local and remote databases
    * @param localDB The local PouchDB instance

package/src/impl/couch/CouchDBSyncStrategy.ts

@@ -21,6 +21,8 @@ const log = (s: any) => {
  */
 export class CouchDBSyncStrategy implements SyncStrategy {
   private syncHandle?: any; // Handle to cancel sync if needed
+  /** In-flight one-shot hydration pull, so a timed-out pull can be abandoned. */
+  private hydrationHandle?: PouchDB.Replication.Replication<object>;
 
   setupRemoteDB(username: string): PouchDB.Database {
     if (username === GuestUsername || username.startsWith(GuestUsername)) {
@@ -42,20 +44,68 @@ export class CouchDBSyncStrategy implements SyncStrategy {
     }
   }
 
+  /**
+   * One-shot remote → local pull. Resolves once the local mirror is caught up.
+   *
+   * Pull only: pushing here would upload whatever the local DB happens to hold
+   * before we know what the remote already has, which is the conflict-leaf
+   * problem hydration exists to avoid. Local changes go up when startSync()
+   * takes over.
+   */
+  async hydrate(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database
+  ): Promise<{ docsWritten: number }> {
+    // A one-shot Replication is itself a promise of the completed result, so
+    // it can be awaited directly — the handle is retained only so a pull that
+    // outlives its timeout can be cancelled.
+    const replication = pouch.replicate(remoteDB, localDB, {});
+    this.hydrationHandle = replication;
+
+    try {
+      const info = await replication;
+      return { docsWritten: info.docs_written };
+    } finally {
+      this.hydrationHandle = undefined;
+    }
+  }
+
   startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void {
-    // Only sync if local and remote are different instances
-    if (localDB !== remoteDB) {
+    // Compare by NAME, not object identity. In guest mode setupRemoteDB()
+    // returns getLocalUserDB(username) — the same database as localDB — but
+    // getLocalUserDB() constructs a fresh PouchDB handle on every call rather
+    // than caching, so `localDB !== remoteDB` was always true and guests ran a
+    // live sync of a database against itself. Names are unambiguous here:
+    // local DBs are named `userdb-<username>` (or a filesystem path in Node),
+    // remote ones are a full `protocol://host/userdb-<hex>` URL.
+    if (localDB.name !== remoteDB.name) {
       this.syncHandle = pouch.sync(localDB, remoteDB, {
         live: true,
         retry: true,
       });
     }
-    // If they're the same (guest mode), no sync needed
+    // If they're the same DB (guest mode), no sync needed
   }
 
   stopSync?(): void {
+    if (this.hydrationHandle) {
+      try {
+        this.hydrationHandle.cancel();
+      } catch (e) {
+        logger.warn(`Failed to cancel hydration pull (continuing anyway): ${e}`);
+      }
+      this.hydrationHandle = undefined;
+    }
+
     if (this.syncHandle) {
-      this.syncHandle.cancel();
+      // Called from BaseUser.init(), which is on the app boot path — a throw
+      // here would leave BaseUser._initialized false forever, and
+      // BaseUser.instance() polls that flag. Drop the handle regardless.
+      try {
+        this.syncHandle.cancel();
+      } catch (e) {
+        logger.warn(`Failed to cancel user sync (continuing anyway): ${e}`);
+      }
       this.syncHandle = undefined;
     }
   }

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})`);