@vue-skuilder/db 0.1.24 → 0.1.25

package/docs/navigators-architecture.md

@@ -46,11 +46,28 @@ interface CardGenerator {
 ```
 
 **Implementations:**
-- `ELONavigator` — New cards scored by ELO proximity to user skill
-- `SRSNavigator` — Review cards scored by overdueness and interval recency
+- `ELONavigator` — New cards scored by ELO proximity to user skill (scores 0.0-1.0)
+- `SRSNavigator` — Review cards scored by overdueness, interval recency, and **backlog pressure** (scores 0.5-1.0)
 - `HardcodedOrderNavigator` — Fixed sequence defined by course author
 - `CompositeGenerator` — Merges multiple generators with frequency boost
 
+#### SRS Backlog Pressure
+
+The SRS generator implements a self-regulating **backlog pressure** mechanism that prevents review pile-up while maintaining healthy new/review balance:
+
+- **Healthy backlog** (≤20 due reviews): No pressure boost, scores 0.5-0.95. New content (ELO) naturally dominates.
+- **Elevated backlog** (40 due): +0.25 boost, scores 0.75-1.0. Reviews compete with new cards.
+- **High backlog** (60+ due): +0.50 boost (max), scores 0.95-1.0. Reviews take priority.
+
+This treats SRS scheduling times as **eligibility dates** rather than hard due dates—reviewing slightly later may be optimal. The system maintains a healthy backlog rather than always clearing to zero (avoiding "Anki death spiral").
+
+Configuration via strategy `serializedData`:
+```json
+{ "healthyBacklog": 20 }
+```
+
+See `todo-review-adaptation.md` for planned per-user adaptation extensions.
+
 ### CardFilter
 
 Transforms card scores (pure function, no side effects):
@@ -516,8 +533,8 @@ return { ...card, score: card.score * multiplier };
 | `core/navigators/Pipeline.ts` | Pipeline orchestration |
 | `core/navigators/PipelineAssembler.ts` | Builds Pipeline from strategy docs |
 | `core/navigators/CompositeGenerator.ts` | Merges multiple generators |
-| `core/navigators/elo.ts` | ELO generator |
-| `core/navigators/srs.ts` | SRS generator |
+| `core/navigators/generators/elo.ts` | ELO generator |
+| `core/navigators/generators/srs.ts` | SRS generator (with backlog pressure) |
 | `core/navigators/hardcodedOrder.ts` | Fixed-order generator |
 | `core/navigators/hierarchyDefinition.ts` | Prerequisite filter |
 | `core/navigators/interferenceMitigator.ts` | Interference filter |
@@ -541,6 +558,7 @@ return { ...card, score: card.score * multiplier };
 ## Related Documentation
 
 - `todo-strategy-authoring.md` — UX and DX for authoring strategies
+- `todo-review-adaptation.md` — Planned per-user review urgency adaptation
 - `future-orchestration-vision.md` — Long-term adaptive strategy vision (beyond current implementation)
 - `devlog/1004` — Implementation details for tag hydration optimization
 - `devlog/1032-orchestrator` — Evolutionary orchestration implementation details

package/docs/todo-review-urgency-adaptation.md

@@ -0,0 +1,205 @@
+# Future Work: Dynamic Review Urgency Adaptation
+
+This document outlines planned extensions to the SRS backlog pressure system for adaptive review urgency tuning.
+
+## Background
+
+The SRS generator now implements **backlog pressure** — a mechanism that boosts review urgency when the number of due reviews exceeds a "healthy" threshold (default: 20). This ensures reviews don't pile up indefinitely while maintaining a healthy mix of new and review content.
+
+See implementation: `core/navigators/generators/srs.ts`
+
+This document describes two extension directions:
+1. **Global/Orchestration Layer** — Course-wide tuning via learnable weights
+2. **Per-User Adaptation** — Individual urgency multipliers based on review outcomes
+
+---
+
+## Extension 1: Orchestrator-Tuned Generator Weights
+
+### Current State
+
+The orchestration layer (`core/orchestration/`) already supports learnable weights:
+
+```typescript
+interface LearnableWeight {
+  weight: number;       // Peak value, 1.0 = neutral
+  confidence: number;   // 0-1, controls exploration width
+  sampleSize: number;   // Observations collected
+}
+```
+
+When a strategy has `learnable` set and `staticWeight: false`, the orchestrator:
+1. Distributes users across a weight range (bell curve around peak)
+2. Records learning outcomes per user
+3. Correlates user deviation with outcomes via gradient estimation
+4. Updates peak weight toward observed optimum
+
+### Application to Review Balance
+
+The orchestrator can tune the ELO vs SRS balance by experimenting with their weights.
+
+In `CompositeGenerator.getWeightedCards()`, weights are already applied:
+
+```typescript
+let weight = gen.learnable?.weight ?? 1.0;
+if (gen.learnable && !gen.staticWeight && context.orchestration) {
+  weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);
+}
+```
+
+If SRS has `learnable: { weight: 1.0, confidence: 0.5, sampleSize: 0 }`, the orchestrator will try variations (0.8, 1.2, etc.) and correlate with learning outcomes.
+
+### Required Work
+
+- [ ] Ensure default ELO and SRS strategy documents include `learnable` config
+- [ ] Verify outcome correlation tracks success/failure per card source (generator provenance)
+- [ ] Consider weight bounds (e.g., SRS weight ∈ [0.5, 2.0]) to prevent extreme tuning
+- [ ] Test interaction with backlog pressure — may need to mark backlog-pressure-derived scores as non-learnable
+
+### Risks
+
+- Orchestrator experiments could override backlog pressure intent
+- May need to separate "base urgency" (learnable) from "backlog pressure" (not learnable)
+
+### Priority
+
+**Low** — The backlog pressure mechanism should handle balance well. Orchestrator tuning is a refinement layer that can be enabled later.
+
+---
+
+## Extension 2: Per-User Review Urgency Adaptation
+
+### Concept
+
+Users have different memory characteristics. A "forgetful" user needs more review pressure; a "retentive" user needs less. Rather than one-size-fits-all, maintain a per-user `reviewUrgencyMultiplier` that adapts based on review outcomes.
+
+### Proposed Data Model
+
+```typescript
+interface ReviewAdaptationState {
+  urgencyMultiplier: number;  // Default 1.0, range [0.5, 2.0]
+  windowStart: string;        // ISO timestamp for rolling window
+  windowFailures: number;     // Failures in current window
+  windowSuccesses: number;    // Successes in current window
+  lastUpdated: string;        // ISO timestamp
+}
+```
+
+### Update Rules
+
+- On failed review: `multiplier = min(2.0, multiplier + 0.05)`
+- On successful review: `multiplier = max(0.5, multiplier - 0.01)`
+
+**Asymmetry rationale**:
+- Failures increase pressure quickly (5x faster than decrease)
+- Successes slowly reduce pressure (avoid death spiral from one good session)
+
+### Equilibrium Analysis
+
+At equilibrium: `0.05 * failRate = 0.01 * (1 - failRate)`
+
+Solving: `failRate = 0.167` (16.7%)
+
+This means:
+- User with 16.7% failure rate → multiplier stable
+- User with >16.7% failure rate → multiplier increases (more review pressure)
+- User with <16.7% failure rate → multiplier decreases (less review pressure)
+
+The equilibrium threshold can be tuned by adjusting increment/decrement rates.
+
+### Application in Scoring
+
+In SRS urgency calculation:
+
+```typescript
+const userAdaptation = await this.getReviewAdaptation();
+const adaptedUrgency = baseUrgency * userAdaptation.urgencyMultiplier;
+const score = Math.min(1.0, 0.5 + adaptedUrgency * 0.45 + backlogPressure);
+```
+
+Note: multiplier affects base urgency, not backlog pressure. This preserves the global backlog escape mechanism.
+
+### Storage
+
+Use strategy state storage (per-user, per-course, per-strategy):
+
+```typescript
+const state = await this.getStrategyState<ReviewAdaptationState>();
+await this.putStrategyState({ ...state, urgencyMultiplier: newValue });
+```
+
+### Implementation Sketch
+
+```typescript
+// In srs.ts
+
+private async getReviewAdaptation(): Promise<ReviewAdaptationState> {
+  const state = await this.getStrategyState<ReviewAdaptationState>();
+  return state || {
+    urgencyMultiplier: 1.0,
+    windowStart: new Date().toISOString(),
+    windowFailures: 0,
+    windowSuccesses: 0,
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+// Called after review outcome recorded (needs integration hook)
+async updateReviewAdaptation(success: boolean): Promise<void> {
+  const state = await this.getReviewAdaptation();
+  
+  if (success) {
+    state.urgencyMultiplier = Math.max(0.5, state.urgencyMultiplier - 0.01);
+    state.windowSuccesses++;
+  } else {
+    state.urgencyMultiplier = Math.min(2.0, state.urgencyMultiplier + 0.05);
+    state.windowFailures++;
+  }
+  
+  state.lastUpdated = new Date().toISOString();
+  await this.putStrategyState(state);
+}
+```
+
+### Required Work
+
+- [ ] Add `getReviewAdaptation()` method to SRSNavigator
+- [ ] Integrate `updateReviewAdaptation()` with card response recording flow
+- [ ] Decide: Should multiplier affect backlog pressure or just base urgency?
+- [ ] Consider reset behavior on long breaks (user returning after 6 months)
+- [ ] Consider course-specific vs global multipliers
+- [ ] Add provenance entry explaining multiplier contribution
+
+### Open Questions
+
+1. **Who calls `updateReviewAdaptation`?** — Needs hook into card response recording (currently in `UserDB.recordInteraction()` or similar)
+
+2. **Rolling window reset?** — Should the window reset periodically to allow recovery from bad streaks?
+
+3. **Visibility?** — Should users see their current multiplier? Could be motivating or discouraging.
+
+4. **Initial calibration?** — New users start at 1.0. Should there be an initial calibration period with more aggressive updates?
+
+### Priority
+
+**Medium** — High value for learning outcomes, moderate implementation complexity. Requires integration with card response recording flow.
+
+---
+
+## Implementation Order
+
+1. ✅ **Backlog Pressure** (implemented) — Fixes immediate balance issue
+2. **Per-User Adaptation** — High value, moderate complexity
+3. **Orchestrator Tuning** — Lower priority if backlog pressure works well
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `core/navigators/generators/srs.ts` | SRS urgency calculation, backlog pressure |
+| `core/orchestration/index.ts` | Orchestration context, deviation logic |
+| `core/types/contentNavigationStrategy.ts` | Strategy config, learnable weights |
+| `core/types/strategyState.ts` | Per-user strategy state storage |
+| `impl/couch/userDB.ts` | User interaction recording |

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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.24",
+    "@vue-skuilder/common": "0.1.25",
     "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.24"
+  "stableVersion": "0.1.25"
 }

package/src/core/interfaces/userDB.ts

@@ -63,6 +63,11 @@ export interface UserDBReader {
    * Strategies use this to persist preferences, learned patterns, or temporal
    * tracking data across sessions. Each strategy owns its own namespace.
    *
+   * @deprecated Use `getCourseInterface(courseId).getStrategyState(strategyKey)` instead.
+   * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+   * allowing accidental cross-course data access. The course-scoped interface binds
+   * courseId once at construction.
+   *
    * @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
@@ -152,6 +157,11 @@ export interface UserDBWriter extends DocumentUpdater {
    * Strategies use this to persist preferences, learned patterns, or temporal
    * tracking data across sessions. Each strategy owns its own namespace.
    *
+   * @deprecated Use `getCourseInterface(courseId).putStrategyState(strategyKey, data)` instead.
+   * Direct use bypasses course-scoping safety — the courseId parameter is unguarded,
+   * allowing accidental cross-course data writes. The course-scoped interface binds
+   * courseId once at construction.
+   *
    * @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
@@ -161,6 +171,9 @@ export interface UserDBWriter extends DocumentUpdater {
   /**
    * Delete strategy-specific state for a course.
    *
+   * @deprecated Use `getCourseInterface(courseId).deleteStrategyState(strategyKey)` instead.
+   * Direct use bypasses course-scoping safety.
+   *
    * @param courseId - The course this state applies to
    * @param strategyKey - Unique key identifying the strategy (typically class name)
    */
@@ -228,6 +241,37 @@ export interface UsrCrsDataInterface {
   getCourseSettings(): Promise<UserCourseSettings>;
   updateCourseSettings(updates: UserCourseSetting[]): void; // [ ] return a result of some sort?
   // getRegistrationDoc(): Promise<CourseRegistration>;
+
+  /**
+   * Get strategy-specific state for this course.
+   *
+   * Course-scoped alternative to `UserDBInterface.getStrategyState()`.
+   * The courseId is bound at construction via `getCourseInterface(courseId)`,
+   * so callers cannot accidentally access another course's state.
+   *
+   * @param strategyKey - Unique key identifying the state document
+   * @returns The state payload, or null if no state exists
+   */
+  getStrategyState<T>(strategyKey: string): Promise<T | null>;
+
+  /**
+   * Store strategy-specific state for this course.
+   *
+   * Course-scoped alternative to `UserDBInterface.putStrategyState()`.
+   *
+   * @param strategyKey - Unique key identifying the state document
+   * @param data - The state payload to store
+   */
+  putStrategyState<T>(strategyKey: string, data: T): Promise<void>;
+
+  /**
+   * Delete strategy-specific state for this course.
+   *
+   * Course-scoped alternative to `UserDBInterface.deleteStrategyState()`.
+   *
+   * @param strategyKey - Unique key identifying the state document
+   */
+  deleteStrategyState(strategyKey: string): Promise<void>;
 }
 
 export type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';

package/src/core/navigators/Pipeline.ts

@@ -7,6 +7,7 @@ import type { CardFilter, FilterContext } from './filters/types';
 import type { CardGenerator, GeneratorContext } from './generators/types';
 import { logger } from '../../util/logger';
 import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
+import { captureRun, buildRunReport, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
 
 // ============================================================================
 // PIPELINE LOGGING HELPERS
@@ -52,14 +53,29 @@ function logExecutionSummary(
   generatedCount: number,
   filterCount: number,
   finalCount: number,
-  topScores: number[]
+  topScores: number[],
+  filterImpacts: Array<{ name: string; boosted: number; penalized: number; passed: number }>
 ): void {
   const scoreDisplay =
     topScores.length > 0 ? topScores.map((s) => s.toFixed(2)).join(', ') : 'none';
 
+  let filterSummary = '';
+  if (filterImpacts.length > 0) {
+    const impacts = filterImpacts.map((f) => {
+      const parts: string[] = [];
+      if (f.boosted > 0) parts.push(`+${f.boosted}`);
+      if (f.penalized > 0) parts.push(`-${f.penalized}`);
+      if (f.passed > 0) parts.push(`=${f.passed}`);
+      return `${f.name}: ${parts.join('/')}`;
+    });
+    filterSummary = `\n  Filter impact: ${impacts.join(', ')}`;
+  }
+
   logger.info(
     `[Pipeline] Execution: ${generatorName} produced ${generatedCount} → ` +
-      `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})`
+      `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})` +
+      filterSummary +
+      `\n  💡 Inspect: window.skuilder.pipeline`
   );
 }
 
@@ -190,17 +206,63 @@ export class Pipeline extends ContentNavigator {
     // Get candidates from generator, passing context
     let cards = await this.generator.getWeightedCards(fetchLimit, context);
     const generatedCount = cards.length;
+    
+    // Capture generator breakdown for debugging (if CompositeGenerator)
+    let generatorSummaries: GeneratorSummary[] | undefined;
+    if ((this.generator as any).generators) {
+      // This is a CompositeGenerator - extract per-generator info from provenance
+      const genMap = new Map<string, { cards: WeightedCard[] }>();
+      for (const card of cards) {
+        const firstProv = card.provenance[0];
+        if (firstProv) {
+          const genName = firstProv.strategyName;
+          if (!genMap.has(genName)) {
+            genMap.set(genName, { cards: [] });
+          }
+          genMap.get(genName)!.cards.push(card);
+        }
+      }
+      generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
+        const newCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('new card'));
+        const reviewCards = data.cards.filter((c) => c.provenance[0]?.reason?.includes('review'));
+        return {
+          name,
+          cardCount: data.cards.length,
+          newCount: newCards.length,
+          reviewCount: reviewCards.length,
+          topScore: Math.max(...data.cards.map((c) => c.score), 0),
+        };
+      });
+    }
 
     logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
 
     // Batch hydrate tags before filters run
     cards = await this.hydrateTags(cards);
+    
+    // Keep a copy of all cards for debug capture (before filtering removes any)
+    const allCardsBeforeFiltering = [...cards];
 
-    // Apply filters sequentially
+    // Apply filters sequentially, tracking impact
+    const filterImpacts: FilterImpact[] = [];
     for (const filter of this.filters) {
       const beforeCount = cards.length;
+      const beforeScores = new Map(cards.map((c) => [c.cardId, c.score]));
       cards = await filter.transform(cards, context);
-      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} → ${cards.length} cards`);
+      
+      // Count boost/penalize/pass/removed for this filter
+      let boosted = 0, penalized = 0, passed = 0;
+      const removed = beforeCount - cards.length;
+      
+      for (const card of cards) {
+        const before = beforeScores.get(card.cardId) ?? 0;
+        if (card.score > before) boosted++;
+        else if (card.score < before) penalized++;
+        else passed++;
+      }
+      filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
+      
+      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
     }
 
     // Remove zero-score cards (hard filtered)
