@vue-skuilder/db 0.1.18 → 0.1.20

package/src/core/types/strategyState.ts

@@ -0,0 +1,84 @@
+import { DocType, DocTypePrefixes } from './types-legacy';
+
+/**
+ * Template literal type for strategy state document IDs.
+ *
+ * Format: `STRATEGY_STATE-{courseId}-{strategyKey}`
+ */
+export 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
+ */
+export 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}`
+ */
+export function buildStrategyStateId(courseId: string, strategyKey: string): StrategyStateId {
+  return `STRATEGY_STATE::${courseId}::${strategyKey}`;
+}

package/src/core/types/types-legacy.ts

@@ -19,6 +19,7 @@ export enum DocType {
   SCHEDULED_CARD = 'SCHEDULED_CARD',
   TAG = 'TAG',
   NAVIGATION_STRATEGY = 'NAVIGATION_STRATEGY',
+  STRATEGY_STATE = 'STRATEGY_STATE',
 }
 
 export interface QualifiedCardID {
@@ -103,6 +104,7 @@ export const DocTypePrefixes = {
   [DocType.VIEW]: 'VIEW',
   [DocType.PEDAGOGY]: 'PEDAGOGY',
   [DocType.NAVIGATION_STRATEGY]: 'NAVIGATION_STRATEGY',
+  [DocType.STRATEGY_STATE]: 'STRATEGY_STATE',
 } as const;
 
 export interface CardHistory<T extends CardRecord> {

package/src/impl/common/BaseUserDB.ts

@@ -1,4 +1,4 @@
-import { DocType, DocTypePrefixes } from '@db/core';
+import { DocType, DocTypePrefixes, StrategyStateDoc, buildStrategyStateId } from '@db/core';
 import { getCardHistoryID } from '@db/core/util';
 import { CourseElo, Status } from '@vue-skuilder/common';
 import moment, { Moment } from 'moment';
@@ -1046,6 +1046,61 @@ Currently logged-in as ${this._username}.`
   public async updateUserElo(courseId: string, elo: CourseElo): Promise<PouchDB.Core.Response> {
     return updateUserElo(this._username, courseId, elo);
   }
+
+  public async getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    try {
+      const doc = await this.localDB.get<StrategyStateDoc<T>>(docId);
+      return doc.data;
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status === 404) {
+        return null;
+      }
+      throw e;
+    }
+  }
+
+  public async putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    let existingRev: string | undefined;
+
+    try {
+      const existing = await this.localDB.get<StrategyStateDoc<T>>(docId);
+      existingRev = existing._rev;
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status !== 404) {
+        throw e;
+      }
+    }
+
+    const doc: StrategyStateDoc<T> = {
+      _id: docId,
+      _rev: existingRev,
+      docType: DocType.STRATEGY_STATE,
+      courseId,
+      strategyKey,
+      data,
+      updatedAt: new Date().toISOString(),
+    };
+
+    await this.localDB.put(doc);
+  }
+
+  public async deleteStrategyState(courseId: string, strategyKey: string): Promise<void> {
+    const docId = buildStrategyStateId(courseId, strategyKey);
+    try {
+      const doc = await this.localDB.get(docId);
+      await this.localDB.remove(doc);
+    } catch (e) {
+      const err = e as PouchError;
+      if (err.status === 404) {
+        return;
+      }
+      throw e;
+    }
+  }
 }
 
 export function accomodateGuest(): {
@@ -1056,7 +1111,9 @@ export function accomodateGuest(): {
 
   // Check if localStorage is available (browser environment)
   if (typeof localStorage === 'undefined') {
-    logger.log('[funnel] localStorage not available (Node.js environment), returning default guest');
+    logger.log(
+      '[funnel] localStorage not available (Node.js environment), returning default guest'
+    );
     return {
       username: GuestUsername + 'nodejs-test',
       firstVisit: true,
@@ -1125,11 +1182,21 @@ export function accomodateGuest(): {
       bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
 
       const uuid = [
-        Array.from(bytes.slice(0, 4)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(4, 6)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(6, 8)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(8, 10)).map(b => b.toString(16).padStart(2, '0')).join(''),
-        Array.from(bytes.slice(10, 16)).map(b => b.toString(16).padStart(2, '0')).join(''),
+        Array.from(bytes.slice(0, 4))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(4, 6))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(6, 8))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(8, 10))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
+        Array.from(bytes.slice(10, 16))
+          .map((b) => b.toString(16).padStart(2, '0'))
+          .join(''),
       ].join('-');
 
       logger.log('[funnel] Generated UUID using crypto.getRandomValues():', uuid);

package/src/impl/couch/adminDB.ts

@@ -80,8 +80,7 @@ export class AdminDB implements AdminDBInterface {
       }
     }
 
-    const dbs = await Promise.all(promisedCRDbs);
-    return dbs.map((db) => {
+    return promisedCRDbs.map((db) => {
       return {
         ...db.getConfig(),
         _id: db._id,

package/src/impl/couch/courseDB.ts

@@ -270,16 +270,6 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
       }
     });
 
-    await Promise.all(
-      cards.rows.map((r) => {
-        return async () => {
-          if (isSuccessRow(r)) {
-            ret[r.id] = r.doc!.id_displayable_data;
-          }
-        };
-      })
-    );
-
     return ret;
   }
 
@@ -379,6 +369,36 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     }
   }
 
