@vue-skuilder/db 0.1.18 → 0.1.20

package/dist/{classroomDB-BgfrVb8d.d.ts → classroomDB-CZdMBiTU.d.ts}

@@ -1,6 +1,6 @@
 import { CourseConfig, ClassroomConfig, CourseElo, Status, SkuilderCourseData as SkuilderCourseData$1, DataShape, TagFilter } from '@vue-skuilder/common';
 import { Moment } from 'moment';
-import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.js';
+import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-DDY4N-Uq.js';
 
 /**
  * Admin functionality
@@ -222,6 +222,18 @@ interface CourseDBInterface extends NavigationStrategyManager {
      * Get tags for a card
      */
     getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
+    /**
+     * Get tags for multiple cards in a single batch query.
+     * More efficient than calling getAppliedTags() for each card.
+     *
+     * This method reduces redundant database operations when multiple filters
+     * need tag data for the same cards. The Pipeline uses this to pre-hydrate
+     * tags on WeightedCard objects before filters run.
+     *
+     * @param cardIds - Array of card IDs to fetch tags for
+     * @returns Map from cardId to array of tag names
+     */
+    getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
     /**
      * Add a tag to a card
      */
@@ -323,6 +335,17 @@ interface UserDBReader {
      */
     getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
     getActivityRecords(): Promise<ActivityRecord[]>;
+    /**
+     * Get strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @returns The strategy's data payload, or null if no state exists
+     */
+    getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
     /**
      * Get user's classroom registrations
      */
@@ -387,6 +410,24 @@ interface UserDBWriter extends DocumentUpdater {
         status: Status;
         error?: string;
     }>;
+    /**
+     * Store strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @param data - The strategy's data payload to store
+     */
+    putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for a course.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     */
+    deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
 }
 /**
  * Authentication and account management operations
@@ -524,6 +565,11 @@ interface WeightedCard {
      * First entry is from the generator, subsequent entries from filters.
      */
     provenance: StrategyContribution[];
+    /**
+     * Pre-fetched tags. Populated by Pipeline before filters run.
+     * Filters should use this instead of querying getAppliedTags() individually.
+     */
+    tags?: string[];
 }
 /**
  * Extract card origin from provenance trail.
@@ -542,7 +588,8 @@ declare enum Navigators {
     HARDCODED = "hardcodedOrder",
     HIERARCHY = "hierarchyDefinition",
     INTERFERENCE = "interferenceMitigator",
-    RELATIVE_PRIORITY = "relativePriority"
+    RELATIVE_PRIORITY = "relativePriority",
+    USER_TAG_PREFERENCE = "userTagPreference"
 }
 /**
  * Role classification for navigation strategies.
@@ -598,6 +645,28 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
      */
     constructor(user?: UserDBInterface, course?: CourseDBInterface, strategyData?: ContentNavigationStrategyData);
+    /**
+     * Unique key identifying this strategy for state storage.
+     *
+     * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+     * Override in subclasses if multiple instances of the same strategy type
+     * need separate state storage.
+     */
+    protected get strategyKey(): string;
+    /**
+     * Get this strategy's persisted state for the current course.
+     *
+     * @returns The strategy's data payload, or null if no state exists
+     * @throws Error if user or course is not initialized
+     */
+    protected getStrategyState<T>(): Promise<T | null>;
+    /**
+     * Persist this strategy's state for the current course.
+     *
+     * @param data - The strategy's data payload to store
+     * @throws Error if user or course is not initialized
+     */
+    protected putStrategyState<T>(data: T): Promise<void>;
     /**
      * Factory method to create navigator instances dynamically.
      *

package/dist/{classroomDB-CTOenngH.d.cts → classroomDB-PxDZTky3.d.cts}

@@ -1,6 +1,6 @@
 import { CourseConfig, ClassroomConfig, CourseElo, Status, SkuilderCourseData as SkuilderCourseData$1, DataShape, TagFilter } from '@vue-skuilder/common';
 import { Moment } from 'moment';
-import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.cjs';
+import { S as SkuilderCourseData, b as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, C as CardHistory, c as CardRecord } from './types-legacy-DDY4N-Uq.cjs';
 
 /**
  * Admin functionality
@@ -222,6 +222,18 @@ interface CourseDBInterface extends NavigationStrategyManager {
      * Get tags for a card
      */
     getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
+    /**
+     * Get tags for multiple cards in a single batch query.
+     * More efficient than calling getAppliedTags() for each card.
+     *
+     * This method reduces redundant database operations when multiple filters
+     * need tag data for the same cards. The Pipeline uses this to pre-hydrate
+     * tags on WeightedCard objects before filters run.
+     *
+     * @param cardIds - Array of card IDs to fetch tags for
+     * @returns Map from cardId to array of tag names
+     */
+    getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
     /**
      * Add a tag to a card
      */