@@ -219,12 +281,31 @@ export class Pipeline extends ContentNavigator {
       generatedCount,
       this.filters.length,
       result.length,
-      topScores
+      topScores,
+      filterImpacts
     );
 
     // Toggle provenance logging (shows scoring history for top cards):
     logCardProvenance(result, 3);
 
+    // Capture run for debug API
+    try {
+      const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
+      const report = buildRunReport(
+        this.course?.getCourseID() || 'unknown',
+        courseName,
+        this.generator.name,
+        generatorSummaries,
+        generatedCount,
+        filterImpacts,
+        allCardsBeforeFiltering,
+        result
+      );
+      captureRun(report);
+    } catch (e) {
+      logger.debug(`[Pipeline] Failed to capture debug run: ${e}`);
+    }
+
     return result;
   }
 

package/src/core/navigators/PipelineAssembler.ts

@@ -1,14 +1,14 @@
 import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import { ContentNavigator, isGenerator, isFilter, Navigators } from './index';
+import { ContentNavigator, isGenerator, isFilter } from './index';
 import type { CardFilter } from './filters/types';
 import { WeightedFilter } from './filters/WeightedFilter';
 import type { CardGenerator } from './generators/types';
 import { Pipeline } from './Pipeline';
-import { DocType } from '../types/types-legacy';
 import { logger } from '../../util/logger';
 import type { CourseDBInterface } from '../interfaces/courseDB';
 import type { UserDBInterface } from '../interfaces/userDB';
 import CompositeGenerator from './generators/CompositeGenerator';
+import { createDefaultEloStrategy, createDefaultSrsStrategy } from './defaults';
 
 // ============================================================================
 // PIPELINE ASSEMBLER
@@ -103,13 +103,15 @@ export class PipelineAssembler {
       }
     }
 
-    // If no generator but filters exist, use default ELO generator
+    // If no generator but filters exist, use default ELO and SRS generators
     if (generatorStrategies.length === 0) {
       if (filterStrategies.length > 0) {
         logger.debug(
-          '[PipelineAssembler] No generator found, using default ELO with configured filters'
+          '[PipelineAssembler] No generator found, using default ELO and SRS with configured filters'
         );
-        generatorStrategies.push(this.makeDefaultEloStrategy(course.getCourseID()));
+        const courseId = course.getCourseID();
+        generatorStrategies.push(createDefaultEloStrategy(courseId));
+        generatorStrategies.push(createDefaultSrsStrategy(courseId));
       } else {
         warnings.push('No generator strategy found');
         return {
@@ -188,20 +190,4 @@ export class PipelineAssembler {
       warnings,
     };
   }
-
-  /**
-   * Creates a default ELO generator strategy.
-   * Used when filters are configured but no generator is specified.
-   */
-  private makeDefaultEloStrategy(courseId: string): ContentNavigationStrategyData {
-    return {
-      _id: 'NAVIGATION_STRATEGY-ELO-default',
-      course: courseId,
-      docType: DocType.NAVIGATION_STRATEGY,
-      name: 'ELO (default)',
-      description: 'Default ELO-based generator',
-      implementingClass: Navigators.ELO,
-      serializedData: '',
-    };
-  }
 }