@vue-skuilder/db 0.2.17 → 0.2.18

package/dist/{SyncStrategy-CyATpyLQ.d.cts → SyncStrategy-BJMZq3WO.d.cts}

@@ -36,6 +36,23 @@ interface SyncStrategy {
      * @returns PouchDB database instance for write operations
      */
     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/dist/{SyncStrategy-CyATpyLQ.d.ts → SyncStrategy-BJMZq3WO.d.ts}

@@ -36,6 +36,23 @@ interface SyncStrategy {
      * @returns PouchDB database instance for write operations
      */
     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/dist/{contentSource-Brz42x7n.d.cts → contentSource-CBqZCoGU.d.cts}

@@ -418,6 +418,81 @@ interface UserOutcomeRecord {
     };
 }
 
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+declare const HYDRATION_MARKER_ID = "_local/hydration";
+/**
+ * Payload of {@link HYDRATION_MARKER_ID}.
+ */
+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;
+}
+
 type Update<T> = Partial<T> | ((x: T) => T);
 
 interface DocumentUpdater {
@@ -438,6 +513,15 @@ interface UserDBReader {
     get<T>(id: string): Promise<T & PouchDB.Core.RevisionIdMeta>;
     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
      */
@@ -1248,4 +1332,4 @@ interface StudyContentSource {
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { Navigators as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type NavigatorConstructor as N, registerNavigator as O, getRegisteredNavigator as P, hasRegisteredNavigator as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, getRegisteredNavigatorRole as V, type WeightedCard as W, getRegisteredNavigatorNames as X, initializeNavigatorRegistry as Y, type StrategyContribution as Z, getCardOrigin as _, type UserDBReader as a, NavigatorRole as a0, NavigatorRoles as a1, isGenerator as a2, isFilter as a3, type CardGenerator as a4, type GeneratorContext as a5, type CardGeneratorFactory as a6, type LearnableWeight as a7, type OrchestrationContext as a8, computeDeviation as a9, computeSpread as aa, computeEffectiveWeight as ab, createOrchestrationContext as ac, type DocumentUpdater as ad, newInterval as ae, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { getRegisteredNavigatorNames as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type UserHydrationState as N, type UserHydrationStatus as O, HYDRATION_MARKER_ID as P, type HydrationMarker as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type NavigatorConstructor as V, type WeightedCard as W, registerNavigator as X, getRegisteredNavigator as Y, hasRegisteredNavigator as Z, getRegisteredNavigatorRole as _, type UserDBReader as a, initializeNavigatorRegistry as a0, type StrategyContribution as a1, getCardOrigin as a2, Navigators as a3, NavigatorRole as a4, NavigatorRoles as a5, isGenerator as a6, isFilter as a7, type CardGenerator as a8, type GeneratorContext as a9, type CardGeneratorFactory as aa, type LearnableWeight as ab, type OrchestrationContext as ac, computeDeviation as ad, computeSpread as ae, computeEffectiveWeight as af, createOrchestrationContext as ag, type DocumentUpdater as ah, newInterval as ai, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };

package/dist/{contentSource-B1p-vdz7.d.ts → contentSource-CudEz5Tm.d.ts}

@@ -418,6 +418,81 @@ interface UserOutcomeRecord {
     };
 }
 
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+declare const HYDRATION_MARKER_ID = "_local/hydration";
+/**
+ * Payload of {@link HYDRATION_MARKER_ID}.
+ */
+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;
+}
+
 type Update<T> = Partial<T> | ((x: T) => T);
 
 interface DocumentUpdater {
@@ -438,6 +513,15 @@ interface UserDBReader {
     get<T>(id: string): Promise<T & PouchDB.Core.RevisionIdMeta>;
     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
      */
@@ -1248,4 +1332,4 @@ interface StudyContentSource {
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { Navigators as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type NavigatorConstructor as N, registerNavigator as O, getRegisteredNavigator as P, hasRegisteredNavigator as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, getRegisteredNavigatorRole as V, type WeightedCard as W, getRegisteredNavigatorNames as X, initializeNavigatorRegistry as Y, type StrategyContribution as Z, getCardOrigin as _, type UserDBReader as a, NavigatorRole as a0, NavigatorRoles as a1, isGenerator as a2, isFilter as a3, type CardGenerator as a4, type GeneratorContext as a5, type CardGeneratorFactory as a6, type LearnableWeight as a7, type OrchestrationContext as a8, computeDeviation as a9, computeSpread as aa, computeEffectiveWeight as ab, createOrchestrationContext as ac, type DocumentUpdater as ad, newInterval as ae, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { getRegisteredNavigatorNames as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type UserHydrationState as N, type UserHydrationStatus as O, HYDRATION_MARKER_ID as P, type HydrationMarker as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, type NavigatorConstructor as V, type WeightedCard as W, registerNavigator as X, getRegisteredNavigator as Y, hasRegisteredNavigator as Z, getRegisteredNavigatorRole as _, type UserDBReader as a, initializeNavigatorRegistry as a0, type StrategyContribution as a1, getCardOrigin as a2, Navigators as a3, NavigatorRole as a4, NavigatorRoles as a5, isGenerator as a6, isFilter as a7, type CardGenerator as a8, type GeneratorContext as a9, type CardGeneratorFactory as aa, type LearnableWeight as ab, type OrchestrationContext as ac, computeDeviation as ad, computeSpread as ae, computeEffectiveWeight as af, createOrchestrationContext as ag, type DocumentUpdater as ah, newInterval as ai, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };

package/dist/core/index.d.cts

@@ -1,6 +1,6 @@
-import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } from '../contentSource-Brz42x7n.cjs';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, O as registerNavigator } from '../contentSource-Brz42x7n.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-CpwpT1rM.cjs';
+import { ab as LearnableWeight, M as UserOutcomeRecord, ac as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, a1 as StrategyContribution } from '../contentSource-CBqZCoGU.cjs';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a9 as GeneratorContext, G as GeneratorResult, P as HYDRATION_MARKER_ID, Q as HydrationMarker, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, X as registerNavigator } from '../contentSource-CBqZCoGU.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-BBA8tJNx.cjs';
 import { D as DocType, d as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-4tlwHnXo.cjs';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-4tlwHnXo.cjs';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, Z as StrategyContribution } from '../contentSource-B1p-vdz7.js';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, O as registerNavigator } from '../contentSource-B1p-vdz7.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-BWayUIoK.js';
+import { ab as LearnableWeight, M as UserOutcomeRecord, ac as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, R as ReplanHints, a1 as StrategyContribution } from '../contentSource-CudEz5Tm.js';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a9 as GeneratorContext, G as GeneratorResult, P as HYDRATION_MARKER_ID, Q as HydrationMarker, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, j as ScheduledCard, I as SessionTrackingData, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, X as registerNavigator } from '../contentSource-CudEz5Tm.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-C9WgkBzR.js';
 import { D as DocType, d as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-4tlwHnXo.js';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-4tlwHnXo.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';

package/dist/core/index.js

@@ -6767,6 +6767,19 @@ var init_couch = __esm({
 });
 
 // src/impl/common/BaseUserDB.ts
+function withTimeout(p, ms, label) {
+  let timer;
+  return Promise.race([
+    p,
+    new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    })
+  ]).finally(() => {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  });
+}
 async function getOrCreateClassroomRegistrationsDoc(user) {
   let ret;
   try {
@@ -6859,7 +6872,7 @@ async function dropUserFromClassroom(user, classID) {
 async function getUserClassrooms(user) {
   return getOrCreateClassroomRegistrationsDoc(user);
 }
-var import_common12, import_moment6, log3, BaseUser, userCoursesDoc, userClassroomsDoc;
+var import_common12, import_moment6, log3, HYDRATION_TIMEOUT_MS, BaseUser, userCoursesDoc, userClassroomsDoc;
 var init_BaseUserDB = __esm({
   "src/impl/common/BaseUserDB.ts"() {
     "use strict";
@@ -6876,6 +6889,7 @@ var init_BaseUserDB = __esm({
     log3 = (s) => {
       logger.info(s);
     };
+    HYDRATION_TIMEOUT_MS = 15e3;
     BaseUser = class _BaseUser {
       static _instance;
       static _initialized = false;
@@ -6904,6 +6918,29 @@ var init_BaseUserDB = __esm({
       writeDB;
       // Database to use for write operations (local-first approach)
       updateQueue;
+      _hydration = { 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.
+       */
+      hydrationStatus() {
+        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.
+       */
+      canMaterializeDefaults() {
+        return this._hydration.state !== "failed" && this._hydration.state !== "hydrating";
+      }
       async createAccount(username, password) {
         if (!this.syncStrategy.canCreateAccount()) {
           throw new Error("Account creation not supported by current sync strategy");
@@ -7021,6 +7058,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           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 \u2014 that would report an existing user as unregistered, and then lose to their real document once sync resumes.`
+              );
+            }
             await this.localDB.put({
               _id: _BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
               courses: [],
@@ -7263,6 +7305,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           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(defaultConfig);
             return this.getConfig();
           } else {
@@ -7336,7 +7383,9 @@ Currently logged-in as ${this._username}.`
           _BaseUser._initialized = true;
           return;
         }
+        this.syncStrategy.stopSync?.();
         this.setDBandQ();
+        await this.hydrateLocalMirror();
         this.syncStrategy.startSync(this.localDB, this.remoteDB);
         this.applyDesignDocs().catch((error) => {
           log3(`Error in applyDesignDocs background task: ${error}`);
@@ -7352,6 +7401,85 @@ 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.
+       */
+      async hydrateLocalMirror() {
+        if (this.localDB.name === this.remoteDB.name || !this.syncStrategy.hydrate) {
+          this._hydration = { state: "not-required" };
+          return;
+        }
+        if (await this.hasHydrationMarker()) {
+          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
+          };
+          log3(
+            `Hydrated local mirror for ${this._username}: ${docsWritten} docs in ${this._hydration.durationMs}ms`
+          );
+        } catch (e) {
+          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.
+       */
+      async hasHydrationMarker() {
+        try {
+          const marker = await this.localDB.get(HYDRATION_MARKER_ID);
+          return marker.username === this._username;
+        } catch {
+          return false;
+        }
+      }
+      async writeHydrationMarker() {
+        try {
+          let existingRev;
+          try {
+            existingRev = (await this.localDB.get(HYDRATION_MARKER_ID))._rev;
+          } catch {
+          }
+          await this.localDB.put({
+            _id: HYDRATION_MARKER_ID,
+            _rev: existingRev,
+            username: this._username,
+            hydratedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch (e) {
+          logger.warn(`Could not write hydration marker for ${this._username}: ${e}`);
+        }
+      }
       static designDocs = [
         {
           _id: "_design/reviewCards",
@@ -7688,6 +7816,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           if (err.status === 404) {
+            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;
@@ -8036,6 +8169,15 @@ var init_userOutcome = __esm({
   }
 });
 
+// src/core/types/hydration.ts
+var HYDRATION_MARKER_ID;
+var init_hydration = __esm({
+  "src/core/types/hydration.ts"() {
+    "use strict";
+    HYDRATION_MARKER_ID = "_local/hydration";
+  }
+});
+
 // src/core/bulkImport/cardProcessor.ts
 async function importParsedCards(parsedCards, courseDB, config) {
   const results = [];
@@ -8516,6 +8658,7 @@ __export(core_exports, {
   DocType: () => DocType,
   DocTypePrefixes: () => DocTypePrefixes,
   GuestUsername: () => GuestUsername,
+  HYDRATION_MARKER_ID: () => HYDRATION_MARKER_ID,
   Loggable: () => Loggable,
   NavigatorRole: () => NavigatorRole,
   NavigatorRoles: () => NavigatorRoles,
@@ -8573,6 +8716,7 @@ var init_core = __esm({
     init_user();
     init_strategyState();
     init_userOutcome();
+    init_hydration();
     init_Loggable();
     init_util();
     init_navigators();
@@ -8590,6 +8734,7 @@ init_core();
   DocType,
   DocTypePrefixes,
   GuestUsername,
+  HYDRATION_MARKER_ID,
   Loggable,
   NavigatorRole,
   NavigatorRoles,