@vue-skuilder/db 0.1.23 → 0.1.24

package/src/courseConfigRegistration.ts

@@ -265,6 +265,113 @@ export function registerQuestionType(
   return true;
 }
 
+/**
+ * Remove a data shape from the course config
+ * @returns true if the data shape was removed, false if it wasn't found
+ */
+export function removeDataShape(
+  dataShapeName: string,
+  courseConfig: CourseConfig
+): boolean {
+  const index = courseConfig.dataShapes.findIndex((ds) => ds.name === dataShapeName);
+
+  if (index === -1) {
+    logger.info(`DataShape '${dataShapeName}' not found in course config`);
+    return false;
+  }
+
+  // Remove the data shape
+  courseConfig.dataShapes.splice(index, 1);
+
+  // Also remove references from any question types
+  courseConfig.questionTypes.forEach((qt) => {
+    const dsIndex = qt.dataShapeList.indexOf(dataShapeName);
+    if (dsIndex !== -1) {
+      qt.dataShapeList.splice(dsIndex, 1);
+    }
+  });
+
+  logger.info(`Removed DataShape: ${dataShapeName}`);
+  return true;
+}
+
+/**
+ * Remove a question type from the course config
+ * @returns true if the question type was removed, false if it wasn't found
+ */
+export function removeQuestionType(
+  questionTypeName: string,
+  courseConfig: CourseConfig
+): boolean {
+  const index = courseConfig.questionTypes.findIndex((qt) => qt.name === questionTypeName);
+
+  if (index === -1) {
+    logger.info(`QuestionType '${questionTypeName}' not found in course config`);
+    return false;
+  }
+
+  // Remove the question type
+  courseConfig.questionTypes.splice(index, 1);
+
+  // Also remove references from data shapes
+  courseConfig.dataShapes.forEach((ds) => {
+    const qtIndex = ds.questionTypes.indexOf(questionTypeName);
+    if (qtIndex !== -1) {
+      ds.questionTypes.splice(qtIndex, 1);
+    }
+  });
+
+  logger.info(`Removed QuestionType: ${questionTypeName}`);
+  return true;
+}
+
+/**
+ * Remove data shapes and question types from course config and persist to database
+ */
+export async function removeCustomQuestionTypes(
+  dataShapeNames: string[],
+  questionTypeNames: string[],
+  courseConfig: CourseConfig,
+  courseDB: CourseDBInterface
+): Promise<{ success: boolean; removedCount: number; errorMessage?: string }> {
+  try {
+    logger.info('Beginning custom question removal');
+    logger.info(`Removing ${dataShapeNames.length} data shapes and ${questionTypeNames.length} question types`);
+
+    let removedCount = 0;
+
+    // Remove question types first (they reference data shapes)
+    for (const qtName of questionTypeNames) {
+      if (removeQuestionType(qtName, courseConfig)) {
+        removedCount++;
+      }
+    }
+
+    // Then remove data shapes
+    for (const dsName of dataShapeNames) {
+      if (removeDataShape(dsName, courseConfig)) {
+        removedCount++;
+      }
+    }
+
+    // Update the course config in the database
+    logger.info('Updating course configuration...');
+    const updateResult = await courseDB.updateCourseConfig(courseConfig);
+
+    if (!updateResult.ok) {
+      throw new Error(`Failed to update course config: ${JSON.stringify(updateResult)}`);
+    }
+
+    logger.info(`Custom question removal complete: ${removedCount} items removed`);
+
+    return { success: true, removedCount };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`Custom question removal failed: ${errorMessage}`);
+    return { success: false, removedCount: 0, errorMessage };
+  }
+}
+
 /**
  * Register seed data for a question type
  *

package/src/factory.ts

@@ -4,6 +4,7 @@ import { DataLayerProvider } from './core/interfaces';
 import { BaseUser } from './impl/common';
 import { logger } from './util/logger';
 import { StaticCourseManifest } from './util/packer/types';
+import { initializeNavigatorRegistry } from './core/navigators';
 
 const NOT_SET = 'NOT_SET' as const;
 
@@ -50,6 +51,11 @@ export async function initializeDataLayer(config: DataLayerConfig): Promise<Data
     logger.warn('Data layer already initialized. Returning existing instance.');
     return dataLayerInstance;
   }
+
+  // Initialize the navigator registry before creating the data layer.
+  // This ensures all built-in navigators are available for pipeline assembly.
+  await initializeNavigatorRegistry();
+
   if (config.options.localStoragePrefix) {
     ENV.LOCAL_STORAGE_PREFIX = config.options.localStoragePrefix;
   }

package/src/impl/common/BaseUserDB.ts

@@ -20,6 +20,7 @@ import {
 } from '@db/core/types/user';
 import { DocumentUpdater } from '@db/study';
 import { CardHistory, CardRecord } from '../../core/types/types-legacy';
+import { UserOutcomeRecord } from '../../core/types/userOutcome';
 import type { SyncStrategy } from './SyncStrategy';
 import {
   filterAllDocsByPrefix,
@@ -1088,6 +1089,21 @@ Currently logged-in as ${this._username}.`
     await this.localDB.put(doc);
   }
 
+  public async putUserOutcome(record: UserOutcomeRecord): Promise<void> {
+    try {
+      await this.localDB.put(record);
+    } catch (err: any) {
+      if (err.status === 409) {
+        // Overwrite if exists
+        const existing = await this.localDB.get(record._id);
+        (record as any)._rev = existing._rev;
+        await this.localDB.put(record);
+      } else {
+        throw err;
+      }
+    }
+  }
+
   public async deleteStrategyState(courseId: string, strategyKey: string): Promise<void> {
     const docId = buildStrategyStateId(courseId, strategyKey);
     try {

package/src/study/SessionController.ts

@@ -12,7 +12,8 @@ import {
   StudySessionReviewItem,
 } from '@db/impl/couch';
 
-import { CardRecord, CardHistory, CourseRegistrationDoc } from '@db/core';
+import { CardRecord, CardHistory, CourseRegistrationDoc, QuestionRecord } from '@db/core';
+import { recordUserOutcome } from '@db/core/orchestration/recording';
 import { Loggable } from '@db/util';
 import { getCardOrigin } from '@db/core/navigators';
 import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
@@ -587,4 +588,66 @@ export class SessionController<TView = unknown> extends Loggable {
       this.failedQ.dequeue((queueItem) => queueItem.cardID);
     }
   }
+
+  /**
+   * End the session and record learning outcomes.
+   *
+   * This method aggregates all responses from the session and records a
+   * UserOutcomeRecord if evolutionary orchestration is enabled.
+   */
+  public async endSession(): Promise<void> {
+    if (!this._sessionRecord || this._sessionRecord.length === 0) {
+      return;
+    }
+
+    const questionRecords = this._sessionRecord
+      .flatMap((r) => r.records)
+      .filter((r): r is QuestionRecord => (r as any).userAnswer !== undefined);
+
+    if (questionRecords.length === 0) {
+      return;
+    }
+
+    // We need to access the orchestration context.
+    // Ideally this would be passed in or available via services.
+    // For now, we'll try to get it from one of the content sources if possible,
+    // or skip if we can't access it.
+
+    // Try to find a source that supports orchestration
+    let orchestrationContext = null;
+    const strategies: string[] = [];
+
+    for (const source of this.sources) {
+      if (source.getOrchestrationContext) {
+        try {
+          orchestrationContext = await source.getOrchestrationContext();
+          // Also try to get strategy IDs if available on the source (e.g. Pipeline)
+          if ((source as any).getStrategyIds) {
+            strategies.push(...(source as any).getStrategyIds());
+          }
+        } catch (e) {
+          logger.warn(`[SessionController] Failed to get orchestration context: ${e}`);
+        }
+        if (orchestrationContext) break;
+      }
+    }
+
+    if (!orchestrationContext) {
+      logger.debug('[SessionController] No orchestration context available, skipping outcome recording');
+      return;
+    }
+
+    // Use current time as period end
+    const periodEnd = new Date().toISOString();
+    // Use session start time as period start
+    const periodStart = new Date(this.startTime).toISOString();
+
+    await recordUserOutcome(
+      orchestrationContext,
+      periodStart,
+      periodEnd,
+      questionRecords,
+      strategies
+    );
+  }
 }

package/tests/core/navigators/Pipeline.test.ts

@@ -90,6 +90,7 @@ function createMockContext(): { user: UserDBInterface; course: CourseDBInterface
     getCourseRegDoc: vi.fn().mockResolvedValue({
       elo: { global: { score: 1000, count: 10 }, tags: {} },
     }),
+    getUsername: vi.fn().mockReturnValue('test-user'),
   } as unknown as UserDBInterface;
 
   const mockCourse = {
@@ -294,6 +295,7 @@ describe('Pipeline', () => {
 
       const failingUser = {
         getCourseRegDoc: vi.fn().mockRejectedValue(new Error('Not registered')),
+        getUsername: vi.fn().mockReturnValue('failing-user'),
       } as unknown as UserDBInterface;
 
       let capturedElo = 0;

package/docs/todo-evolutionary-orchestration.md

@@ -1,310 +0,0 @@
-# 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.