@vue-skuilder/db 0.1.18 → 0.1.21

package/dist/pouch/index.js

@@ -40,6 +40,9 @@ var import_pouchdb_find = __toESM(require("pouchdb-find"), 1);
 var import_pouchdb_authentication = __toESM(require("@nilock2/pouchdb-authentication"), 1);
 import_pouchdb.default.plugin(import_pouchdb_find.default);
 import_pouchdb.default.plugin(import_pouchdb_authentication.default);
+if (typeof import_pouchdb.default.debug !== "undefined") {
+  import_pouchdb.default.debug.disable();
+}
 import_pouchdb.default.defaults({
   // ajax: {
   //   timeout: 60000,

package/dist/pouch/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/pouch/index.ts","../../src/impl/couch/pouchdb-setup.ts"],"sourcesContent":["// Export configured PouchDB instance\nexport { default } from '../impl/couch/pouchdb-setup.js';","import PouchDB from 'pouchdb';\nimport PouchDBFind from 'pouchdb-find';\nimport PouchDBAuth from '@nilock2/pouchdb-authentication';\n\n// Register plugins\nPouchDB.plugin(PouchDBFind);\nPouchDB.plugin(PouchDBAuth);\n\n// Configure PouchDB globally\nPouchDB.defaults({\n  // ajax: {\n  //   timeout: 60000,\n  // },\n});\n\nexport default PouchDB;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,qBAAoB;AACpB,0BAAwB;AACxB,oCAAwB;AAGxB,eAAAA,QAAQ,OAAO,oBAAAC,OAAW;AAC1B,eAAAD,QAAQ,OAAO,8BAAAE,OAAW;AAG1B,eAAAF,QAAQ,SAAS;AAAA;AAAA;AAAA;AAIjB,CAAC;AAED,IAAO,wBAAQ,eAAAA;","names":["PouchDB","PouchDBFind","PouchDBAuth"]}
+{"version":3,"sources":["../../src/pouch/index.ts","../../src/impl/couch/pouchdb-setup.ts"],"sourcesContent":["// Export configured PouchDB instance\nexport { default } from '../impl/couch/pouchdb-setup.js';","import PouchDB from 'pouchdb';\nimport PouchDBFind from 'pouchdb-find';\nimport PouchDBAuth from '@nilock2/pouchdb-authentication';\n\n// Register plugins\nPouchDB.plugin(PouchDBFind);\nPouchDB.plugin(PouchDBAuth);\n\n// Disable PouchDB debug logging to prevent interference with CLI prompts\n// Debug logging (like DerivedLogger.emit) will still go to the TUI log file\n// if initializeTuiLogging() has been called, but won't clutter terminal output\nif (typeof PouchDB.debug !== 'undefined') {\n  PouchDB.debug.disable();\n}\n\n// Configure PouchDB globally\nPouchDB.defaults({\n  // ajax: {\n  //   timeout: 60000,\n  // },\n});\n\nexport default PouchDB;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,qBAAoB;AACpB,0BAAwB;AACxB,oCAAwB;AAGxB,eAAAA,QAAQ,OAAO,oBAAAC,OAAW;AAC1B,eAAAD,QAAQ,OAAO,8BAAAE,OAAW;AAK1B,IAAI,OAAO,eAAAF,QAAQ,UAAU,aAAa;AACxC,iBAAAA,QAAQ,MAAM,QAAQ;AACxB;AAGA,eAAAA,QAAQ,SAAS;AAAA;AAAA;AAAA;AAIjB,CAAC;AAED,IAAO,wBAAQ,eAAAA;","names":["PouchDB","PouchDBFind","PouchDBAuth"]}

package/dist/pouch/index.mjs

@@ -4,6 +4,9 @@ import PouchDBFind from "pouchdb-find";
 import PouchDBAuth from "@nilock2/pouchdb-authentication";
 PouchDB.plugin(PouchDBFind);
 PouchDB.plugin(PouchDBAuth);
+if (typeof PouchDB.debug !== "undefined") {
+  PouchDB.debug.disable();
+}
 PouchDB.defaults({
   // ajax: {
   //   timeout: 60000,

package/dist/pouch/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/impl/couch/pouchdb-setup.ts"],"sourcesContent":["import PouchDB from 'pouchdb';\nimport PouchDBFind from 'pouchdb-find';\nimport PouchDBAuth from '@nilock2/pouchdb-authentication';\n\n// Register plugins\nPouchDB.plugin(PouchDBFind);\nPouchDB.plugin(PouchDBAuth);\n\n// Configure PouchDB globally\nPouchDB.defaults({\n  // ajax: {\n  //   timeout: 60000,\n  // },\n});\n\nexport default PouchDB;\n"],"mappings":";AAAA,OAAO,aAAa;AACpB,OAAO,iBAAiB;AACxB,OAAO,iBAAiB;AAGxB,QAAQ,OAAO,WAAW;AAC1B,QAAQ,OAAO,WAAW;AAG1B,QAAQ,SAAS;AAAA;AAAA;AAAA;AAIjB,CAAC;AAED,IAAO,wBAAQ;","names":[]}
+{"version":3,"sources":["../../src/impl/couch/pouchdb-setup.ts"],"sourcesContent":["import PouchDB from 'pouchdb';\nimport PouchDBFind from 'pouchdb-find';\nimport PouchDBAuth from '@nilock2/pouchdb-authentication';\n\n// Register plugins\nPouchDB.plugin(PouchDBFind);\nPouchDB.plugin(PouchDBAuth);\n\n// Disable PouchDB debug logging to prevent interference with CLI prompts\n// Debug logging (like DerivedLogger.emit) will still go to the TUI log file\n// if initializeTuiLogging() has been called, but won't clutter terminal output\nif (typeof PouchDB.debug !== 'undefined') {\n  PouchDB.debug.disable();\n}\n\n// Configure PouchDB globally\nPouchDB.defaults({\n  // ajax: {\n  //   timeout: 60000,\n  // },\n});\n\nexport default PouchDB;\n"],"mappings":";AAAA,OAAO,aAAa;AACpB,OAAO,iBAAiB;AACxB,OAAO,iBAAiB;AAGxB,QAAQ,OAAO,WAAW;AAC1B,QAAQ,OAAO,WAAW;AAK1B,IAAI,OAAO,QAAQ,UAAU,aAAa;AACxC,UAAQ,MAAM,QAAQ;AACxB;AAGA,QAAQ,SAAS;AAAA;AAAA;AAAA;AAIjB,CAAC;AAED,IAAO,wBAAQ;","names":[]}

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 metadata:
 
 ```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:
@@ -192,10 +210,6 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
       }]
     }));
   }
-
-  // Legacy methods - stub or implement for backward compat
-  async getNewCards() { return []; }
-  async getPendingReviews() { return []; }
 }
 ```
 
@@ -228,15 +242,96 @@ class MyFilter extends ContentNavigator implements CardFilter {
     });
   }
 
-  // Legacy methods - filters don't generate cards
+  // Legacy method - filters don't generate cards
   async getWeightedCards() { throw new Error('Use transform() via Pipeline'); }
-  async getNewCards() { return []; }
-  async getPendingReviews() { return []; }
 }
 ```
 
 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 +349,15 @@ 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-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.21",
   "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.21",
     "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.21"
 }

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/classroomDB.ts

@@ -1,6 +1,4 @@
 import { ClassroomConfig } from '@vue-skuilder/common';
-import { ScheduledCard } from '../types/user';
-import { StudySessionNewItem, StudySessionReviewItem } from './contentSource';
 
 /**
  * Classroom management
@@ -29,17 +27,11 @@ export interface TeacherClassroomDBInterface extends ClassroomDBInterface {
   removeContent?(content: AssignedContent): Promise<void>;
 }
 
-export interface StudentClassroomDBInterface extends ClassroomDBInterface {
-  /**
-   * For student interfaces: get pending reviews
-   */
-  getPendingReviews?(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-
-  /**
-   * For student interfaces: get new cards
-   */
-  getNewCards?(limit?: number): Promise<StudySessionNewItem[]>;
-}
+/**
+ * Student-facing classroom interface.
+ * Content is accessed via StudyContentSource.getWeightedCards().
+ */
+export type StudentClassroomDBInterface = ClassroomDBInterface;
 
 export type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
 

package/src/core/interfaces/contentSource.ts

@@ -1,43 +1,10 @@
 import { getDataLayer } from '@db/factory';
 import { UserDBInterface } from '..';
 import { StudentClassroomDB } from '../../impl/couch/classroomDB';
-import { ScheduledCard } from '@db/core/types/user';
 import { WeightedCard } from '../navigators';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
 
-// ============================================================================
-// API MIGRATION NOTICE
-// ============================================================================
-//
-// The StudyContentSource interface is being superseded by the ContentNavigator
-// class and its getWeightedCards() API. See:
-//   packages/db/src/core/navigators/ARCHITECTURE.md
-//
-// HISTORICAL CONTEXT:
-// - This interface was designed to abstract 'classrooms' and 'courses' as
-//   content sources for study sessions.
-// - getNewCards() and getPendingReviews() were artifacts of two hard-coded
-//   navigation strategies: ELO proximity (new) and SRS scheduling (reviews).
-// - The new/review split reflected implementation details, not fundamentals.
-//
-// THE PROBLEM:
-// - "What does 'get reviews' mean for an interference mitigator?" - it doesn't.
-// - SRS is just one strategy that could express review urgency as scores.
-// - Some strategies generate candidates, others filter/score them.
-//
-// THE SOLUTION:
-// - ContentNavigator.getWeightedCards() returns unified scored candidates.
-// - WeightedCard.source field distinguishes new/review/failed (metadata, not API).
-// - Strategies compose via delegate pattern (filter wraps generator).
-//
-// MIGRATION PATH:
-// 1. ContentNavigator implements StudyContentSource for backward compat
-// 2. SessionController will migrate to call getWeightedCards()
-// 3. Legacy methods will be deprecated, then removed
-//
-// ============================================================================
-
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
 export interface StudySessionFailedNewItem extends StudySessionItem {
@@ -89,49 +56,22 @@ export interface ContentSourceID {
 /**
  * Interface for sources that provide study content to SessionController.
  *
- * @deprecated This interface will be superseded by ContentNavigator.getWeightedCards().
- * The getNewCards/getPendingReviews split was an artifact of hard-coded ELO and SRS
- * strategies. The new API returns unified WeightedCard[] with scores.
- *
- * MIGRATION:
- * - Implement ContentNavigator instead of StudyContentSource directly
- * - Override getWeightedCards() as the primary method
- * - Legacy methods can delegate to getWeightedCards() or be left as-is
+ * Content sources return scored candidates via getWeightedCards(), which
+ * SessionController uses to populate study queues.
  *
- * See: packages/db/src/core/navigators/ARCHITECTURE.md
+ * See: packages/db/docs/navigators-architecture.md
  */
 export interface StudyContentSource {
-  /**
-   * Get cards scheduled for review based on SRS algorithm.
-   *
-   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
-   * Review urgency will be expressed as a score rather than a separate method.
-   */
-  getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-
-  /**
-   * Get new cards for introduction, typically ordered by ELO proximity.
-   *
-   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
-   * New card selection and scoring will be unified with review scoring.
-   *
-   * @param n - Maximum number of new cards to return
-   */
-  getNewCards(n?: number): Promise<StudySessionNewItem[]>;
-
   /**
    * Get cards with suitability scores for presentation.
    *
-   * This is the PRIMARY API for content sources going forward. Returns unified
-   * scored candidates that can be sorted and selected by SessionController.
-   *
-   * The `source` field on WeightedCard indicates origin ('new' | 'review' | 'failed')
-   * for queue routing purposes during the migration period.
+   * Returns unified scored candidates that can be sorted and selected by SessionController.
+   * The card origin ('new' | 'review' | 'failed') is determined by provenance metadata.
    *
    * @param limit - Maximum number of cards to return
    * @returns Cards sorted by score descending
    */
-  getWeightedCards?(limit: number): Promise<WeightedCard[]>;
+  getWeightedCards(limit: number): Promise<WeightedCard[]>;
 }
 // #endregion docs_StudyContentSource
 

package/src/core/interfaces/courseDB.ts

@@ -1,5 +1,5 @@
 import { CourseConfig, CourseElo, DataShape, SkuilderCourseData } from '@vue-skuilder/common';
-import { StudySessionNewItem, StudySessionItem } from './contentSource';
+import { StudyContentSource, StudySessionItem } from './contentSource';
 import { TagStub, Tag, QualifiedCardID } from '../types/types-legacy';
 import { DataLayerResult } from '../types/db';
 import { NavigationStrategyManager } from './navigationStrategyManager';
@@ -26,7 +26,7 @@ export interface CourseInfo {
   registeredUsers: number;
 }
 
-export interface CourseDBInterface extends NavigationStrategyManager {
+export interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
   /**
    * Get course config
    */
@@ -74,11 +74,6 @@ export interface CourseDBInterface extends NavigationStrategyManager {
    */
   updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
 
-  /**
-   * Get new cards for study
-   */
-  getNewCards(limit?: number): Promise<StudySessionNewItem[]>;
-
   /**
    * Get cards centered at a particular ELO rating
    */
@@ -92,6 +87,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>;
 }
 
 /**