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

package/dist/core/index.d.ts

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