@@ -323,6 +335,17 @@ interface UserDBReader {
      */
     getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
     getActivityRecords(): Promise<ActivityRecord[]>;
+    /**
+     * Get strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @returns The strategy's data payload, or null if no state exists
+     */
+    getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
     /**
      * Get user's classroom registrations
      */
@@ -387,6 +410,24 @@ interface UserDBWriter extends DocumentUpdater {
         status: Status;
         error?: string;
     }>;
+    /**
+     * Store strategy-specific state for a course.
+     *
+     * Strategies use this to persist preferences, learned patterns, or temporal
+     * tracking data across sessions. Each strategy owns its own namespace.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     * @param data - The strategy's data payload to store
+     */
+    putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
+    /**
+     * Delete strategy-specific state for a course.
+     *
+     * @param courseId - The course this state applies to
+     * @param strategyKey - Unique key identifying the strategy (typically class name)
+     */
+    deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
 }
 /**
  * Authentication and account management operations
@@ -524,6 +565,11 @@ interface WeightedCard {
      * First entry is from the generator, subsequent entries from filters.
      */
     provenance: StrategyContribution[];
+    /**
+     * Pre-fetched tags. Populated by Pipeline before filters run.
+     * Filters should use this instead of querying getAppliedTags() individually.
+     */
+    tags?: string[];
 }
 /**
  * Extract card origin from provenance trail.
@@ -542,7 +588,8 @@ declare enum Navigators {
     HARDCODED = "hardcodedOrder",
     HIERARCHY = "hierarchyDefinition",
     INTERFERENCE = "interferenceMitigator",
-    RELATIVE_PRIORITY = "relativePriority"
+    RELATIVE_PRIORITY = "relativePriority",
+    USER_TAG_PREFERENCE = "userTagPreference"
 }
 /**
  * Role classification for navigation strategies.
@@ -598,6 +645,28 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
      */
     constructor(user?: UserDBInterface, course?: CourseDBInterface, strategyData?: ContentNavigationStrategyData);
+    /**
+     * Unique key identifying this strategy for state storage.
+     *
+     * Defaults to the constructor name (e.g., "UserTagPreferenceFilter").
+     * Override in subclasses if multiple instances of the same strategy type
+     * need separate state storage.
+     */
+    protected get strategyKey(): string;
+    /**
+     * Get this strategy's persisted state for the current course.
+     *
+     * @returns The strategy's data payload, or null if no state exists
+     * @throws Error if user or course is not initialized
+     */
+    protected getStrategyState<T>(): Promise<T | null>;
+    /**
+     * Persist this strategy's state for the current course.
+     *
+     * @param data - The strategy's data payload to store
+     * @throws Error if user or course is not initialized
+     */
+    protected putStrategyState<T>(data: T): Promise<void>;
     /**
      * Factory method to create navigator instances dynamically.
      *

package/dist/core/index.d.cts

@@ -1,8 +1,8 @@
-import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../classroomDB-CTOenngH.cjs';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../classroomDB-CTOenngH.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-D6PoCwS6.cjs';
-import { C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-6ettoclI.cjs';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-6ettoclI.cjs';
+import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../classroomDB-PxDZTky3.cjs';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../classroomDB-PxDZTky3.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-D0MoZMjH.cjs';
+import { b as DocTypePrefixes, D as DocType, C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-DDY4N-Uq.cjs';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-DDY4N-Uq.cjs';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
 
@@ -169,6 +169,80 @@ interface CardGenerator {
  */
 type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
 
+/**
+ * Template literal type for strategy state document IDs.
+ *
+ * Format: `STRATEGY_STATE-{courseId}-{strategyKey}`
+ */
+type StrategyStateId = `${(typeof DocTypePrefixes)[DocType.STRATEGY_STATE]}::${string}::${string}`;
+/**
+ * Document storing strategy-specific state in the user database.
+ *
+ * Each strategy can persist its own state (user preferences, learned patterns,
+ * temporal tracking, etc.) using this document type. The state is scoped to
+ * a (user, course, strategy) tuple.
+ *
+ * ## Use Cases
+ *
+ * 1. **Explicit user preferences**: User configures tag filters, difficulty
+ *    preferences, or learning goals. UI writes to strategy state.
+ *
+ * 2. **Learned/temporal state**: Strategy tracks patterns over time, e.g.,
+ *    "when did I last introduce confusable concepts together?"
+ *
+ * 3. **Adaptive personalization**: Strategy infers user preferences from
+ *    behavior and stores them for future sessions.
+ *
+ * ## Storage Location
+ *
+ * These documents live in the **user database**, not the course database.
+ * They sync with the user's data across devices.
+ *
+ * ## Document ID Format
+ *
+ * `STRATEGY_STATE::{courseId}::{strategyKey}`
+ *
+ * Example: `STRATEGY_STATE::piano-basics::UserTagPreferenceFilter`
+ *
+ * @template T - The shape of the strategy-specific data payload
+ */
+interface StrategyStateDoc<T = unknown> {
+    _id: StrategyStateId;
+    _rev?: string;
+    docType: DocType.STRATEGY_STATE;
+    /**
+     * The course this state applies to.
+     */
+    courseId: string;
+    /**
+     * Unique key identifying the strategy instance.
+     * Typically the strategy class name (e.g., "UserTagPreferenceFilter",
+     * "InterferenceMitigatorNavigator").
+     *
+     * If a course has multiple instances of the same strategy type with
+     * different configurations, use a more specific key.
+     */
+    strategyKey: string;
+    /**
+     * Strategy-specific data payload.
+     * Each strategy defines its own schema for this field.
+     */
+    data: T;
+    /**
+     * ISO timestamp of last update.
+     * Use `moment.utc(updatedAt)` to parse into a Moment object.
+     */
+    updatedAt: string;
+}
+/**
+ * Build the document ID for a strategy state document.
+ *
+ * @param courseId - The course ID
+ * @param strategyKey - The strategy key (typically class name)
+ * @returns The document ID in format `STRATEGY_STATE::{courseId}::{strategyKey}`
+ */
+declare function buildStrategyStateId(courseId: string, strategyKey: string): StrategyStateId;
+
 declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
 declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
 declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
