@vue-skuilder/db 0.1.30 → 0.1.31-a

package/docs/navigators-architecture.md

@@ -374,45 +374,6 @@ 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
@@ -421,7 +382,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(),
@@ -439,6 +400,8 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
 }
 ```
 
+Register in `NavigatorRoles` as `NavigatorRole.GENERATOR`.
+
 ### Filter
 
 ```typescript
@@ -450,7 +413,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,
@@ -471,29 +434,7 @@ class MyFilter extends ContentNavigator implements CardFilter {
 }
 ```
 
-### 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.
+Register in `NavigatorRoles` as `NavigatorRole.FILTER`.
 
 ---
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.30",
+  "version": "0.1.31-a",
   "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.30",
+    "@vue-skuilder/common": "0.1.31-a",
     "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.30"
+  "stableVersion": "0.1.31a"
 }

package/src/core/navigators/generators/elo.ts

@@ -88,30 +88,41 @@ export default class ELONavigator extends ContentNavigator implements CardGenera
     const cardIds = newCards.map((c) => c.cardID);
     const cardEloData = await this.course.getCardEloData(cardIds);
 
-    // Score new cards by ELO distance
+    // Score new cards by ELO distance, then apply weighted sampling without
+    // replacement using the Efraimidis-Spirakis (A-Res) algorithm:
+    //
+    //   key = U ^ (1 / rawScore)   where U ~ Uniform(0, 1)
+    //
+    // Sorting by key descending produces a weighted random sample: high-score
+    // cards are still preferred, but cards with equal scores are shuffled
+    // uniformly rather than deterministically. This prevents the same failed
+    // cards from looping back every session when many cards share similar ELO.
+    //
+    // Edge case: rawScore=0 → key=0, never selected (correct exclusion).
     const scored: WeightedCard[] = newCards.map((c, i) => {
       const cardElo = cardEloData[i]?.global?.score ?? 1000;
       const distance = Math.abs(cardElo - userGlobalElo);
-      const score = Math.max(0, 1 - distance / 500);
+      const rawScore = Math.max(0, 1 - distance / 500);
+      const samplingKey = rawScore > 0 ? Math.random() ** (1 / rawScore) : 0;
 
       return {
         cardId: c.cardID,
         courseId: c.courseID,
-        score,
+        score: samplingKey,
         provenance: [
           {
             strategy: 'elo',
             strategyName: this.strategyName || this.name,
             strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
             action: 'generated',
-            score,
-            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`,
+            score: samplingKey,
+            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), raw ${rawScore.toFixed(3)}, key ${samplingKey.toFixed(3)}`,
           },
         ],
       };
     });
 
-    // Sort by score descending
+    // Sort by sampling key descending (weighted sample without replacement)
     scored.sort((a, b) => b.score - a.score);
 
     const result = scored.slice(0, limit);

package/src/core/navigators/index.ts

@@ -46,20 +46,10 @@ export type NavigatorConstructor = new (
 ) => ContentNavigator;
 
 /**
- * Entry in the navigator registry, storing the constructor and an optional
- * pipeline role. The role is used by PipelineAssembler to classify
- * consumer-registered navigators that aren't in the built-in Navigators enum.
- */
-interface NavigatorRegistryEntry {
-  constructor: NavigatorConstructor;
-  role?: NavigatorRole;
-}
-
-/**
- * Registry mapping implementingClass names to navigator entries.
+ * Registry mapping implementingClass names to navigator constructors.
  * Populated by registerNavigator() and used by ContentNavigator.create().
  */
-const navigatorRegistry = new Map<string, NavigatorRegistryEntry>();
+const navigatorRegistry = new Map<string, NavigatorConstructor>();
 
 /**
  * Register a navigator implementation.
@@ -67,21 +57,15 @@ const navigatorRegistry = new Map<string, NavigatorRegistryEntry>();
  * Call this to make a navigator available for instantiation by
  * ContentNavigator.create() without relying on dynamic imports.
  *
- * Passing a `role` is optional for built-in navigators (whose roles are in
- * the hardcoded `NavigatorRoles` record), but **required** for consumer-
- * defined navigators that need to participate in pipeline assembly.
- *
- * @param implementingClass - The class name (e.g., 'elo', 'letterGatingFilter')
+ * @param implementingClass - The class name (e.g., 'elo', 'hierarchyDefinition')
  * @param constructor - The navigator class constructor
- * @param role - Optional pipeline role (GENERATOR or FILTER)
  */
 export function registerNavigator(
   implementingClass: string,
-  constructor: NavigatorConstructor,
-  role?: NavigatorRole
+  constructor: NavigatorConstructor
 ): void {
-  navigatorRegistry.set(implementingClass, { constructor, role });
-  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}${role ? ` (${role})` : ''}`);
+  navigatorRegistry.set(implementingClass, constructor);
+  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}`);
 }
 
 /**
@@ -91,7 +75,7 @@ export function registerNavigator(
  * @returns The constructor, or undefined if not registered
  */
 export function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined {
-  return navigatorRegistry.get(implementingClass)?.constructor;
+  return navigatorRegistry.get(implementingClass);
 }
 
 /**
@@ -104,16 +88,6 @@ export function hasRegisteredNavigator(implementingClass: string): boolean {
   return navigatorRegistry.has(implementingClass);
 }
 
-/**
- * Get the registered role for a navigator, if one was provided at registration.
- *
- * @param implementingClass - The class name to look up
- * @returns The role, or undefined if not registered or no role was specified
- */
-export function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined {
-  return navigatorRegistry.get(implementingClass)?.role;
-}
-
 /**
  * Get all registered navigator names.
  * Useful for debugging and testing.
@@ -397,24 +371,17 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
  * @returns true if the navigator is a generator, false otherwise
  */
 export function isGenerator(impl: string): boolean {
-  if (NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR) return true;
-  // Fallback: check the registry for consumer-registered navigators
-  return getRegisteredNavigatorRole(impl) === NavigatorRole.GENERATOR;
+  return NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR;
 }
 
 /**
  * Check if a navigator implementation is a filter.
  *
- * Checks the built-in NavigatorRoles enum first, then falls back to the
- * navigator registry for consumer-registered navigators.
- *
- * @param impl - Navigator implementation name (e.g., 'elo', 'letterGatingFilter')
+ * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
  * @returns true if the navigator is a filter, false otherwise
  */
 export function isFilter(impl: string): boolean {
-  if (NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER) return true;
-  // Fallback: check the registry for consumer-registered navigators
-  return getRegisteredNavigatorRole(impl) === NavigatorRole.FILTER;
+  return NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER;
 }
 
 /**