+  async getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>> {
+    if (cardIds.length === 0) {
+      return new Map();
+    }
+
+    const db = getCourseDB(this.id);
+    const result = await db.query<TagStub>('getTags', {
+      keys: cardIds,
+      include_docs: false,
+    });
+
+    const tagsByCard = new Map<string, string[]>();
+
+    // Initialize all requested cards with empty arrays
+    for (const cardId of cardIds) {
+      tagsByCard.set(cardId, []);
+    }
+
+    // Populate from query results
+    for (const row of result.rows) {
+      const cardId = row.key as string;
+      const tagName = row.value?.name;
+      if (tagName && tagsByCard.has(cardId)) {
+        tagsByCard.get(cardId)!.push(tagName);
+      }
+    }
+
+    return tagsByCard;
+  }
+
   async addTagToCard(
     cardId: string,
     tagId: string,

package/src/impl/static/courseDB.ts

@@ -249,6 +249,17 @@ export class StaticCourseDB implements CourseDBInterface {
     }
   }
 
+  async getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>> {
+    const tagsIndex = await this.unpacker.getTagsIndex();
+    const tagsByCard = new Map<string, string[]>();
+
+    for (const cardId of cardIds) {
+      tagsByCard.set(cardId, tagsIndex.byCard[cardId] || []);
+    }
+
+    return tagsByCard;
+  }
+
   async addTagToCard(_cardId: string, _tagId: string): Promise<PouchDB.Core.Response> {
     throw new Error('Cannot modify tags in static mode');
   }

package/tests/core/navigators/Pipeline.test.ts