@@ -227,4 +301,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, UserDBInterface, WeightedCard, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, type StrategyStateDoc, type StrategyStateId, UserDBInterface, WeightedCard, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
-import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../classroomDB-BgfrVb8d.js';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../classroomDB-BgfrVb8d.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-CZxC9GtB.js';
-import { C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-6ettoclI.js';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-6ettoclI.js';
+import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../classroomDB-CZdMBiTU.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../classroomDB-CZdMBiTU.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-D8o6ZnKW.js';
+import { b as DocTypePrefixes, D as DocType, C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-DDY4N-Uq.js';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-DDY4N-Uq.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
 
@@ -169,6 +169,80 @@ interface CardGenerator {
  */
 type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
 
+/**
+ * Template literal type for strategy state document IDs.
+ *
+ * Format: `STRATEGY_STATE-{courseId}-{strategyKey}`
+ */
+type StrategyStateId = `${(typeof DocTypePrefixes)[DocType.STRATEGY_STATE]}::${string}::${string}`;
+/**
+ * Document storing strategy-specific state in the user database.
+ *
+ * Each strategy can persist its own state (user preferences, learned patterns,
+ * temporal tracking, etc.) using this document type. The state is scoped to
+ * a (user, course, strategy) tuple.
+ *
+ * ## Use Cases
+ *
+ * 1. **Explicit user preferences**: User configures tag filters, difficulty
+ *    preferences, or learning goals. UI writes to strategy state.
+ *
+ * 2. **Learned/temporal state**: Strategy tracks patterns over time, e.g.,
+ *    "when did I last introduce confusable concepts together?"
+ *
+ * 3. **Adaptive personalization**: Strategy infers user preferences from
+ *    behavior and stores them for future sessions.
+ *
+ * ## Storage Location
+ *
+ * These documents live in the **user database**, not the course database.
+ * They sync with the user's data across devices.
+ *
+ * ## Document ID Format
+ *
+ * `STRATEGY_STATE::{courseId}::{strategyKey}`
+ *
+ * Example: `STRATEGY_STATE::piano-basics::UserTagPreferenceFilter`
+ *
+ * @template T - The shape of the strategy-specific data payload
+ */
+interface StrategyStateDoc<T = unknown> {
+    _id: StrategyStateId;
+    _rev?: string;
+    docType: DocType.STRATEGY_STATE;
+    /**
+     * The course this state applies to.
+     */
+    courseId: string;
+    /**
+     * Unique key identifying the strategy instance.
+     * Typically the strategy class name (e.g., "UserTagPreferenceFilter",
+     * "InterferenceMitigatorNavigator").
+     *
+     * If a course has multiple instances of the same strategy type with
+     * different configurations, use a more specific key.
+     */
+    strategyKey: string;
+    /**
+     * Strategy-specific data payload.
+     * Each strategy defines its own schema for this field.
+     */
+    data: T;
+    /**
+     * ISO timestamp of last update.
+     * Use `moment.utc(updatedAt)` to parse into a Moment object.
+     */
+    updatedAt: string;
+}
+/**
+ * Build the document ID for a strategy state document.
+ *
+ * @param courseId - The course ID
+ * @param strategyKey - The strategy key (typically class name)
+ * @returns The document ID in format `STRATEGY_STATE::{courseId}::{strategyKey}`
+ */
+declare function buildStrategyStateId(courseId: string, strategyKey: string): StrategyStateId;
+
 declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
 declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
 declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
@@ -227,4 +301,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, UserDBInterface, WeightedCard, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, type StrategyStateDoc, type StrategyStateId, UserDBInterface, WeightedCard, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };