@vue-skuilder/db 0.1.22 → 0.1.24

package/dist/core/index.d.cts

@@ -1,8 +1,8 @@
-import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-DsJadoBU.cjs';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, j as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../contentSource-DsJadoBU.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-CHYrQ5pB.cjs';
-import { b as DocTypePrefixes, D as DocType, C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-DDY4N-Uq.cjs';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-DDY4N-Uq.cjs';
+import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-C90LH-OH.cjs';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H as SessionTrackingData, V as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-C90LH-OH.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-DGKp4zFB.cjs';
+import { D as DocType, i as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-JXDxinpU.cjs';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-JXDxinpU.cjs';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
 
@@ -12,6 +12,216 @@ declare abstract class Loggable {
     protected error(...args: unknown[]): void;
 }
 
+/**
+ * Snapshot of the learning state for a strategy.
+ *
+ * Stored in the CourseDB for observability and debugging.
+ * Updated periodically by the gradient learning system.
+ */
+interface StrategyLearningState {
+    /**
+     * Unique ID: "STRATEGY_LEARNING_STATE::{courseId}::{strategyId}"
+     */
+    _id: string;
+    /** Allow CouchDB to manage revisions */
+    _rev?: string;
+    docType: DocType.STRATEGY_LEARNING_STATE;
+    courseId: string;
+    strategyId: string;
+    /** Current learned weight (mirrors the strategy doc, for convenience) */
+    currentWeight: LearnableWeight;
+    /** Most recent regression statistics */
+    regression: {
+        /** Slope of the linear regression (deviation vs outcome) */
+        gradient: number;
+        /** Y-intercept of the regression line */
+        intercept: number;
+        /** R-squared value (0-1), measure of fit quality */
+        rSquared: number;
+        /** Number of observations used in this regression */
+        sampleSize: number;
+        /** ISO timestamp of when this regression was computed */
+        computedAt: string;
+    };
+    /** Historical weight snapshots for visualization */
+    history: Array<{
+        timestamp: string;
+        weight: number;
+        confidence: number;
+        gradient: number;
+    }>;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Data point for gradient computation: (deviation, outcome) pair.
+ */
+interface GradientObservation {
+    /** User's deviation for this strategy [-1, 1] */
+    deviation: number;
+    /** User's outcome value [0, 1] */
+    outcomeValue: number;
+    /** Optional: weight for this observation (default 1.0) */
+    weight?: number;
+}
+/**
+ * Result of linear regression on (deviation, outcome) pairs.
+ */
+interface GradientResult {
+    /** Slope: positive = higher deviation correlates with better outcomes */
+    gradient: number;
+    /** Y-intercept */
+    intercept: number;
+    /** R-squared: 0-1, how well the line fits */
+    rSquared: number;
+    /** Number of observations */
+    sampleSize: number;
+}
+
+/**
+ * Extract (deviation, outcome) observations for a specific strategy
+ * from a collection of UserOutcomeRecords.
+ *
+ * @param outcomes - Collection of outcome records (from multiple users)
+ * @param strategyId - The strategy to extract observations for
+ * @returns Array of gradient observations
+ */
+declare function aggregateOutcomesForGradient(outcomes: UserOutcomeRecord[], strategyId: string): GradientObservation[];
+/**
+ * Compute linear regression on (deviation, outcome) pairs.
+ *
+ * Uses ordinary least squares to find the best fit line:
+ *   outcome = gradient * deviation + intercept
+ *
+ * The gradient tells us:
+ * - Positive: users with higher deviation (higher weight) had better outcomes
+ *             → we should increase the peak weight
+ * - Negative: users with higher deviation (higher weight) had worse outcomes
+ *             → we should decrease the peak weight
+ * - Near zero: weight doesn't affect outcomes much
+ *             → we're near optimal, increase confidence
+ *
+ * @param observations - Array of (deviation, outcome) pairs
+ * @returns Regression result, or null if insufficient data
+ */
+declare function computeStrategyGradient(observations: GradientObservation[]): GradientResult | null;
+
+/**
+ * Compute updated weight based on gradient result.
+ *
+ * The update logic:
+ * - Positive gradient: users with higher weight did better → increase weight
+ * - Negative gradient: users with higher weight did worse → decrease weight
+ * - Flat gradient: weight doesn't affect outcome → increase confidence
+ *
+ * @param current - Current learnable weight
+ * @param gradient - Computed gradient result
+ * @returns Updated learnable weight
+ */
+declare function updateStrategyWeight(current: LearnableWeight, gradient: GradientResult): LearnableWeight;
+/**
+ * Create or update a StrategyLearningState document.
+ *
+ * @param courseId - Course ID
+ * @param strategyId - Strategy ID
+ * @param currentWeight - Current learned weight
+ * @param gradient - Gradient result from recent computation
+ * @param existing - Existing learning state (if any)
+ * @returns Updated learning state document
+ */
+declare function updateLearningState(courseId: string, strategyId: string, currentWeight: LearnableWeight, gradient: GradientResult, existing?: StrategyLearningState): StrategyLearningState;
+/**
+ * Input data for running a period update on a single strategy.
+ */
+interface PeriodUpdateInput {
+    courseId: string;
+    strategyId: string;
+    currentWeight: LearnableWeight;
+    gradient: GradientResult;
+    existingState?: StrategyLearningState;
+}
+/**
+ * Result of a period update for a single strategy.
+ */
+interface PeriodUpdateResult {
+    strategyId: string;
+    previousWeight: LearnableWeight;
+    newWeight: LearnableWeight;
+    gradient: GradientResult;
+    learningState: StrategyLearningState;
+    updated: boolean;
+}
+/**
+ * Run a period update for a single strategy.
+ *
+ * This function:
+ * 1. Takes the computed gradient
+ * 2. Computes the new weight
+ * 3. Generates the updated learning state
+ *
+ * Note: Actual persistence (updating strategy doc, saving learning state)
+ * must be done by the caller with appropriate DB access.
+ *
+ * @param input - Update input data
+ * @returns Update result with new weight and learning state
+ */
+declare function runPeriodUpdate(input: PeriodUpdateInput): PeriodUpdateResult;
+/**
+ * Create a default LearnableWeight for strategies that don't have one.
+ */
+declare function getDefaultLearnableWeight(): LearnableWeight;
+
+interface SignalConfig {
+    /** Target accuracy for "in the zone" learning (default: 0.85) */
+    targetAccuracy?: number;
+    /** Width of the peak plateau (default: 0.05) */
+    tolerance?: number;
+}
+/**
+ * Computes a scalar signal (0-1) representing the quality of the learning outcome.
+ *
+ * Current implementation focuses on "accuracy within Zone of Proximal Development".
+ * Future versions should include ELO gain rate.
+ *
+ * @param records - List of question attempts in the period
+ * @param config - Configuration for the signal function
+ * @returns Score 0.0-1.0, or null if insufficient data
+ */
+declare function computeOutcomeSignal(records: QuestionRecord[], config?: SignalConfig): number | null;
+/**
+ * Scores an accuracy value based on how close it is to the target "sweet spot".
+ *
+ * The function defines a plateau of width (2 * tolerance) around the target
+ * where score is 1.0. Outside this plateau, it falls off linearly.
+ *
+ * @param accuracy - Observed accuracy (0-1)
+ * @param target - Target accuracy (e.g. 0.85)
+ * @param tolerance - +/- range allowed for max score
+ */
+declare function scoreAccuracyInZone(accuracy: number, target: number, tolerance: number): number;
+
+/**
+ * Records a learning outcome for a specific period of time.
+ *
+ * This function:
+ * 1. Computes a scalar "success" signal from the provided question records
+ * 2. Re-computes the deviations that were active for this user/course
+ * 3. Persists a UserOutcomeRecord to the user's database
+ *
+ * This record is later used by the optimization job to correlate
+ * deviations with outcomes (Evolutionary Orchestration).
+ *
+ * @param context - Orchestration context (user, course, etc.)
+ * @param periodStart - ISO timestamp of period start
+ * @param periodEnd - ISO timestamp of period end (now)
+ * @param records - Question records generated during this period
+ * @param activeStrategyIds - IDs of strategies active in this course
+ * @param eloStart - User's ELO at start of period (optional)
+ * @param eloEnd - User's ELO at end of period (optional)
+ * @param config - Optional configuration for signal computation
+ */
+declare function recordUserOutcome(context: OrchestrationContext, periodStart: string, periodEnd: string, records: QuestionRecord[], activeStrategyIds: string[], eloStart?: number, eloEnd?: number, config?: SignalConfig): Promise<void>;
+
 /**
  * Shared context available to all filters in a pipeline.
  *
@@ -25,6 +235,8 @@ interface FilterContext {
     course: CourseDBInterface;
     /** User's global ELO score for this course */
     userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
 }
 /**
  * A filter that transforms a list of weighted cards.
@@ -104,6 +316,8 @@ interface GeneratorContext {
     course: CourseDBInterface;
     /** User's global ELO score for this course */
     userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
 }
 /**
  * A generator that produces candidate cards with initial scores.
@@ -301,4 +515,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, type StrategyStateDoc, type StrategyStateId, UserDBInterface, WeightedCard, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, QuestionRecord, type SignalConfig, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
-import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BP9hznNV.js';
-export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, j as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview } from '../contentSource-BP9hznNV.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-MDTxXq2l.js';
-import { b as DocTypePrefixes, D as DocType, C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-DDY4N-Uq.js';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-DDY4N-Uq.js';
+import { a1 as LearnableWeight, L as UserOutcomeRecord, a2 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BotbOOfX.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, N as NavigatorConstructor, Z as NavigatorRole, _ as NavigatorRoles, Y as Navigators, j as ScheduledCard, H as SessionTrackingData, V as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a3 as computeDeviation, a5 as computeEffectiveWeight, a4 as computeSpread, a6 as createOrchestrationContext, X as getCardOrigin, O as getRegisteredNavigator, Q as getRegisteredNavigatorNames, r as getStudySource, P as hasRegisteredNavigator, R as initializeNavigatorRegistry, a0 as isFilter, $ as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-BotbOOfX.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-SBpz9jQf.js';
+import { D as DocType, i as QuestionRecord, b as DocTypePrefixes, C as CardHistory, c as CardRecord } from '../types-legacy-JXDxinpU.js';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-JXDxinpU.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
 
@@ -12,6 +12,216 @@ declare abstract class Loggable {
     protected error(...args: unknown[]): void;
 }
 
+/**
+ * Snapshot of the learning state for a strategy.
+ *
+ * Stored in the CourseDB for observability and debugging.
+ * Updated periodically by the gradient learning system.
+ */
+interface StrategyLearningState {
+    /**
+     * Unique ID: "STRATEGY_LEARNING_STATE::{courseId}::{strategyId}"
+     */
+    _id: string;
+    /** Allow CouchDB to manage revisions */
+    _rev?: string;
+    docType: DocType.STRATEGY_LEARNING_STATE;
+    courseId: string;
+    strategyId: string;
+    /** Current learned weight (mirrors the strategy doc, for convenience) */
+    currentWeight: LearnableWeight;
+    /** Most recent regression statistics */
+    regression: {
+        /** Slope of the linear regression (deviation vs outcome) */
+        gradient: number;
+        /** Y-intercept of the regression line */
+        intercept: number;
+        /** R-squared value (0-1), measure of fit quality */
+        rSquared: number;
+        /** Number of observations used in this regression */
+        sampleSize: number;
+        /** ISO timestamp of when this regression was computed */
+        computedAt: string;
+    };
+    /** Historical weight snapshots for visualization */
+    history: Array<{
+        timestamp: string;
+        weight: number;
+        confidence: number;
+        gradient: number;
+    }>;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Data point for gradient computation: (deviation, outcome) pair.
+ */
+interface GradientObservation {
+    /** User's deviation for this strategy [-1, 1] */
+    deviation: number;
+    /** User's outcome value [0, 1] */
+    outcomeValue: number;
+    /** Optional: weight for this observation (default 1.0) */
+    weight?: number;
+}
+/**
+ * Result of linear regression on (deviation, outcome) pairs.
+ */
+interface GradientResult {
+    /** Slope: positive = higher deviation correlates with better outcomes */
+    gradient: number;
+    /** Y-intercept */
+    intercept: number;
+    /** R-squared: 0-1, how well the line fits */
+    rSquared: number;
+    /** Number of observations */
+    sampleSize: number;
+}
+
+/**
+ * Extract (deviation, outcome) observations for a specific strategy
+ * from a collection of UserOutcomeRecords.
+ *
+ * @param outcomes - Collection of outcome records (from multiple users)
+ * @param strategyId - The strategy to extract observations for
+ * @returns Array of gradient observations
+ */
+declare function aggregateOutcomesForGradient(outcomes: UserOutcomeRecord[], strategyId: string): GradientObservation[];
+/**
+ * Compute linear regression on (deviation, outcome) pairs.
+ *
+ * Uses ordinary least squares to find the best fit line:
+ *   outcome = gradient * deviation + intercept
+ *
+ * The gradient tells us:
+ * - Positive: users with higher deviation (higher weight) had better outcomes
+ *             → we should increase the peak weight
+ * - Negative: users with higher deviation (higher weight) had worse outcomes
+ *             → we should decrease the peak weight
+ * - Near zero: weight doesn't affect outcomes much
+ *             → we're near optimal, increase confidence
+ *
+ * @param observations - Array of (deviation, outcome) pairs
+ * @returns Regression result, or null if insufficient data
+ */
+declare function computeStrategyGradient(observations: GradientObservation[]): GradientResult | null;
+
+/**
+ * Compute updated weight based on gradient result.
+ *
+ * The update logic:
+ * - Positive gradient: users with higher weight did better → increase weight
+ * - Negative gradient: users with higher weight did worse → decrease weight
+ * - Flat gradient: weight doesn't affect outcome → increase confidence
+ *
+ * @param current - Current learnable weight
+ * @param gradient - Computed gradient result
+ * @returns Updated learnable weight
+ */
+declare function updateStrategyWeight(current: LearnableWeight, gradient: GradientResult): LearnableWeight;
+/**
+ * Create or update a StrategyLearningState document.
+ *
+ * @param courseId - Course ID
+ * @param strategyId - Strategy ID
+ * @param currentWeight - Current learned weight
+ * @param gradient - Gradient result from recent computation
+ * @param existing - Existing learning state (if any)
+ * @returns Updated learning state document
+ */
+declare function updateLearningState(courseId: string, strategyId: string, currentWeight: LearnableWeight, gradient: GradientResult, existing?: StrategyLearningState): StrategyLearningState;
+/**
+ * Input data for running a period update on a single strategy.
+ */
+interface PeriodUpdateInput {
+    courseId: string;
+    strategyId: string;
+    currentWeight: LearnableWeight;
+    gradient: GradientResult;
+    existingState?: StrategyLearningState;
+}
+/**
+ * Result of a period update for a single strategy.
+ */
+interface PeriodUpdateResult {
+    strategyId: string;
+    previousWeight: LearnableWeight;
+    newWeight: LearnableWeight;
+    gradient: GradientResult;
+    learningState: StrategyLearningState;
+    updated: boolean;
+}
+/**
+ * Run a period update for a single strategy.
+ *
+ * This function:
+ * 1. Takes the computed gradient
+ * 2. Computes the new weight
+ * 3. Generates the updated learning state
+ *
+ * Note: Actual persistence (updating strategy doc, saving learning state)
+ * must be done by the caller with appropriate DB access.
+ *
+ * @param input - Update input data
+ * @returns Update result with new weight and learning state
+ */
+declare function runPeriodUpdate(input: PeriodUpdateInput): PeriodUpdateResult;
+/**
+ * Create a default LearnableWeight for strategies that don't have one.
+ */
+declare function getDefaultLearnableWeight(): LearnableWeight;
+
+interface SignalConfig {
+    /** Target accuracy for "in the zone" learning (default: 0.85) */
+    targetAccuracy?: number;
+    /** Width of the peak plateau (default: 0.05) */
+    tolerance?: number;
+}
+/**
+ * Computes a scalar signal (0-1) representing the quality of the learning outcome.
+ *
+ * Current implementation focuses on "accuracy within Zone of Proximal Development".
+ * Future versions should include ELO gain rate.
+ *
+ * @param records - List of question attempts in the period
+ * @param config - Configuration for the signal function
+ * @returns Score 0.0-1.0, or null if insufficient data
+ */
+declare function computeOutcomeSignal(records: QuestionRecord[], config?: SignalConfig): number | null;
+/**
+ * Scores an accuracy value based on how close it is to the target "sweet spot".
+ *
+ * The function defines a plateau of width (2 * tolerance) around the target
+ * where score is 1.0. Outside this plateau, it falls off linearly.
+ *
+ * @param accuracy - Observed accuracy (0-1)
+ * @param target - Target accuracy (e.g. 0.85)
+ * @param tolerance - +/- range allowed for max score
+ */
+declare function scoreAccuracyInZone(accuracy: number, target: number, tolerance: number): number;
+
+/**
+ * Records a learning outcome for a specific period of time.
+ *
+ * This function:
+ * 1. Computes a scalar "success" signal from the provided question records
+ * 2. Re-computes the deviations that were active for this user/course
+ * 3. Persists a UserOutcomeRecord to the user's database
+ *
+ * This record is later used by the optimization job to correlate
+ * deviations with outcomes (Evolutionary Orchestration).
+ *
+ * @param context - Orchestration context (user, course, etc.)
+ * @param periodStart - ISO timestamp of period start
+ * @param periodEnd - ISO timestamp of period end (now)
+ * @param records - Question records generated during this period
+ * @param activeStrategyIds - IDs of strategies active in this course
+ * @param eloStart - User's ELO at start of period (optional)
+ * @param eloEnd - User's ELO at end of period (optional)
+ * @param config - Optional configuration for signal computation
+ */
+declare function recordUserOutcome(context: OrchestrationContext, periodStart: string, periodEnd: string, records: QuestionRecord[], activeStrategyIds: string[], eloStart?: number, eloEnd?: number, config?: SignalConfig): Promise<void>;
+
 /**
  * Shared context available to all filters in a pipeline.
  *
@@ -25,6 +235,8 @@ interface FilterContext {
     course: CourseDBInterface;
     /** User's global ELO score for this course */
     userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
 }
 /**
  * A filter that transforms a list of weighted cards.
@@ -104,6 +316,8 @@ interface GeneratorContext {
     course: CourseDBInterface;
     /** User's global ELO score for this course */
     userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
 }
 /**
  * A generator that produces candidate cards with initial scores.
@@ -301,4 +515,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, type StrategyStateDoc, type StrategyStateId, UserDBInterface, WeightedCard, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, QuestionRecord, type SignalConfig, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, parseCardHistoryID, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, validateProcessorConfig };