@vue-skuilder/db 0.1.17 → 0.1.20

package/docs/navigators-architecture.md

@@ -0,0 +1,370 @@
+# Navigation Strategy Architecture
+
+## Overview
+
+The navigation strategy system selects and scores cards for study sessions. It uses a
+**Pipeline architecture** where generators produce candidates and filters transform scores.
+
+## Core Concepts
+
+### WeightedCard
+
+A card with a suitability score, audit trail, and pre-fetched data:
+
+```typescript
+interface WeightedCard {
+  cardId: string;
+  courseId: string;
+  score: number;              // 0-1 suitability score
+  provenance: StrategyContribution[];  // Audit trail
+  tags?: string[];            // Pre-fetched tags (hydrated by Pipeline)
+}
+
+interface StrategyContribution {
+  strategy: string;           // Type: 'elo', 'srs', 'hierarchyDefinition'
+  strategyName: string;       // Human-readable: "ELO (default)"
+  strategyId: string;         // Document ID: 'NAVIGATION_STRATEGY-ELO-default'
+  action: 'generated' | 'passed' | 'boosted' | 'penalized';
+  score: number;              // Score after this strategy
+  reason: string;             // Human-readable explanation
+}
+```
+
+### CardGenerator
+
+Produces candidate cards with initial scores:
+
+```typescript
+interface CardGenerator {
+  name: string;
+  getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
+}
+```
+
+**Implementations:**
+- `ELONavigator` — New cards scored by ELO proximity to user skill
+- `SRSNavigator` — Review cards scored by overdueness and interval recency
+- `HardcodedOrderNavigator` — Fixed sequence defined by course author
+- `CompositeGenerator` — Merges multiple generators with frequency boost
+
+### CardFilter
+
+Transforms card scores (pure function, no side effects):
+
+```typescript
+interface CardFilter {
+  name: string;
+  transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
+}
+```
+
+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, data hydration, and filters:
+
+```typescript
+class Pipeline {
+  constructor(
+    generator: CardGenerator,
+    filters: CardFilter[],
+    user: UserDBInterface,
+    course: CourseDBInterface
+  )
+
+  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);
+  }
+}
+```
+
+**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:
+
+```typescript
+const assembler = new PipelineAssembler();
+const { pipeline, warnings } = await assembler.assemble({
+  strategies: allStrategies,
+  user,
+  course,
+});
+```
+
+Assembly logic:
+1. Separate strategies into generators and filters by `NavigatorRole`
+2. Instantiate generators — wrap multiple in `CompositeGenerator`
+3. Instantiate filters — sorted alphabetically for determinism
+4. Return `Pipeline(generator, filters)`
+
+If no strategies are configured, `courseDB.createNavigator()` returns a default pipeline:
+```typescript
+Pipeline(
+  CompositeGenerator([ELONavigator, SRSNavigator]),
+  [eloDistanceFilter]
+)
+```
+
+## Score Semantics
+
+| Score | Meaning |
+|-------|---------|
+| 1.0 | Fully suitable |
+| 0.5 | Neutral |
+| 0.0 | Exclude (hard filter) |
+| 0.x | Proportional suitability |
+
+**All filters are multipliers.** This means:
+- Filter order doesn't affect final scores (multiplication is commutative)
+- Score 0 from any filter excludes the card
+- Filters are applied alphabetically for determinism
+
+## Provenance Tracking
+
+Each card's provenance shows how it was scored:
+
+```typescript
+provenance: [
+  {
+    strategy: 'elo',
+    strategyName: 'ELO (default)',
+    strategyId: 'NAVIGATION_STRATEGY-ELO-default',
+    action: 'generated',
+    score: 0.85,
+    reason: 'ELO distance 75 (card: 1025, user: 1100), new card'
+  },
+  {
+    strategy: 'hierarchyDefinition',
+    strategyName: 'Hierarchy: Phonics Basics',
+    strategyId: 'NAVIGATION_STRATEGY-hierarchy-phonics',
+    action: 'passed',
+    score: 0.85,
+    reason: 'Prerequisites met, tags: letter-sounds'
+  },
+  {
+    strategy: 'eloDistance',
+    strategyName: 'ELO Distance Filter',
+    strategyId: 'ELO_DISTANCE_FILTER',
+    action: 'penalized',
+    score: 0.72,
+    reason: 'ELO distance 150 (card: 1150, user: 1000) → 0.85x'
+  }
+]
+```
+
+Use `getCardOrigin(card)` to extract 'new', 'review', or 'failed' from provenance.
+
+## Creating New Strategies
+
+### Generator
+
+```typescript
+class MyGenerator extends ContentNavigator implements CardGenerator {
+  name = 'My Generator';
+
+  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(),
+      score: this.computeScore(c),
+      provenance: [{
+        strategy: 'myGenerator',
+        strategyName: this.name,
+        strategyId: this.strategyId || 'MY_GENERATOR',
+        action: 'generated',
+        score: this.computeScore(c),
+        reason: 'Explanation here, new card'
+      }]
+    }));
+  }
+
+  // Legacy methods - stub or implement for backward compat
+  async getNewCards() { return []; }
+  async getPendingReviews() { return []; }
+}
+```
+
+Register in `NavigatorRoles` as `NavigatorRole.GENERATOR`.
+
+### Filter
+
+```typescript
+class MyFilter extends ContentNavigator implements CardFilter {
+  name = 'My Filter';
+
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    return cards.map(card => {
+      const multiplier = this.computeMultiplier(card, context);
+      const newScore = card.score * multiplier;
+      const action = multiplier < 1 ? 'penalized' : multiplier > 1 ? 'boosted' : 'passed';
+      
+      return {
+        ...card,
+        score: newScore,
+        provenance: [...card.provenance, {
+          strategy: 'myFilter',
+          strategyName: this.name,
+          strategyId: this.strategyId || 'MY_FILTER',
+          action,
+          score: newScore,
+          reason: 'Explanation here'
+        }]
+      };
+    });
+  }
+
+  // Legacy methods - 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 |
+|------|---------|
+| `core/navigators/index.ts` | `ContentNavigator`, `WeightedCard`, `NavigatorRole` |
+| `core/navigators/generators/types.ts` | `CardGenerator`, `GeneratorContext` |
+| `core/navigators/filters/types.ts` | `CardFilter`, `FilterContext` |
+| `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/hardcodedOrder.ts` | Fixed-order generator |
+| `core/navigators/hierarchyDefinition.ts` | Prerequisite 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 Documentation
+
+- `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/docs/todo-evolutionary-orchestration.md

