@vue-skuilder/db 0.1.23 → 0.1.24

package/docs/todo-strategy-authoring.md

@@ -53,7 +53,6 @@ interface HierarchyConfig {
   prerequisites: {
     [tagId: string]: TagPrerequisite[];
   };
-  delegateStrategy?: string;  // default: "elo"
 }
 
 interface TagPrerequisite {
@@ -75,8 +74,7 @@ interface TagPrerequisite {
     "blends": [
       { "tag": "cvc-words", "masteryThreshold": { "minCount": 20 } }
     ]
-  },
-  "delegateStrategy": "elo"
+  }
 }
 ```
 
@@ -99,7 +97,6 @@ interface InterferenceConfig {
     minElapsedDays?: number;
   };
   defaultDecay?: number;
-  delegateStrategy?: string;
 }
 
 interface InterferenceGroup {
@@ -137,7 +134,6 @@ interface RelativePriorityConfig {
   defaultPriority?: number;
   combineMode?: 'max' | 'average' | 'min';
   priorityInfluence?: number;
-  delegateStrategy?: string;
 }
 ```
 
@@ -398,4 +394,10 @@ The NavigationStrategy editor is accessible in:
 - `packages/db/src/core/navigators/hierarchyDefinition.ts` — Config interface reference
 - `packages/db/src/core/navigators/interferenceMitigator.ts` — Config interface reference
 - `packages/db/src/core/navigators/relativePriority.ts` — Config interface reference
-- `packages/edit-ui/src/components/NavigationStrategy/` — UI components (all forms)
+- `packages/edit-ui/src/components/NavigationStrategy/` — UI components (all forms)
+
+## Related Documentation
+
+- `navigators-architecture.md` — Pipeline architecture and strategy framework
+- `future-orchestration-vision.md` — Long-term adaptive strategy vision
+- `devlog/1032-orchestrator` — Evolutionary orchestration implementation details

package/package.json

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

package/src/core/index.ts

@@ -4,7 +4,9 @@ export * from './interfaces';
 export * from './types/types-legacy';
 export * from './types/user';
 export * from './types/strategyState';
+export * from './types/userOutcome';
 export * from '../util/Loggable';
 export * from './util';
 export * from './navigators';
 export * from './bulkImport';
+export * from './orchestration';

package/src/core/interfaces/contentSource.ts

@@ -4,6 +4,7 @@ import { StudentClassroomDB } from '../../impl/couch/classroomDB';
 import { WeightedCard } from '../navigators';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
+import { OrchestrationContext } from '../orchestration';
 
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
@@ -72,6 +73,12 @@ export interface StudyContentSource {
    * @returns Cards sorted by score descending
    */
   getWeightedCards(limit: number): Promise<WeightedCard[]>;
+
+  /**
+   * Get the orchestration context for this source.
+   * Used for recording learning outcomes.
+   */
+  getOrchestrationContext?(): Promise<OrchestrationContext>;
 }
 // #endregion docs_StudyContentSource
 

package/src/core/interfaces/userDB.ts

@@ -7,6 +7,7 @@ import {
 import { CourseElo, Status } from '@vue-skuilder/common';
 import { Moment } from 'moment';
 import { CardHistory, CardRecord, QualifiedCardID } from '../types/types-legacy';
+import { UserOutcomeRecord } from '../types/userOutcome';
 import { UserConfig } from '../types/user';
 import { DocumentUpdater } from '@db/study';
 
@@ -164,6 +165,11 @@ export interface UserDBWriter extends DocumentUpdater {
    * @param strategyKey - Unique key identifying the strategy (typically class name)
    */
   deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
+
+  /**
+   * Record a user learning outcome for evolutionary orchestration.
+   */
+  putUserOutcome(record: UserOutcomeRecord): Promise<void>;
 }
 
 /**

package/src/core/navigators/Pipeline.ts

@@ -6,6 +6,7 @@ import type { WeightedCard } from './index';
 import type { CardFilter, FilterContext } from './filters/types';
 import type { CardGenerator, GeneratorContext } from './generators/types';
 import { logger } from '../../util/logger';
+import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
 
 // ============================================================================
 // PIPELINE LOGGING HELPERS
@@ -273,10 +274,14 @@ export class Pipeline extends ContentNavigator {
       logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
     }
 
+    // Initialize orchestration context (used for evolutionary weighting)
+    const orchestration = await createOrchestrationContext(this.user!, this.course!);
+
     return {
       user: this.user!,
       course: this.course!,
       userElo,
+      orchestration,
     };
   }
 
@@ -286,4 +291,45 @@ export class Pipeline extends ContentNavigator {
   getCourseID(): string {
     return this.course!.getCourseID();
   }
+
+  /**
+   * Get orchestration context for outcome recording.
+   */
+  async getOrchestrationContext(): Promise<OrchestrationContext> {
+    return createOrchestrationContext(this.user!, this.course!);
+  }
+
+  /**
+   * Get IDs of all strategies in this pipeline.
+   * Used to record which strategies contributed to an outcome.
+   */
+  getStrategyIds(): string[] {
+    const ids: string[] = [];
+
+    const extractId = (obj: any): string | null => {
+      // Check for strategyId property (ContentNavigator, WeightedFilter)
+      if (obj.strategyId) return obj.strategyId;
+      return null;
+    };
+
+    // Generator(s)
+    const genId = extractId(this.generator);
+    if (genId) ids.push(genId);
+
+    // Inspect CompositeGenerator children (accessing private field via cast)
+    if ((this.generator as any).generators && Array.isArray((this.generator as any).generators)) {
+      (this.generator as any).generators.forEach((g: any) => {
+        const subId = extractId(g);
+        if (subId) ids.push(subId);
+      });
+    }
+
+    // Filters
+    for (const filter of this.filters) {
+      const fId = extractId(filter);
+      if (fId) ids.push(fId);
+    }
+
+    return [...new Set(ids)];
+  }
 }

