@vue-skuilder/db 0.1.18 → 0.1.20

package/dist/{types-CzPDLAK6.d.cts → types-Bn0itutr.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-6ettoclI.cjs';
+import { D as DocType } from './types-legacy-DDY4N-Uq.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-CewsN87z.d.ts → types-DQaXnuoc.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-6ettoclI.js';
+import { D as DocType } from './types-legacy-DDY4N-Uq.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-6ettoclI.d.cts → types-legacy-DDY4N-Uq.d.cts}

@@ -13,7 +13,8 @@ declare enum DocType {
     CARDRECORD = "CARDRECORD",
     SCHEDULED_CARD = "SCHEDULED_CARD",
     TAG = "TAG",
-    NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY"
+    NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
+    STRATEGY_STATE = "STRATEGY_STATE"
 }
 interface QualifiedCardID {
     courseID: string;
@@ -89,6 +90,7 @@ declare const DocTypePrefixes: {
     readonly VIEW: "VIEW";
     readonly PEDAGOGY: "PEDAGOGY";
     readonly NAVIGATION_STRATEGY: "NAVIGATION_STRATEGY";
+    readonly STRATEGY_STATE: "STRATEGY_STATE";
 };
 interface CardHistory<T extends CardRecord> {
     _id: PouchDB.Core.DocumentId;

package/dist/{types-legacy-6ettoclI.d.ts → types-legacy-DDY4N-Uq.d.ts}

@@ -13,7 +13,8 @@ declare enum DocType {
     CARDRECORD = "CARDRECORD",
     SCHEDULED_CARD = "SCHEDULED_CARD",
     TAG = "TAG",
-    NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY"
+    NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
+    STRATEGY_STATE = "STRATEGY_STATE"
 }
 interface QualifiedCardID {
     courseID: string;
@@ -89,6 +90,7 @@ declare const DocTypePrefixes: {
     readonly VIEW: "VIEW";
     readonly PEDAGOGY: "PEDAGOGY";
     readonly NAVIGATION_STRATEGY: "NAVIGATION_STRATEGY";
+    readonly STRATEGY_STATE: "STRATEGY_STATE";
 };
 interface CardHistory<T extends CardRecord> {
     _id: PouchDB.Core.DocumentId;

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CzPDLAK6.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-D-Fa4Smt.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-Bn0itutr.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-B_j6u5E4.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-6ettoclI.cjs';
+import '../../types-legacy-DDY4N-Uq.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CewsN87z.js';
-export { C as CouchDBToStaticPacker } from '../../index-CD8BZz2k.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DQaXnuoc.js';
+export { C as CouchDBToStaticPacker } from '../../index-Dj0SEgk3.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-6ettoclI.js';
+import '../../types-legacy-DDY4N-Uq.js';
 import 'moment';

package/docs/navigators-architecture.md

@@ -9,7 +9,7 @@ The navigation strategy system selects and scores cards for study sessions. It u
 
 ### WeightedCard
 
-A card with a suitability score and audit trail:
+A card with a suitability score, audit trail, and pre-fetched data:
 
 ```typescript
 interface WeightedCard {
@@ -17,6 +17,7 @@ interface WeightedCard {
   courseId: string;
   score: number;              // 0-1 suitability score
   provenance: StrategyContribution[];  // Audit trail
+  tags?: string[];            // Pre-fetched tags (hydrated by Pipeline)
 }
 
 interface StrategyContribution {
@@ -57,15 +58,19 @@ interface CardFilter {
 }
 ```
 
+Filters receive cards with pre-hydrated data (e.g., `card.tags`) from Pipeline, eliminating
+redundant database queries.
+
 **Implementations:**
 - `HierarchyDefinitionNavigator` — Gates cards by prerequisite mastery (score=0 if locked)
 - `InterferenceMitigatorNavigator` — Reduces scores for confusable content
 - `RelativePriorityNavigator` — Boosts scores for high-utility content
+- `UserTagPreferenceFilter` — Applies user-configured tag preferences (path constraints)
 - `createEloDistanceFilter()` — Penalizes cards far from user's current ELO
 
 ### Pipeline
 
-Orchestrates generator and filters:
+Orchestrates generator, data hydration, and filters:
 
 ```typescript
 class Pipeline {
@@ -77,13 +82,20 @@ class Pipeline {
   )
 
   async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    // Build shared context (user ELO, etc.)
     const context = await this.buildContext();
+
+    // Generate candidates
     let cards = await this.generator.getWeightedCards(fetchLimit, context);
-    
+
+    // Hydrate shared data (tags, etc.) in single batch query
+    cards = await this.hydrateTags(cards);
+
+    // Apply filters sequentially
     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);
@@ -91,6 +103,12 @@ class Pipeline {
 }
 ```
 
+**Responsibilities:**
+- **Context building** — Fetches shared data (user ELO) once for all strategies
+- **Data hydration** — Pre-fetches commonly needed data (tags) in batch queries
+- **Filter orchestration** — Applies filters in sequence, accumulating provenance
+- **Result selection** — Removes zero-scores, sorts, and returns top N
+
 ## Pipeline Assembly
 
 `PipelineAssembler` builds pipelines from strategy documents:
@@ -237,6 +255,89 @@ class MyFilter extends ContentNavigator implements CardFilter {
 
 Register in `NavigatorRoles` as `NavigatorRole.FILTER`.
 
+## Strategy State Storage
+
+Strategies can persist user-scoped state (preferences, learned patterns, temporal tracking)
+using the `STRATEGY_STATE` document type in the user database.
+
+### Goals vs Preferences vs Inferred
+
+The system distinguishes three types of user-scoped navigation data:
+
+| Type | Defines | Example | Affects ELO | Implementation |
+|------|---------|---------|-------------|----------------|
+| **Goal** | Destination (what to learn) | "Master ear-training" | Yes | `userGoal.ts` (stub) |
+| **Preference** | Path (how to learn) | "Skip text-heavy cards" | No | `filters/userTagPreference.ts` |
+| **Inferred** | Learned patterns | "User prefers visual" | No | `inferredPreference.ts` (stub) |
+
+- **Goals** redefine the optimization target — they scope which content matters for progress
+- **Preferences** constrain the path — they affect card selection without changing progress tracking
+- **Inferred** preferences are learned from behavior — they act as soft suggestions
+
+See stub files for detailed architectural intent on goals and inferred preferences.
+
+### Storage API
+
+`ContentNavigator` provides protected helper methods:
+
+```typescript
+// Get this strategy's persisted state for the current course
+protected async getStrategyState<T>(): Promise<T | null>
+
+// Persist this strategy's state for the current course  
+protected async putStrategyState<T>(data: T): Promise<void>
+
+// Override to customize the storage key (default: constructor name)
+protected get strategyKey(): string
+```
+
+### Document Format
+
+```typescript
+interface StrategyStateDoc<T> {
+  _id: StrategyStateId;  // "STRATEGY_STATE::{courseId}::{strategyKey}"
+  docType: DocType.STRATEGY_STATE;
+  courseId: string;
+  strategyKey: string;
+  data: T;               // Strategy-specific payload
+  updatedAt: string;     // ISO timestamp
+}
+```
+
+### Example: User Tag Preferences
+
+`UserTagPreferenceFilter` reads user preferences from strategy state:
+
+```typescript
+interface UserTagPreferenceState {
+  /**
+   * Tag-specific multipliers.
+   * - 0 = exclude (card score = 0)
+   * - 0.5 = penalize by 50%
+   * - 1.0 = neutral/no effect
+   * - 2.0 = 2x preference boost
+   * - Higher = stronger preference
+   */
+  boost: Record<string, number>;
+  updatedAt: string;
+}
+
+// In filter's transform():
+const prefs = await this.getStrategyState<UserTagPreferenceState>();
+if (!prefs || Object.keys(prefs.boost).length === 0) {
+  return cards; // No preferences configured
+}
+
+// Apply multipliers (max wins when multiple tags match)
+const multiplier = computeMultiplier(cardTags, prefs.boost);
+return { ...card, score: card.score * multiplier };
+```
+
+**UI Component**: `packages/common-ui/src/components/UserTagPreferences.vue`
+- Slider-based interface (0-2 default range, expandable to 10)
+- All sliders share global max for consistent visual comparison
+- Writes to strategy state via `userDB.putStrategyState()`
+
 ## File Reference
 
 | File | Purpose |
@@ -254,12 +355,16 @@ Register in `NavigatorRoles` as `NavigatorRole.FILTER`.
 | `core/navigators/interferenceMitigator.ts` | Interference filter |
 | `core/navigators/relativePriority.ts` | Priority filter |
 | `core/navigators/filters/eloDistance.ts` | ELO distance filter |
+| `core/navigators/filters/userTagPreference.ts` | User tag preference filter |
+| `common-ui/.../UserTagPreferences.vue` | UI for tag preference sliders |
+| `core/navigators/userGoal.ts` | User goal navigator (stub) |
+| `core/navigators/inferredPreference.ts` | Inferred preference navigator (stub) |
+| `core/types/strategyState.ts` | `StrategyStateDoc`, `StrategyStateId` |
 | `impl/couch/courseDB.ts` | `createNavigator()` entry point |
 
-## Related TODOs
+## Related Documentation
 
-- `todo-pipeline-optimization.md` - Batch tag hydration for filter efficiency
-- `todo-strategy-authoring.md` - ux and dx for authoring strategies
-- todo-pipeline-optimization.md - 
-- todo-strategy-state-storage
-- todo-evolutionary-orchestration
+- `todo-pipeline-optimization.md` — Batch tag hydration implementation (✅ completed)
+- `todo-strategy-authoring.md` — UX and DX for authoring strategies
+- `todo-evolutionary-orchestration.md` — Long-term adaptive strategy vision
+- `devlog/1004` — Implementation details for tag hydration optimization

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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.18",
+    "@vue-skuilder/common": "0.1.20",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -60,7 +60,7 @@
     "tsup": "^8.0.2",
     "typescript": "~5.9.3",
     "vite": "^7.0.0",
-    "vitest": "^4.0.14"
+    "vitest": "^4.0.15"
   },
-  "stableVersion": "0.1.18"
+  "stableVersion": "0.1.20"
 }

package/src/core/index.ts

@@ -3,6 +3,7 @@
 export * from './interfaces';
 export * from './types/types-legacy';
 export * from './types/user';
+export * from './types/strategyState';
 export * from '../util/Loggable';
 export * from './util';
 export * from './navigators';

package/src/core/interfaces/courseDB.ts

@@ -92,6 +92,19 @@ export interface CourseDBInterface extends NavigationStrategyManager {
    */
   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
    */

package/src/core/interfaces/userDB.ts

@@ -56,6 +56,18 @@ export interface UserDBReader {
 
   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
    */
@@ -132,6 +144,26 @@ export interface UserDBWriter extends DocumentUpdater {
    * Reset all user data (progress, registrations, etc.) while preserving authentication
    */
   resetUserData(): Promise<{ 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>;
 }
 
 /**

package/src/core/navigators/Pipeline.ts

@@ -9,6 +9,88 @@ import type { CardGenerator, GeneratorContext } from './generators/types';
 import type { StudySessionNewItem, StudySessionReviewItem } from '../interfaces/contentSource';
 import { logger } from '../../util/logger';
 
+// ============================================================================
+// PIPELINE LOGGING HELPERS
+// ============================================================================
+//
+// Focused logging functions that can be toggled by commenting single lines.
+// Use these to inspect pipeline behavior in development/production.
+//
+
+/**
+ * Log pipeline configuration on construction.
+ * Shows generator and filter chain structure.
+ */
+function logPipelineConfig(generator: CardGenerator, filters: CardFilter[]): void {
+  const filterList = filters.length > 0
+    ? '\n    - ' + filters.map(f => f.name).join('\n    - ')
+    : ' none';
+
+  logger.info(
+    `[Pipeline] Configuration:\n` +
+    `  Generator: ${generator.name}\n` +
+    `  Filters:${filterList}`
+  );
+}
+
+/**
+ * Log tag hydration results.
+ * Shows effectiveness of batch query (how many cards/tags were hydrated).
+ */
+function logTagHydration(cards: WeightedCard[], tagsByCard: Map<string, string[]>): void {
+  const totalTags = Array.from(tagsByCard.values()).reduce((sum, tags) => sum + tags.length, 0);
+  const cardsWithTags = Array.from(tagsByCard.values()).filter(tags => tags.length > 0).length;
+
+  logger.debug(
+    `[Pipeline] Tag hydration: ${cards.length} cards, ` +
+    `${cardsWithTags} have tags (${totalTags} total tags) - single batch query`
+  );
+}
+
+/**
+ * Log pipeline execution summary.
+ * Shows complete flow from generator through filters to final results.
+ */
+function logExecutionSummary(
+  generatorName: string,
+  generatedCount: number,
+  filterCount: number,
+  finalCount: number,
+  topScores: number[]
+): void {
+  const scoreDisplay = topScores.length > 0
+    ? topScores.map(s => s.toFixed(2)).join(', ')
+    : 'none';
+
+  logger.info(
+    `[Pipeline] Execution: ${generatorName} produced ${generatedCount} → ` +
+    `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})`
+  );
+}
+
+/**
+ * Log provenance trails for cards.
+ * Shows the complete scoring history for each card through the pipeline.
+ * Useful for debugging why cards scored the way they did.
+ */
+function logCardProvenance(cards: WeightedCard[], maxCards: number = 3): void {
+  const cardsToLog = cards.slice(0, maxCards);
+
+  logger.debug(`[Pipeline] Provenance for top ${cardsToLog.length} cards:`);
+
+  for (const card of cardsToLog) {
+    logger.debug(`[Pipeline]   ${card.cardId} (final score: ${card.score.toFixed(3)}):`);
+
+    for (const entry of card.provenance) {
+      const scoreChange = entry.score.toFixed(3);
+      const action = entry.action.padEnd(9); // Align columns
+      logger.debug(
+        `[Pipeline]     ${action} ${scoreChange} - ${entry.strategyName}: ${entry.reason}`
+      );
+    }
+  }
+}
+
 // ============================================================================
 // PIPELINE
 // ============================================================================
@@ -72,9 +154,8 @@ export class Pipeline extends ContentNavigator {
     this.user = user;
     this.course = course;
 
-    logger.debug(
-      `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(', ')}`
-    );
+    // Toggle pipeline configuration logging:
+    logPipelineConfig(generator, filters);
   }
 
   /**
@@ -82,10 +163,11 @@ export class Pipeline extends ContentNavigator {
    *
    * 1. Build shared context (user ELO, etc.)
    * 2. Get candidates from generator (passing context)
-   * 3. Apply each filter sequentially
-   * 4. Remove zero-score cards
-   * 5. Sort by score descending
-   * 6. Return top N
+   * 3. Batch hydrate tags for all candidates
+   * 4. Apply each filter sequentially
+   * 5. Remove zero-score cards
+   * 6. Sort by score descending
+   * 7. Return top N
    *
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
@@ -104,8 +186,12 @@ export class Pipeline extends ContentNavigator {
 
     // Get candidates from generator, passing context
     let cards = await this.generator.getWeightedCards(fetchLimit, context);
+    const generatedCount = cards.length;
+
+    logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
 
-    logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
+    // Batch hydrate tags before filters run
+    cards = await this.hydrateTags(cards);
 
     // Apply filters sequentially
     for (const filter of this.filters) {
@@ -123,16 +209,43 @@ export class Pipeline extends ContentNavigator {
     // Return top N
     const result = cards.slice(0, limit);
 
-    logger.debug(
-      `[Pipeline] Returning ${result.length} cards (top scores: ${result
-        .slice(0, 3)
-        .map((c) => c.score.toFixed(2))
-        .join(', ')}...)`
-    );
+    // Toggle execution summary logging:
+    const topScores = result.slice(0, 3).map(c => c.score);
+    logExecutionSummary(this.generator.name, generatedCount, this.filters.length, result.length, topScores);
+
+    // Toggle provenance logging (shows scoring history for top cards):
+    logCardProvenance(result, 3);
 
     return result;
   }
 
+  /**
+   * Batch hydrate tags for all cards.
+   *
+   * Fetches tags for all cards in a single database query and attaches them
+   * to the WeightedCard objects. Filters can then use card.tags instead of
+   * making individual getAppliedTags() calls.
+   *
+   * @param cards - Cards to hydrate
+   * @returns Cards with tags populated
+   */
+  private async hydrateTags(cards: WeightedCard[]): Promise<WeightedCard[]> {
+    if (cards.length === 0) {
+      return cards;
+    }
+
+    const cardIds = cards.map((c) => c.cardId);
+    const tagsByCard = await this.course!.getAppliedTagsBatch(cardIds);
+
+    // Toggle tag hydration logging:
+    logTagHydration(cards, tagsByCard);
+
+    return cards.map((card) => ({
+      ...card,
+      tags: tagsByCard.get(card.cardId) ?? [],
+    }));
+  }
+
   /**
    * Build shared context for generator and filters.
    *

package/src/core/navigators/filters/index.ts

@@ -4,3 +4,6 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './types';
 // Filter implementations
 export { createEloDistanceFilter } from './eloDistance';
 export type { EloDistanceConfig } from './eloDistance';
+
+export { default as UserTagPreferenceFilter } from './userTagPreference';
+export type { UserTagPreferenceState } from './userTagPreference';