@@ -0,0 +1,310 @@
+# TODO: Evolutionary Orchestration Vision
+
+## Status: FOUNDATIONAL WORK COMPLETE, ORCHESTRATION NOT STARTED
+
+> **Prerequisite:** `packages/db/docs/todo-naive-orchestration.md` — Pipeline assembly must be
+> working before evolutionary selection can be layered on top. This document describes the
+> "grander vision"; naive orchestration is the foundation.
+
+This document tracks progress toward the "grander vision" of dynamic orchestration with
+evolutionary pressures, as outlined in `u.3.strategic-nuggets.md`.
+
+## The Vision (Summary)
+
+A self-improving courseware system where:
+
+1. **N strategies exist** — Each a hypothesis about effective content sequencing
+2. **M users exist** — Each with learning goals and measurable outcomes
+3. **Multi-arm bandit selection** — Strategies are applied based on confidence in their utility
+4. **Evolutionary pressure** — Effective strategies propagate, ineffective ones decay
+5. **Self-healing content** — System identifies barriers and incentivizes remediation
+
+---
+
+## Progress Assessment
+
+### ✅ COMPLETE: Strategy Infrastructure
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `WeightedCard` API | ✅ Done | Unified scored candidate model |
+| `ContentNavigator` base class | ✅ Done | Extensible strategy framework |
+| Delegate pattern composition | ✅ Done | Strategies can wrap/chain |
+| `HierarchyDefinition` strategy | ✅ Done | Prerequisite gating |
+| `InterferenceMitigator` strategy | ✅ Done | Confusable concept separation |
+| `RelativePriority` strategy | ✅ Done | Utility-based content ordering |
+| `SessionController` integration | ✅ Done | `getWeightedCards()` is live |
+| Pipeline assembly | ❌ Not done | See `todo-naive-orchestration.md` |
+
+**What this enables:**
+- Multiple strategies can coexist and be configured per-course
+- Strategies return graded suitability scores (0-1), not just binary include/exclude
+- Composition allows layering strategies: `Priority(Interference(Hierarchy(ELO)))`
+
+**What's missing for basic operation:**
+- No pipeline configuration in CourseConfig (`navigationPipeline` field)
+- No assembly logic to chain configured strategies
+- Currently falls back to hard-coded ELO navigator
+
+---
+
+### 🟡 PARTIAL: Strategy State & Context
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Read user ELO (global + per-tag) | ✅ Done | Via `CourseRegistration.elo` |
+| Read user history | ✅ Done | `getSeenCards()`, `getPendingReviews()` |
+| Write strategy-specific state | ❌ Not done | See `todo-strategy-state-storage.md` |
+| Temporal tracking | ❌ Not done | "When was tag X last introduced?" |
+
+**Gap for evolutionary vision:**
+- Strategies cannot yet persist their own learning/state
+- No mechanism for tracking strategy effectiveness over time
+
+---
+
+### ❌ NOT STARTED: Multi-Arm Bandit Selection
+
+The core orchestration logic described in the vision:
+
+```
+each of N strategies divides into cohorts via some hashId collision metric
+  eg: h(strategyHash + slowRotationSalt) xor userHash 
+      if resultant Ones are < utilityConfidence percent of total bits, 
+      then include the strategy for the user
+```
+
+**What's needed:**
+
+1. **Strategy Registry** — Central list of available strategies with metadata
+2. **Utility Confidence** — Per-strategy confidence score (0-1)
+3. **Cohort Assignment** — Deterministic but rotatable user-to-strategy mapping
+4. **Salt Rotation** — Periodic rotation to prevent user lock-in
+5. **Outcome Measurement** — Track goal achievement per cohort
+
+**Proposed architecture:**
+
+```typescript
+interface StrategyRegistryEntry {
+  strategyId: string;
+  strategyType: string;
+  config: unknown;
+  
+  // Evolutionary metadata
+  utilityConfidence: number;      // 0-1, probability of usefulness
+  createdAt: string;
+  lastMeasuredAt: string;
+  cohortSalt: string;             // Rotated periodically
+  
+  // Outcome tracking
+  metrics: {
+    usersExposed: number;
+    goalAchievementRate: number;
+    engagementScore: number;
+    progressRate: number;
+  };
+}
+
+interface Orchestrator {
+  // Determine which strategies apply to this user for this session
+  selectStrategies(userId: string, courseId: string): Promise<StrategyRegistryEntry[]>;
+  
+  // Record outcome for evolutionary learning
+  recordOutcome(userId: string, strategyIds: string[], outcome: Outcome): Promise<void>;
+  
+  // Rotate cohort assignments
+  rotateSalt(): Promise<void>;
+  
+  // Prune ineffective strategies
+  pruneStrategies(minConfidence: number): Promise<void>;
+}
+```
+
+---
+
+### ❌ NOT STARTED: Parameterizable / Programmable Strategies
+
+The vision describes:
+
+```
+would like to extend into parameterizable / programmable strategies. 
+eg, should be able to specify deps like:
+  `grade-{n}` & `geometry` -> `grade-{n+1}` & `geometry`
+```
+
+**What's needed:**
+
+1. **Template syntax** — Pattern matching for tag relationships
+2. **Variable binding** — Extract and apply variables in prerequisite rules
+3. **Rule engine** — Evaluate parameterized rules against user state
+
+**Example:**
+```typescript
+interface ParameterizedPrerequisite {
+  pattern: "grade-{n} & {subject}";
+  implies: "grade-{n+1} & {subject}";
+  constraints: {
+    n: { type: "number", min: 1, max: 12 },
+    subject: { type: "tag-category", category: "academic-subject" }
+  };
+}
+```
+
+---
+
+### ❌ NOT STARTED: Self-Healing Content
+
+The meta-consideration from the vision:
+
+```
+- identifying learning 'barriers' where substantive portion of cohort gets stuck or abandons
+- surfacing that info in a useful way
+- author aims to diagnose and remedy by providing intermediate content
+```
+
+**What's needed:**
+
+1. **Barrier Detection** — Identify cards/tags where many users get stuck
+2. **Cohort Analysis** — Compare progress across strategy cohorts
+3. **Alert System** — Surface barriers to authors
+4. **Intervention Hooks** — Enable targeted content insertion
+5. **Feedback Loop** — Measure intervention effectiveness
+
+**Signals for barrier detection:**
+- High failure rate on specific cards
+- Long dwell time before mastery
+- Drop-off (users abandon course at specific points)
+- ELO stagnation on specific tags
+
+---
+
+## Roadmap to Full Vision
+
+### Phase A: Foundation (COMPLETE ✅)
+
+- [x] WeightedCard API
+- [x] ContentNavigator framework
+- [x] Core strategies (Hierarchy, Interference, RelativePriority)
+- [x] SessionController integration
+
+### Phase B: Strategy Ecosystem (IN PROGRESS 🟡)
+
+- [ ] SRS as ContentNavigator (`todo-srs-navigator.md`)
+- [ ] Strategy authoring tools (`todo-strategy-authoring.md`)
+- [ ] Strategy state storage (`todo-strategy-state-storage.md`)
+- [ ] Provenance/audit trail (`todo-provenance.md`)
+
+### Phase C: Measurement Infrastructure (NOT STARTED)
+
+- [ ] Define "learning outcome" metrics
+- [ ] Instrument strategy usage per user
+- [ ] Track outcome-to-strategy correlation
+- [ ] Build cohort comparison views
+
+### Phase D: Multi-Arm Bandit Orchestrator (NOT STARTED)
+
+- [ ] Strategy registry with utility confidence
+- [ ] Cohort assignment algorithm
+- [ ] Salt rotation mechanism
+- [ ] Confidence update rules (Bayesian or frequentist)
+- [ ] Orchestrator integration with SessionController
+
+### Phase E: Evolutionary Pressure (NOT STARTED)
+
+- [ ] Strategy creation incentives
+- [ ] Automatic strategy pruning
+- [ ] Strategy mutation/variation generation
+- [ ] A/B testing framework
+
+### Phase F: Self-Healing (NOT STARTED)
+
+- [ ] Barrier detection pipeline
+- [ ] Author alerting system
+- [ ] Intervention recommendation engine
+- [ ] Content gap analysis
+
+### Phase G: Programmable Strategies (NOT STARTED)
+
+- [ ] Template syntax design
+- [ ] Rule engine implementation
+- [ ] Variable binding in prerequisites
+- [ ] Cross-course strategy generalization
+
+---
+
+## Key Design Decisions Ahead
+
+### 1. Centralized vs Decentralized Orchestration
+
+**Option A: Central Orchestrator Service**
+- Single service decides strategy application
+- Cleaner cohort tracking
+- Requires backend infrastructure
+
+**Option B: Client-Side Orchestration**
+- Each client computes its own strategy set
+- Works offline
+- Harder to track cohorts
+
+**Recommendation:** Hybrid — client computes from synced registry, outcomes reported to backend.
+
+### 2. Confidence Update Mechanism
+
+**Option A: Frequentist (Simple)**
+- Track success/failure counts
+- Confidence = success_rate with smoothing
+- Easy to implement
+
+**Option B: Bayesian (Principled)**
+- Prior belief + observed evidence
+- Thompson sampling for exploration/exploitation
+- More complex but theoretically sound
+
+**Recommendation:** Start with frequentist, migrate to Bayesian if needed.
+
+### 3. Strategy Granularity
+
+**Question:** What counts as "a strategy" for evolutionary purposes?
+
+- A specific `HierarchyDefinition` config? (Fine-grained)
+- The `HierarchyDefinition` approach in general? (Coarse-grained)
+- A specific prerequisite rule within a hierarchy? (Very fine-grained)
+
+**Recommendation:** Start coarse (strategy type + major config), add granularity as measurement matures.
+
+### 4. Outcome Attribution
+
+**Question:** If a user is exposed to multiple strategies, how do we attribute outcomes?
+
+- All strategies get credit/blame equally?
+- Weight by score contribution?
+- Require isolated A/B cells?
+
+**Recommendation:** Start with equal attribution, instrument for isolated testing later.
+
+---
+
+## Related Documents
+
+- `u.3.strategic-nuggets.md` — Original vision statement
+- `todo-srs-navigator.md` — SRS migration
+- `todo-strategy-authoring.md` — Authoring tools
+- `todo-strategy-state-storage.md` — State persistence
+- `todo-provenance.md` — Audit trail for transparency
+- `a.2.plan.md` — Detailed implementation plan
+- `a.3.todo.md` — Task tracking
+- `packages/db/docs/navigators-architecture.md` — Technical architecture
+
+---
+
+## Summary
+
+**Where we are:** Solid foundation. Strategies exist, compose, return scores, and are integrated
+with SessionController. The infrastructure supports the vision.
+
+**What's next:** Build the measurement and orchestration layers. The strategies can now *exist*;
+we need to make them *compete* and *evolve*.
+
+**The gap:** The evolutionary pressure mechanisms (multi-arm bandit selection, outcome measurement,
+confidence updates, self-healing) are not yet implemented. This is where the "magic" of the
+vision lives, and it's entirely ahead of us.