package/src/core/navigators/PipelineAssembler.ts

@@ -1,6 +1,7 @@
 import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
 import { ContentNavigator, isGenerator, isFilter, Navigators } 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';
@@ -149,7 +150,19 @@ export class PipelineAssembler {
         const nav = await ContentNavigator.create(user, course, filterStrategy);
         // The navigator implements CardFilter
         if ('transform' in nav && typeof nav.transform === 'function') {
-          filters.push(nav as unknown as CardFilter);
+          let filter = nav as unknown as CardFilter;
+
+          // Apply evolutionary weighting wrapper if configured
+          if (filterStrategy.learnable) {
+            filter = new WeightedFilter(
+              filter,
+              filterStrategy.learnable,
+              filterStrategy.staticWeight,
+              filterStrategy._id
+            );
+          }
+
+          filters.push(filter);
           logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
         } else {
           warnings.push(

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

@@ -0,0 +1,141 @@
+import { CardFilter, FilterContext } from './types';
+import { WeightedCard } from '../index';
+import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNavigationStrategy';
+
+/**
+ * Wraps a CardFilter to apply evolutionary weighting to its effects.
+ *
+ * If a filter applies a multiplier M (score * M), and the strategy has
+ * an effective weight W, the final multiplier becomes M^W.
+ *
+ * - W=1.0: Original behavior
+ * - W>1.0: Amplifies the filter's opinion (stronger boost/penalty)
+ * - W<1.0: Dampens the filter's opinion (weaker boost/penalty)
+ * - W=0.0: Nullifies the filter (identity)
+ *
+ * This wrapper handles the math of scaling the filter's impact and updating
+ * the provenance trail with the effective weight used.
+ */
+export class WeightedFilter implements CardFilter {
+  public name: string;
+  private inner: CardFilter;
+  private learnable: LearnableWeight;
+  private staticWeight: boolean;
+  private strategyId?: string;
+
+  constructor(
+    inner: CardFilter,
+    learnable: LearnableWeight = DEFAULT_LEARNABLE_WEIGHT,
+    staticWeight: boolean = false,
+    strategyId?: string
+  ) {
+    this.inner = inner;
+    this.name = inner.name;
+    this.learnable = learnable;
+    this.staticWeight = staticWeight;
+    this.strategyId = strategyId;
+  }
+
+  /**
+   * Apply the inner filter, then scale its effect by the configured weight.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    // ========================================================================
+    // 1. DETERMINE EFFECTIVE WEIGHT
+    // ========================================================================
+    
+    // Determine effective weight using orchestration context if available
+    let effectiveWeight = this.learnable.weight;
+    let deviation: number | undefined;
+
+    if (!this.staticWeight && context.orchestration) {
+      // ContentNavigator instances have a strategyId property (protected/private)
+      // We assume inner filter is a ContentNavigator or has a strategyId property.
+      // Fallback to name if not present.
+      const strategyId = this.strategyId || (this.inner as any).strategyId || this.name;
+      effectiveWeight = context.orchestration.getEffectiveWeight(strategyId, this.learnable);
+      deviation = context.orchestration.getDeviation(strategyId);
+    }
+
+    // Optimization: If weight is 1.0, the scaling is an identity operation.
+    // Just run the inner filter directly.
+    if (Math.abs(effectiveWeight - 1.0) < 0.001) {
+      return this.inner.transform(cards, context);
+    }
+
+    // ========================================================================
+    // 2. CAPTURE STATE BEFORE FILTER
+    // ========================================================================
+    
+    // We need original scores to calculate what the filter did (M = new/old)
+    const originalScores = new Map<string, number>();
+    for (const card of cards) {
+      originalScores.set(card.cardId, card.score);
+    }
+
+    // ========================================================================
+    // 3. RUN INNER FILTER
+    // ========================================================================
+    
+    const transformedCards = await this.inner.transform(cards, context);
+
+    // ========================================================================
+    // 4. APPLY WEIGHT SCALING
+    // ========================================================================
+    
+    return transformedCards.map((card) => {
+      const originalScore = originalScores.get(card.cardId);
+
+      // Edge cases where we can't or shouldn't scale:
+      // - Original score missing (shouldn't happen)
+      // - Original score 0 (was already excluded)
+      // - New score 0 (filter excluded it / vetoed) - we treat vetoes as absolute
+      if (originalScore === undefined || originalScore === 0 || card.score === 0) {
+        return card;
+      }
+
+      // Calculate raw effect multiplier: M = new / old
+      const rawEffect = card.score / originalScore;
+
+      // If filter didn't change this card, nothing to scale
+      if (Math.abs(rawEffect - 1.0) < 0.0001) {
+        return card;
+      }
+
+      // Apply weight: scaled = M ^ W
+      // Example: 0.5 penalty ^ 2.0 weight = 0.25 (stronger penalty)
+      // Example: 0.5 penalty ^ 0.5 weight = 0.707 (weaker penalty)
+      const weightedEffect = Math.pow(rawEffect, effectiveWeight);
+      const newScore = originalScore * weightedEffect;
+
+      // Update provenance
+      // The inner filter just added the last entry. We need to update it
+      // to reflect the weighted score and record the effective weight.
+      const lastProvIndex = card.provenance.length - 1;
+      const lastProv = card.provenance[lastProvIndex];
+
+      if (lastProv) {
+        const updatedProvenance = [...card.provenance];
+        updatedProvenance[lastProvIndex] = {
+          ...lastProv,
+          score: newScore,
+          effectiveWeight: effectiveWeight,
+          deviation: deviation,
+          // We can optionally append to the reason, but the structured field is key
+        };
+
+        return {
+          ...card,
+          score: newScore,
+          provenance: updatedProvenance,
+        };
+      }
+
+      // Fallback if no provenance found (rare)
+      return {
+        ...card,
+        score: newScore,
+      };
+    });
+  }
+}

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

@@ -1,6 +1,7 @@
 import type { WeightedCard } from '../index';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
+import type { OrchestrationContext } from '../../orchestration';
 
 // ============================================================================
 // CARD FILTER INTERFACE
@@ -40,6 +41,9 @@ export interface FilterContext {
   /** User's global ELO score for this course */
   userElo: number;
 
+  /** Orchestration context for evolutionary weighting */
+  orchestration?: OrchestrationContext;
+
   // Future extensions:
   // - hydrated tags for all cards (batch lookup)
   // - user's tag-level ELO data

package/src/core/navigators/generators/CompositeGenerator.ts

@@ -113,20 +113,45 @@ export default class CompositeGenerator extends ContentNavigator implements Card
       this.generators.map((g) => g.getWeightedCards(limit, context))
     );
 
-    // Group by cardId
-    const byCardId = new Map<string, WeightedCard[]>();
-    for (const cards of results) {
+    // Group by cardId, tracking the weight of the generator that produced each instance
+    type WeightedResult = { card: WeightedCard; weight: number };
+    const byCardId = new Map<string, WeightedResult[]>();
+
+    results.forEach((cards, index) => {
+      // Access learnable weight if available
+      const gen = this.generators[index] as unknown as ContentNavigator;
+
+      // Determine effective weight
+      let weight = gen.learnable?.weight ?? 1.0;
+      let deviation: number | undefined;
+
+      if (gen.learnable && !gen.staticWeight && context.orchestration) {
+        // Access strategyId (protected field) via type assertion
+        const strategyId = (gen as any).strategyId;
+        if (strategyId) {
+          weight = context.orchestration.getEffectiveWeight(strategyId, gen.learnable);
+          deviation = context.orchestration.getDeviation(strategyId);
+        }
+      }
+
       for (const card of cards) {
+        // Record effective weight in provenance for transparency
+        if (card.provenance.length > 0) {
+          card.provenance[0].effectiveWeight = weight;
+          card.provenance[0].deviation = deviation;
+        }
+
         const existing = byCardId.get(card.cardId) || [];
-        existing.push(card);
+        existing.push({ card, weight });
         byCardId.set(card.cardId, existing);
       }
-    }
+    });
 
     // Aggregate scores
     const merged: WeightedCard[] = [];
-    for (const [, cards] of byCardId) {
-      const aggregatedScore = this.aggregateScores(cards);
+    for (const [, items] of byCardId) {
+      const cards = items.map((i) => i.card);
+      const aggregatedScore = this.aggregateScores(items);
       const finalScore = Math.min(1.0, aggregatedScore); // Clamp to [0, 1]
 
       // Merge provenance from all generators that produced this card
@@ -138,7 +163,7 @@ export default class CompositeGenerator extends ContentNavigator implements Card
         finalScore > initialScore ? 'boosted' : finalScore < initialScore ? 'penalized' : 'passed';
 
       // Build reason explaining the aggregation
-      const reason = this.buildAggregationReason(cards, finalScore);
+      const reason = this.buildAggregationReason(items, finalScore);
 
       // Append composite provenance entry
       merged.push({
@@ -165,12 +190,18 @@ export default class CompositeGenerator extends ContentNavigator implements Card
   /**
    * Build human-readable reason for score aggregation.
    */
-  private buildAggregationReason(cards: WeightedCard[], finalScore: number): string {
+  private buildAggregationReason(
+    items: { card: WeightedCard; weight: number }[],
+    finalScore: number
+  ): string {
+    const cards = items.map((i) => i.card);
     const count = cards.length;
     const scores = cards.map((c) => c.score.toFixed(2)).join(', ');
 
     if (count === 1) {
-      return `Single generator, score ${finalScore.toFixed(2)}`;
+      const weightMsg =
+        Math.abs(items[0].weight - 1.0) > 0.001 ? ` (w=${items[0].weight.toFixed(2)})` : '';
+      return `Single generator, score ${finalScore.toFixed(2)}${weightMsg}`;
     }
 
     const strategies = cards.map((c) => c.provenance[0]?.strategy || 'unknown').join(', ');
@@ -180,12 +211,16 @@ export default class CompositeGenerator extends ContentNavigator implements Card
         return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
 
       case AggregationMode.AVERAGE:
-        return `Average of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+        return `Weighted Avg of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
 
       case AggregationMode.FREQUENCY_BOOST: {
-        const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
+        // Recalculate basic weighted avg for display
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
         const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
-        return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
+        return `Frequency boost from ${count} generators (${strategies}): w-avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
       }
 
       default:
@@ -196,19 +231,26 @@ export default class CompositeGenerator extends ContentNavigator implements Card
   /**
    * Aggregate scores from multiple generators for the same card.
    */
-  private aggregateScores(cards: WeightedCard[]): number {
-    const scores = cards.map((c) => c.score);
+  private aggregateScores(items: { card: WeightedCard; weight: number }[]): number {
+    const scores = items.map((i) => i.card.score);
 
     switch (this.aggregationMode) {
       case AggregationMode.MAX:
         return Math.max(...scores);
 
-      case AggregationMode.AVERAGE:
-        return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+      case AggregationMode.AVERAGE: {
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        if (totalWeight === 0) return 0;
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        return weightedSum / totalWeight;
+      }
 
       case AggregationMode.FREQUENCY_BOOST: {
-        const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
-        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
+        const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
+        const weightedSum = items.reduce((sum, i) => sum + i.card.score * i.weight, 0);
+        const avg = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
+        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (items.length - 1);
         return avg * frequencyBoost;
       }
 

package/src/core/navigators/generators/types.ts

@@ -1,6 +1,7 @@
 import type { WeightedCard } from '../index';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
+import type { OrchestrationContext } from '../../orchestration';
 
 // ============================================================================
 // CARD GENERATOR INTERFACE
@@ -34,6 +35,9 @@ export interface GeneratorContext {
   /** User's global ELO score for this course */
   userElo: number;
 
+  /** Orchestration context for evolutionary weighting */
+  orchestration?: OrchestrationContext;
+
   // Future extensions:
   // - user's tag-level ELO data
   // - course config