@vue-skuilder/db 0.1.31-a → 0.1.31

package/docs/navigators-architecture.md

@@ -374,6 +374,45 @@ Set `staticWeight: true` for foundational strategies that should not be tuned:
 
 ## Creating New Strategies
 
+Strategies can be defined in two places:
+
+- **Framework-internal:** Added directly to `NavigatorRoles` in `index.ts`. Used
+  for general-purpose strategies shipped with the framework.
+- **Consumer-defined:** Registered at app startup via `registerNavigator()`.
+  Used for course-specific strategies that live in the consumer codebase.
+
+Both types participate identically in the pipeline once registered.
+
+### Registration
+
+Framework-internal strategies are listed in the hardcoded `NavigatorRoles` record.
+Consumer-defined strategies use the public `registerNavigator()` API:
+
+```typescript
+import { registerNavigator, NavigatorRole } from '@vue-skuilder/db';
+import { MyFilter } from './MyFilter';
+
+// At app init, before any study session:
+registerNavigator('myFilter', MyFilter, NavigatorRole.FILTER);
+```
+
+The third argument (`role`) is **required** for consumer-defined strategies —
+without it, `PipelineAssembler` cannot classify the strategy and will skip it
+with a warning. For framework-internal strategies the role is already in
+`NavigatorRoles`, so the argument is optional.
+
+A corresponding `NAVIGATION_STRATEGY` document must exist in CouchDB with
+`implementingClass` matching the registered name:
+
+```json
+{
+  "_id": "NAVIGATION_STRATEGY-my-filter",
+  "implementingClass": "myFilter",
+  "name": "My Filter",
+  "serializedData": "{}"
+}
+```
+
 ### Generator
 
 ```typescript
@@ -382,7 +421,7 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
 
   async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
     const candidates = await this.findCandidates(limit);
-    
+
     return candidates.map(c => ({
       cardId: c.id,
       courseId: this.course.getCourseID(),
@@ -400,8 +439,6 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
 }
 ```
 
-Register in `NavigatorRoles` as `NavigatorRole.GENERATOR`.
-
 ### Filter
 
 ```typescript
@@ -413,7 +450,7 @@ class MyFilter extends ContentNavigator implements CardFilter {
       const multiplier = this.computeMultiplier(card, context);
       const newScore = card.score * multiplier;
       const action = multiplier < 1 ? 'penalized' : multiplier > 1 ? 'boosted' : 'passed';
-      
+
       return {
         ...card,
         score: newScore,
@@ -434,7 +471,29 @@ class MyFilter extends ContentNavigator implements CardFilter {
 }
 ```
 
-Register in `NavigatorRoles` as `NavigatorRole.FILTER`.
+### Accessing Strategy State from Consumer Filters
+
+Consumer strategies can share state with other parts of the consumer app via
+`getStrategyState()` / `putStrategyState()`. Override `strategyKey` to read
+an existing state document:
+
+```typescript
+class MyFilter extends ContentNavigator implements CardFilter {
+  // Read the same doc that another part of the app writes
+  protected get strategyKey(): string {
+    return 'MySharedStateKey';
+  }
+
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    const state = await this.getStrategyState<MyStateType>();
+    // ... use state for filtering decisions
+  }
+}
+```
+
+This enables **single source of truth** patterns: the consumer app writes state
+via `UsrCrsDataInterface.putStrategyState()`, and the consumer filter reads it
+via the same key. No framework changes needed.
 
 ---
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.31-a",
+  "version": "0.1.31",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.31-a",
+    "@vue-skuilder/common": "0.1.31",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^7.0.0",
     "vitest": "^4.0.15"
   },
-  "stableVersion": "0.1.31a"
+  "stableVersion": "0.1.31"
 }

package/src/core/interfaces/contentSource.ts

@@ -79,6 +79,12 @@ export interface StudyContentSource {
    * Used for recording learning outcomes.
    */
   getOrchestrationContext?(): Promise<OrchestrationContext>;
+
+  /**
+   * Set ephemeral hints for the next pipeline run.
+   * No-op for sources that don't support hints.
+   */
+  setEphemeralHints?(hints: Record<string, unknown>): void;
 }
 // #endregion docs_StudyContentSource
 

package/src/core/interfaces/courseDB.ts

@@ -100,6 +100,12 @@ export interface CourseDBInterface extends NavigationStrategyManager, StudyConte
    */
   getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
 
+  /**
+   * Get all card IDs in the course.
+   * Used by diagnostics to scan the full card space.
+   */
+  getAllCardIds(): Promise<string[]>;
+
   /**
    * Add a tag to a card
    */

package/src/core/interfaces/dataLayerProvider.ts

@@ -56,4 +56,24 @@ export interface DataLayerProvider {
    * Check if this data layer is read-only
    */
   isReadOnly(): boolean;
+
+  /**
+   * Trigger local replication of a course database.
+   *
+   * When a course opts in via `CourseConfig.localSync.enabled`, this method
+   * replicates the remote course DB to a local PouchDB instance. Subsequent
+   * `getCourseDB()` calls for that course will return a CourseDB that reads
+   * from the local replica (fast, no network) and writes to the remote
+   * (ELO updates, admin ops).
+   *
+   * Safe to call multiple times — concurrent calls coalesce. Returns when
+   * sync is complete (or immediately if already synced / disabled).
+   *
+   * Implementations that don't support local sync may no-op.
+   *
+   * @param courseId - The course to sync locally
+   * @param forceEnabled - Skip CourseConfig check and sync regardless.
+   *   Use when the caller already knows local sync is desired.
+   */
+  ensureCourseSynced?(courseId: string, forceEnabled?: boolean): Promise<void>;
 }