@@ -102,6 +102,7 @@ function createMockContext(): { user: UserDBInterface; course: CourseDBInterface
 
   const mockCourse = {
     getCourseID: vi.fn().mockReturnValue('test-course'),
+    getAppliedTagsBatch: vi.fn().mockResolvedValue(new Map()),
   } as unknown as CourseDBInterface;
 
   return { user: mockUser, course: mockCourse };

package/docs/todo-pipeline-optimization.md

@@ -1,117 +0,0 @@
-# TODO: Pipeline Optimization - Batch Tag Hydration
-
-## Status: NOT STARTED
-
-## Problem
-
-Each filter strategy independently queries for card tags, resulting in redundant database operations.
-
-For N cards through 3 filters = 3N tag lookups, when N would suffice.
-
-```typescript
-// In HierarchyDefinitionNavigator
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-
-// In InterferenceMitigatorNavigator  
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-
-// In RelativePriorityNavigator
-const tagResponse = await context.course.getAppliedTags(card.cardId);
-```
-
-## Proposed Solution: Hydrate Tags in WeightedCard
-
-Extend `WeightedCard` to optionally carry pre-fetched tag data:
-
-```typescript
-interface WeightedCard {
-  cardId: string;
-  courseId: string;
-  score: number;
-  provenance: StrategyContribution[];
-  
-  /** Pre-fetched tags. If present, filters should use this instead of querying. */
-  tags?: string[];
-}
-```
-
-### Implementation Steps
-
-#### Step 1: Add batch tag lookup method
-
-```typescript
-// In CourseDBInterface
-getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
-```
-
-#### Step 2: Update WeightedCard type
-
-Add optional `tags?: string[]` field to `WeightedCard` in `core/navigators/index.ts`.
-
-#### Step 3: Hydrate in Pipeline
-
-The `Pipeline` class should batch-fetch tags after getting candidates from the generator:
-
-```typescript
-async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-  const context = await this.buildContext();
-  let cards = await this.generator.getWeightedCards(fetchLimit, context);
-  
-  // Batch hydrate tags
-  cards = await this.hydrateTags(cards);
-  
-  for (const filter of this.filters) {
-    cards = await filter.transform(cards, context);
-  }
-  
-  return cards.filter(c => c.score > 0)
-              .sort((a, b) => b.score - a.score)
-              .slice(0, limit);
-}
-
-private async hydrateTags(cards: WeightedCard[]): Promise<WeightedCard[]> {
-  const cardIds = cards.map(c => c.cardId);
-  const tagsByCard = await this.course.getAppliedTagsBatch(cardIds);
-  
-  return cards.map(c => ({
-    ...c,
-    tags: tagsByCard.get(c.cardId) ?? []
-  }));
-}
-```
-
-#### Step 4: Update filter strategies
-
-Each filter checks for pre-hydrated tags before querying:
-
-```typescript
-const cardTags = card.tags ?? await this.getCardTags(card.cardId, context.course);
-```
-
-#### Step 5: Add tests
-
-- Verify tags are populated by Pipeline
-- Verify filters use pre-fetched tags when available
-- Verify fallback works if tags missing
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `core/navigators/index.ts` | Add `tags?` to `WeightedCard` |
-| `core/interfaces/courseDB.ts` | Add `getAppliedTagsBatch()` |
-| `impl/couch/courseDB.ts` | Implement `getAppliedTagsBatch()` |
-| `impl/static/courseDB.ts` | Implement `getAppliedTagsBatch()` |
-| `core/navigators/Pipeline.ts` | Add `hydrateTags()` step |
-| `core/navigators/hierarchyDefinition.ts` | Use `card.tags` if available |
-| `core/navigators/interferenceMitigator.ts` | Use `card.tags` if available |
-| `core/navigators/relativePriority.ts` | Use `card.tags` if available |
-
-## Performance Expectations
-
-| Scenario | Before | After |
-|----------|--------|-------|
-| 20 cards, 3 filters | 60 tag queries | 1 batch query (20 cards) |
-| 50 cards, 4 filters | 200 tag queries | 1 batch query (50 cards) |
-
-Batch queries also reduce round-trip overhead compared to individual queries.

package/docs/todo-strategy-state-storage.md

@@ -1,278 +0,0 @@
-# TODO: Strategy-Specific State Storage in UserDB
-
-## Status: NOT STARTED
-
-## Goal
-
-Enable NavigationStrategies (ContentNavigators) to persist their own state data in the
-user's database, allowing strategies to maintain context across sessions.
-
-## Current State
-
-### What Strategies Can Read
-
-| Data | Method | Notes |
-|------|--------|-------|
-| User's global ELO | `user.getCourseRegDoc(courseId).elo.global` | ✅ Available |
-| User's per-tag ELO | `user.getCourseRegDoc(courseId).elo.tags` | ✅ Available |
-| Seen cards | `user.getSeenCards(courseId)` | ✅ Card IDs only |
-| Active cards | `user.getActiveCards()` | ✅ Available |
-| Pending reviews | `user.getPendingReviews(courseId)` | ✅ ScheduledCard objects |
-| Card history | `user.putCardRecord()` returns `CardHistory` | 🟡 Only after write |
-
-### What Strategies Cannot Do
-
-- **Store arbitrary state**: No namespaced storage for strategy-specific data
-- **Track temporal patterns**: No easy way to record "when did I last introduce tag X?"
-- **Persist learning context**: Strategy state is lost between sessions
-
-## Use Cases
-
-### 1. InterferenceMitigator
-
-**Need**: Track when interfering concepts were last introduced together.
-
-```typescript
-// Desired: Store last introduction time per tag
-{
-  "lastIntroduction": {
-    "letter-b": "2024-01-15T10:30:00Z",
-    "letter-d": "2024-01-16T14:20:00Z"
-  }
-}
-```
-
-### 2. Minimal Pairs Strategy (Future)
-
-**Need**: Track discrimination training progress between confusable pairs.
-
-```typescript
-// Desired: Store discrimination scores per pair
-{
-  "pairScores": {
-    "b-d": { "correct": 15, "total": 20, "lastPracticed": "..." },
-    "m-n": { "correct": 8, "total": 10, "lastPracticed": "..." }
-  }
-}
-```
-
-### 3. Adaptive Pacing Strategy (Future)
-
-**Need**: Track user's engagement patterns and optimal session timing.
-
-```typescript
-// Desired: Store engagement metrics
-{
-  "sessionMetrics": {
-    "avgAccuracyByTimeOfDay": { "morning": 0.85, "afternoon": 0.78 },
-    "optimalSessionLength": 180,  // seconds
-    "fatigueThreshold": 12        // cards before accuracy drops
-  }
-}
-```
-
-## Proposed Solutions
-
-### Option A: Extend CourseRegistration
-
-Add a `strategyState` field to the existing `CourseRegistration` document.
-
-**Schema:**
-```typescript
-interface CourseRegistration {
-  // ... existing fields ...
-  
-  /**
-   * Strategy-specific state, keyed by strategy ID or type.
-   * Each strategy owns its own namespace.
-   */
-  strategyState?: {
-    [strategyKey: string]: unknown;
-  };
-}
-```
-
-**Pros:**
-- No new document types
-- Lives alongside other course-specific user data
-- Already synced via existing mechanisms
-
-**Cons:**
-- Potential for large documents if strategies store lots of data
-- All strategies share one document (contention on updates)
-
----
-
-### Option B: Separate Strategy State Documents
-
-Create a new document type for strategy state.
-
-**Schema:**
-```typescript
-interface StrategyStateDoc {
-  _id: `STRATEGY_STATE-${courseId}-${strategyKey}`;
-  docType: DocType.STRATEGY_STATE;
-  courseId: string;
-  strategyKey: string;  // e.g., "interferenceMitigator" or strategy instance ID
-  data: unknown;
-  updatedAt: string;
-}
-```
-
-**Pros:**
-- Clean separation
-- No document size concerns
-- Independent updates (no contention)
-
-**Cons:**
-- New document type to manage
-- More queries to fetch state
-
----
-
-### Option C: Generic Key-Value Store in UserDB
-
-Add generic methods for namespaced storage.
-
-**Interface:**
-```typescript
-interface UserDBWriter {
-  // ... existing methods ...
-  
-  /**
-   * Store data in a namespaced location.
-   * @param namespace - Unique namespace (e.g., "strategy:interferenceMitigator:course123")
-   * @param data - Arbitrary JSON-serializable data
-   */
-  putNamespacedData(namespace: string, data: unknown): Promise<void>;
-  
-  /**
-   * Retrieve namespaced data.
-   * @param namespace - The namespace to retrieve
-   * @returns The stored data, or null if not found
-   */
-  getNamespacedData<T>(namespace: string): Promise<T | null>;
-  
-  /**
-   * Delete namespaced data.
-   * @param namespace - The namespace to delete
-   */
-  deleteNamespacedData(namespace: string): Promise<void>;
-}
-```
-
-**Pros:**
-- Most flexible
-- Reusable beyond strategies
-- Clean API
-
-**Cons:**
-- Very generic (might be too permissive)
-- Namespace collision risk
-
----
-
-## Recommended Approach
-
-**Option B (Separate Documents)** with a convenience wrapper:
-
-```typescript
-// In ContentNavigator base class or a mixin
-abstract class ContentNavigator {
-  // ... existing methods ...
-  
-  /**
-   * Get this strategy's persisted state for the current course.
-   */
-  protected async getStrategyState<T>(): Promise<T | null> {
-    const key = `STRATEGY_STATE-${this.course.getCourseID()}-${this.strategyKey}`;
-    try {
-      return await this.user.get<T>(key);
-    } catch (e) {
-      return null;  // Not found
-    }
-  }
-  
-  /**
-   * Persist this strategy's state for the current course.
-   */
-  protected async putStrategyState<T>(data: T): Promise<void> {
-    const key = `STRATEGY_STATE-${this.course.getCourseID()}-${this.strategyKey}`;
-    const existing = await this.getStrategyState<T>();
-    await this.user.put({
-      _id: key,
-      _rev: existing?._rev,
-      docType: DocType.STRATEGY_STATE,
-      courseId: this.course.getCourseID(),
-      strategyKey: this.strategyKey,
-      data,
-      updatedAt: new Date().toISOString(),
-    });
-  }
-  
-  /**
-   * Unique key for this strategy instance.
-   * Override in subclasses if multiple instances need separate state.
-   */
-  protected get strategyKey(): string {
-    return this.constructor.name;  // e.g., "InterferenceMitigatorNavigator"
-  }
-}
-```
-
-## Implementation Plan
-
-### Phase 1: Add DocType and Interface
-
-1. Add `STRATEGY_STATE` to `DocType` enum in `packages/db/src/core/types/types-legacy.ts`
-2. Define `StrategyStateDoc` interface
-3. Add prefix to `DocTypePrefixes`
-
-### Phase 2: Add UserDB Methods
-
-1. Add `getStrategyState()` and `putStrategyState()` to `UserDBInterface`
-2. Implement in `CouchUserDB`
-
-### Phase 3: Add ContentNavigator Helpers
-
-1. Add protected helper methods to `ContentNavigator` base class
-2. Document usage pattern
-
-### Phase 4: Update Strategies
-
-1. Update `InterferenceMitigatorNavigator` to use state storage
-2. Add tests for state persistence
-
-## Files to Create/Modify
-
-| File | Action | Description |
-|------|--------|-------------|
-| `packages/db/src/core/types/types-legacy.ts` | MODIFY | Add STRATEGY_STATE DocType |
-| `packages/db/src/core/types/strategyState.ts` | CREATE | StrategyStateDoc interface |
-| `packages/db/src/core/interfaces/userDB.ts` | MODIFY | Add state storage methods |
-| `packages/db/src/impl/couch/userDB.ts` | MODIFY | Implement state storage |
-| `packages/db/src/core/navigators/index.ts` | MODIFY | Add helper methods to base class |
-| `packages/db/src/core/navigators/interferenceMitigator.ts` | MODIFY | Use state storage |
-
-## Test Cases
-
-1. **Store and retrieve**: Write state, read it back, verify equality
-2. **Update existing**: Write state, update it, verify new value
-3. **Separate namespaces**: Two strategies store data, each gets their own
-4. **Cross-session persistence**: Store state, simulate new session, verify data persists
-5. **Missing state**: Read state that doesn't exist, get null (not error)
-
-## Open Questions
-
-1. **State migration**: How to handle strategy state when strategy config changes?
-2. **State cleanup**: When a strategy is deleted, should its state be cleaned up?
-3. **State size limits**: Should we enforce maximum state size?
-4. **Sync behavior**: How does state sync across devices for multi-device users?
-
-## Related Files
-
-- `packages/db/src/core/interfaces/userDB.ts` — UserDB interface
-- `packages/db/src/impl/couch/userDB.ts` — UserDB implementation
-- `packages/db/src/core/navigators/index.ts` — ContentNavigator base class
-- `packages/db/src/core/types/types-legacy.ts` — DocType enum
-- `packages/db/docs/navigators-architecture.md` — Architecture overview