@vue-skuilder/db 0.1.32-b → 0.1.32-e

package/dist/{contentSource-DF1nUbPQ.d.cts → contentSource-BMlMwSiG.d.cts}

@@ -1043,14 +1043,133 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * @param limit - Maximum cards to return
      * @returns Cards sorted by score descending, with provenance trails
      */
-    getWeightedCards(_limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(_limit: number): Promise<GeneratorResult>;
     /**
      * Set ephemeral hints for the next pipeline run.
      * No-op for non-Pipeline navigators. Pipeline overrides this.
      */
-    setEphemeralHints(_hints: Record<string, unknown>): void;
+    setEphemeralHints(_hints: ReplanHints): void;
 }
 
+/**
+ * Typed ephemeral pipeline hints for a single run.
+ * All fields are optional. Tag/card patterns support `*` wildcards.
+ */
+interface ReplanHints {
+    /** Multiply scores for cards matching these tag patterns. */
+    boostTags?: Record<string, number>;
+    /** Multiply scores for these specific card IDs (glob patterns). */
+    boostCards?: Record<string, number>;
+    /** Cards matching these tag patterns MUST appear in results. */
+    requireTags?: string[];
+    /** These specific card IDs MUST appear in results. */
+    requireCards?: string[];
+    /** Remove cards matching these tag patterns from results. */
+    excludeTags?: string[];
+    /** Remove these specific card IDs from results. */
+    excludeCards?: string[];
+    /**
+     * Debugging label threaded from the replan requester.
+     * Prefixed with `_` to signal it's metadata, not a scoring hint.
+     */
+    _label?: string;
+}
+/**
+ * Context available to generators when producing candidates.
+ *
+ * Built once per getWeightedCards() call by the Pipeline.
+ */
+interface GeneratorContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
+}
+/**
+ * Structured generator result.
+ *
+ * Generators may optionally emit one-shot replan hints alongside their
+ * candidate cards. This allows a generator to shape the broader pipeline
+ * without having to enumerate every affected support card directly.
+ */
+interface GeneratorResult {
+    /** Candidate cards produced by the generator */
+    cards: WeightedCard[];
+    /** Optional one-shot hints to apply after the filter chain */
+    hints?: ReplanHints;
+}
+/**
+ * A generator that produces candidate cards with initial scores.
+ *
+ * Generators are the "source" stage of a navigation pipeline.
+ * They query the database for eligible cards and assign initial
+ * suitability scores based on their strategy (ELO proximity,
+ * review urgency, fixed order, etc.).
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Create provenance**: Each card should have a provenance entry
+ *    with action='generated' documenting why it was selected.
+ *
+ * 2. **Score semantics**: Higher scores = more suitable for presentation.
+ *    Scores should be in [0, 1] range for composability.
+ *
+ * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
+ *    internally if needed for scoring accuracy.
+ *
+ * 4. **Sort before returning**: Return cards sorted by score descending.
+ *
+ * 5. **Hints are optional**: Generators may return structured results with
+ *    `hints` when they need to apply pipeline-wide ephemeral pressure.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myGenerator: CardGenerator = {
+ *   name: 'My Generator',
+ *   async getWeightedCards(limit, context) {
+ *     const candidates = await fetchCandidates(context.course, limit);
+ *     return candidates.map(c => ({
+ *       cardId: c.id,
+ *       courseId: context.course.getCourseID(),
+ *       score: computeScore(c, context),
+ *       provenance: [{
+ *         strategy: 'myGenerator',
+ *         strategyName: 'My Generator',
+ *         strategyId: 'MY_GENERATOR',
+ *         action: 'generated',
+ *         score: computeScore(c, context),
+ *         reason: 'Explanation of selection'
+ *       }]
+ *     }));
+ *   }
+ * };
+ * ```
+ */
+interface CardGenerator {
+    /** Human-readable name for this generator */
+    name: string;
+    /**
+     * Produce candidate cards with initial scores.
+     *
+     * @param limit - Maximum number of cards to return
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Cards sorted by score descending, with provenance, optionally
+     *          accompanied by one-shot replan hints
+     */
+    getWeightedCards(limit: number, context: GeneratorContext): Promise<GeneratorResult>;
+}
+/**
+ * Factory function type for creating generators from configuration.
+ *
+ * Used by PipelineAssembler to instantiate generators from strategy documents.
+ */
+type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
+
 type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 interface StudySessionFailedNewItem extends StudySessionItem {
     status: 'failed-new';
@@ -1101,7 +1220,7 @@ interface StudyContentSource {
      * @param limit - Maximum number of cards to return
      * @returns Cards sorted by score descending
      */
-    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(limit: number): Promise<GeneratorResult>;
     /**
      * Get the orchestration context for this source.
      * Used for recording learning outcomes.
@@ -1111,8 +1230,8 @@ interface StudyContentSource {
      * Set ephemeral hints for the next pipeline run.
      * No-op for sources that don't support hints.
      */
-    setEphemeralHints?(hints: Record<string, unknown>): void;
+    setEphemeralHints?(hints: ReplanHints): void;
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { NavigatorRoles as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type ClassroomRegistrationDoc as G, type SessionTrackingData as H, type UserConfig as I, type ActivityRecord as J, type CourseRegistration as K, type UserOutcomeRecord as L, registerNavigator as M, type NavigatorConstructor as N, getRegisteredNavigator as O, hasRegisteredNavigator as P, getRegisteredNavigatorRole as Q, getRegisteredNavigatorNames as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, initializeNavigatorRegistry as V, type WeightedCard as W, type StrategyContribution as X, getCardOrigin as Y, Navigators as Z, NavigatorRole as _, type UserDBReader as a, isGenerator as a0, isFilter as a1, type LearnableWeight as a2, type OrchestrationContext as a3, computeDeviation as a4, computeSpread as a5, computeEffectiveWeight as a6, createOrchestrationContext as a7, type DocumentUpdater as a8, newInterval as a9, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { Navigators as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type NavigatorConstructor as N, registerNavigator as O, getRegisteredNavigator as P, hasRegisteredNavigator as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, getRegisteredNavigatorRole as V, type WeightedCard as W, getRegisteredNavigatorNames as X, initializeNavigatorRegistry as Y, type StrategyContribution as Z, getCardOrigin as _, type UserDBReader as a, NavigatorRole as a0, NavigatorRoles as a1, isGenerator as a2, isFilter as a3, type CardGenerator as a4, type GeneratorContext as a5, type CardGeneratorFactory as a6, type LearnableWeight as a7, type OrchestrationContext as a8, computeDeviation as a9, computeSpread as aa, computeEffectiveWeight as ab, createOrchestrationContext as ac, type DocumentUpdater as ad, newInterval as ae, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };

package/dist/{contentSource-Bdwkvqa8.d.ts → contentSource-Ht3N2f-y.d.ts}

@@ -1043,14 +1043,133 @@ declare abstract class ContentNavigator implements StudyContentSource {
      * @param limit - Maximum cards to return
      * @returns Cards sorted by score descending, with provenance trails
      */
-    getWeightedCards(_limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(_limit: number): Promise<GeneratorResult>;
     /**
      * Set ephemeral hints for the next pipeline run.
      * No-op for non-Pipeline navigators. Pipeline overrides this.
      */
-    setEphemeralHints(_hints: Record<string, unknown>): void;
+    setEphemeralHints(_hints: ReplanHints): void;
 }
 
+/**
+ * Typed ephemeral pipeline hints for a single run.
+ * All fields are optional. Tag/card patterns support `*` wildcards.
+ */
+interface ReplanHints {
+    /** Multiply scores for cards matching these tag patterns. */
+    boostTags?: Record<string, number>;
+    /** Multiply scores for these specific card IDs (glob patterns). */
+    boostCards?: Record<string, number>;
+    /** Cards matching these tag patterns MUST appear in results. */
+    requireTags?: string[];
+    /** These specific card IDs MUST appear in results. */
+    requireCards?: string[];
+    /** Remove cards matching these tag patterns from results. */
+    excludeTags?: string[];
+    /** Remove these specific card IDs from results. */
+    excludeCards?: string[];
+    /**
+     * Debugging label threaded from the replan requester.
+     * Prefixed with `_` to signal it's metadata, not a scoring hint.
+     */
+    _label?: string;
+}
+/**
+ * Context available to generators when producing candidates.
+ *
+ * Built once per getWeightedCards() call by the Pipeline.
+ */
+interface GeneratorContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+    /** Orchestration context for evolutionary weighting */
+    orchestration?: OrchestrationContext;
+}
+/**
+ * Structured generator result.
+ *
+ * Generators may optionally emit one-shot replan hints alongside their
+ * candidate cards. This allows a generator to shape the broader pipeline
+ * without having to enumerate every affected support card directly.
+ */
+interface GeneratorResult {
+    /** Candidate cards produced by the generator */
+    cards: WeightedCard[];
+    /** Optional one-shot hints to apply after the filter chain */
+    hints?: ReplanHints;
+}
+/**
+ * A generator that produces candidate cards with initial scores.
+ *
+ * Generators are the "source" stage of a navigation pipeline.
+ * They query the database for eligible cards and assign initial
+ * suitability scores based on their strategy (ELO proximity,
+ * review urgency, fixed order, etc.).
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Create provenance**: Each card should have a provenance entry
+ *    with action='generated' documenting why it was selected.
+ *
+ * 2. **Score semantics**: Higher scores = more suitable for presentation.
+ *    Scores should be in [0, 1] range for composability.
+ *
+ * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
+ *    internally if needed for scoring accuracy.
+ *
+ * 4. **Sort before returning**: Return cards sorted by score descending.
+ *
+ * 5. **Hints are optional**: Generators may return structured results with
+ *    `hints` when they need to apply pipeline-wide ephemeral pressure.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myGenerator: CardGenerator = {
+ *   name: 'My Generator',
+ *   async getWeightedCards(limit, context) {
+ *     const candidates = await fetchCandidates(context.course, limit);
+ *     return candidates.map(c => ({
+ *       cardId: c.id,
+ *       courseId: context.course.getCourseID(),
+ *       score: computeScore(c, context),
+ *       provenance: [{
+ *         strategy: 'myGenerator',
+ *         strategyName: 'My Generator',
+ *         strategyId: 'MY_GENERATOR',
+ *         action: 'generated',
+ *         score: computeScore(c, context),
+ *         reason: 'Explanation of selection'
+ *       }]
+ *     }));
+ *   }
+ * };
+ * ```
+ */
+interface CardGenerator {
+    /** Human-readable name for this generator */
+    name: string;
+    /**
+     * Produce candidate cards with initial scores.
+     *
+     * @param limit - Maximum number of cards to return
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Cards sorted by score descending, with provenance, optionally
+     *          accompanied by one-shot replan hints
+     */
+    getWeightedCards(limit: number, context: GeneratorContext): Promise<GeneratorResult>;
+}
+/**
+ * Factory function type for creating generators from configuration.
+ *
+ * Used by PipelineAssembler to instantiate generators from strategy documents.
+ */
+type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
+
 type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 interface StudySessionFailedNewItem extends StudySessionItem {
     status: 'failed-new';
@@ -1101,7 +1220,7 @@ interface StudyContentSource {
      * @param limit - Maximum number of cards to return
      * @returns Cards sorted by score descending
      */
-    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    getWeightedCards(limit: number): Promise<GeneratorResult>;
     /**
      * Get the orchestration context for this source.
      * Used for recording learning outcomes.
@@ -1111,8 +1230,8 @@ interface StudyContentSource {
      * Set ephemeral hints for the next pipeline run.
      * No-op for sources that don't support hints.
      */
-    setEphemeralHints?(hints: Record<string, unknown>): void;
+    setEphemeralHints?(hints: ReplanHints): void;
 }
 declare function getStudySource(source: ContentSourceID, user: UserDBInterface): Promise<StudyContentSource>;
 
-export { NavigatorRoles as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type ClassroomRegistrationDoc as G, type SessionTrackingData as H, type UserConfig as I, type ActivityRecord as J, type CourseRegistration as K, type UserOutcomeRecord as L, registerNavigator as M, type NavigatorConstructor as N, getRegisteredNavigator as O, hasRegisteredNavigator as P, getRegisteredNavigatorRole as Q, getRegisteredNavigatorNames as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, initializeNavigatorRegistry as V, type WeightedCard as W, type StrategyContribution as X, getCardOrigin as Y, Navigators as Z, NavigatorRole as _, type UserDBReader as a, isGenerator as a0, isFilter as a1, type LearnableWeight as a2, type OrchestrationContext as a3, computeDeviation as a4, computeSpread as a5, computeEffectiveWeight as a6, createOrchestrationContext as a7, type DocumentUpdater as a8, newInterval as a9, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };
+export { Navigators as $, type AdminDBInterface as A, type UsrCrsDataInterface as B, type CourseDBInterface as C, type DataLayerResult as D, type ClassroomRegistrationDesignation as E, type ClassroomRegistration as F, type GeneratorResult as G, type ClassroomRegistrationDoc as H, type SessionTrackingData as I, type UserConfig as J, type ActivityRecord as K, type CourseRegistration as L, type UserOutcomeRecord as M, type NavigatorConstructor as N, registerNavigator as O, getRegisteredNavigator as P, hasRegisteredNavigator as Q, type ReplanHints as R, type StudySessionItem as S, type TeacherClassroomDBInterface as T, type UserDBInterface as U, getRegisteredNavigatorRole as V, type WeightedCard as W, getRegisteredNavigatorNames as X, initializeNavigatorRegistry as Y, type StrategyContribution as Z, getCardOrigin as _, type UserDBReader as a, NavigatorRole as a0, NavigatorRoles as a1, isGenerator as a2, isFilter as a3, type CardGenerator as a4, type GeneratorContext as a5, type CardGeneratorFactory as a6, type LearnableWeight as a7, type OrchestrationContext as a8, computeDeviation as a9, computeSpread as aa, computeEffectiveWeight as ab, createOrchestrationContext as ac, type DocumentUpdater as ad, newInterval as ae, type CoursesDBInterface as b, type ClassroomDBInterface as c, type CourseInfo as d, type ContentNavigationStrategyData as e, ContentNavigator as f, type AssignedContent as g, type StudyContentSource as h, type StudentClassroomDBInterface as i, type ScheduledCard as j, type StudySessionFailedItem as k, type StudySessionFailedNewItem as l, type StudySessionFailedReviewItem as m, type StudySessionNewItem as n, type StudySessionReviewItem as o, isReview as p, type ContentSourceID as q, getStudySource as r, type CourseRegistrationDoc as s, type AssignedTag as t, type AssignedCourse as u, type AssignedCard as v, type UserDBWriter as w, type UserDBAuthenticator as x, type UserCourseSettings as y, type UserCourseSetting as z };

package/dist/core/index.d.cts

@@ -1,6 +1,6 @@
-import { a2 as LearnableWeight, L as UserOutcomeRecord, a3 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, X as StrategyContribution } from '../contentSource-DF1nUbPQ.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, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, j as ScheduledCard, H as SessionTrackingData, 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, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-DF1nUbPQ.cjs';
-export { D as DataLayerProvider } from '../dataLayerProvider-BQdfJuBN.cjs';
+import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, Z as StrategyContribution } from '../contentSource-BMlMwSiG.cjs';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, R as ReplanHints, j as ScheduledCard, I as SessionTrackingData, 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, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, O as registerNavigator } from '../contentSource-BMlMwSiG.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-BEqB8VBR.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';
@@ -304,85 +304,6 @@ interface CardFilter {
  */
 type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
 
-/**
- * Context available to generators when producing candidates.
- *
- * Built once per getWeightedCards() call by the Pipeline.
- */
-interface GeneratorContext {
-    /** User database interface */
-    user: UserDBInterface;
-    /** Course database interface */
-    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.
- *
- * Generators are the "source" stage of a navigation pipeline.
- * They query the database for eligible cards and assign initial
- * suitability scores based on their strategy (ELO proximity,
- * review urgency, fixed order, etc.).
- *
- * ## Implementation Guidelines
- *
- * 1. **Create provenance**: Each card should have a provenance entry
- *    with action='generated' documenting why it was selected.
- *
- * 2. **Score semantics**: Higher scores = more suitable for presentation.
- *    Scores should be in [0, 1] range for composability.
- *
- * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
- *    internally if needed for scoring accuracy.
- *
- * 4. **Sort before returning**: Return cards sorted by score descending.
- *
- * ## Example Implementation
- *
- * ```typescript
- * const myGenerator: CardGenerator = {
- *   name: 'My Generator',
- *   async getWeightedCards(limit, context) {
- *     const candidates = await fetchCandidates(context.course, limit);
- *     return candidates.map(c => ({
- *       cardId: c.id,
- *       courseId: context.course.getCourseID(),
- *       score: computeScore(c, context),
- *       provenance: [{
- *         strategy: 'myGenerator',
- *         strategyName: 'My Generator',
- *         strategyId: 'MY_GENERATOR',
- *         action: 'generated',
- *         score: computeScore(c, context),
- *         reason: 'Explanation of selection'
- *       }]
- *     }));
- *   }
- * };
- * ```
- */
-interface CardGenerator {
-    /** Human-readable name for this generator */
-    name: string;
-    /**
-     * Produce candidate cards with initial scores.
-     *
-     * @param limit - Maximum number of cards to return
-     * @param context - Shared context (user, course, userElo, etc.)
-     * @returns Cards sorted by score descending, with provenance
-     */
-    getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
-}
-/**
- * Factory function type for creating generators from configuration.
- *
- * Used by PipelineAssembler to instantiate generators from strategy documents.
- */
-type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
-
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -432,6 +353,8 @@ interface PipelineRunReport {
     timestamp: Date;
     courseId: string;
     courseName?: string;
+    /** User's global ELO at the time of this pipeline run */
+    userElo?: number;
     generatorName: string;
     generators?: GeneratorSummary[];
     generatedCount: number;
@@ -444,6 +367,8 @@ interface PipelineRunReport {
         courseId: string;
         origin: 'new' | 'review' | 'unknown';
         finalScore: number;
+        /** Card's ELO (parsed from ELO generator provenance, if available) */
+        cardElo?: number;
         provenance: StrategyContribution[];
         tags?: string[];
         selected: boolean;
@@ -473,6 +398,17 @@ declare const pipelineDebugAPI: {
      * Explain why reviews may or may not have been selected.
      */
     explainReviews(): void;
+    /**
+     * Show prescribed-related cards from the most recent run.
+     *
+     * Highlights:
+     * - cards directly generated by the prescribed strategy
+     * - blocked prescribed targets mentioned in provenance
+     * - support tags resolved for blocked targets
+     *
+     * @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
+     */
+    showPrescribed(groupId?: string): void;
     /**
      * Show all runs in compact format.
      */
@@ -508,6 +444,13 @@ declare const pipelineDebugAPI: {
      * @param threshold - Score threshold for "well indicated" (default 0.10)
      */
     diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
+    /**
+     * Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
+     *
+     * @param tagFilter - Optional glob pattern(s) to filter tags.
+     *   Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
+     */
+    showTagElo(tagFilter?: string | string[]): Promise<void>;
     /**
      * Show help.
      */
@@ -700,4 +643,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorContext, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { a2 as LearnableWeight, L as UserOutcomeRecord, a3 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, X as StrategyContribution } from '../contentSource-Bdwkvqa8.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, _ as NavigatorRole, $ as NavigatorRoles, Z as Navigators, j as ScheduledCard, H as SessionTrackingData, 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, a4 as computeDeviation, a6 as computeEffectiveWeight, a5 as computeSpread, a7 as createOrchestrationContext, Y as getCardOrigin, O as getRegisteredNavigator, R as getRegisteredNavigatorNames, Q as getRegisteredNavigatorRole, r as getStudySource, P as hasRegisteredNavigator, V as initializeNavigatorRegistry, a1 as isFilter, a0 as isGenerator, p as isReview, M as registerNavigator } from '../contentSource-Bdwkvqa8.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-BKmVoyJR.js';
+import { a7 as LearnableWeight, M as UserOutcomeRecord, a8 as OrchestrationContext, W as WeightedCard, U as UserDBInterface, C as CourseDBInterface, Z as StrategyContribution } from '../contentSource-Ht3N2f-y.js';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, a5 as GeneratorContext, G as GeneratorResult, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, R as ReplanHints, j as ScheduledCard, I as SessionTrackingData, 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, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, O as registerNavigator } from '../contentSource-Ht3N2f-y.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-DObSXjnf.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';
@@ -304,85 +304,6 @@ interface CardFilter {
  */
 type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
 
-/**
- * Context available to generators when producing candidates.
- *
- * Built once per getWeightedCards() call by the Pipeline.
- */
-interface GeneratorContext {
-    /** User database interface */
-    user: UserDBInterface;
-    /** Course database interface */
-    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.
- *
- * Generators are the "source" stage of a navigation pipeline.
- * They query the database for eligible cards and assign initial
- * suitability scores based on their strategy (ELO proximity,
- * review urgency, fixed order, etc.).
- *
- * ## Implementation Guidelines
- *
- * 1. **Create provenance**: Each card should have a provenance entry
- *    with action='generated' documenting why it was selected.
- *
- * 2. **Score semantics**: Higher scores = more suitable for presentation.
- *    Scores should be in [0, 1] range for composability.
- *
- * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
- *    internally if needed for scoring accuracy.
- *
- * 4. **Sort before returning**: Return cards sorted by score descending.
- *
- * ## Example Implementation
- *
- * ```typescript
- * const myGenerator: CardGenerator = {
- *   name: 'My Generator',
- *   async getWeightedCards(limit, context) {
- *     const candidates = await fetchCandidates(context.course, limit);
- *     return candidates.map(c => ({
- *       cardId: c.id,
- *       courseId: context.course.getCourseID(),
- *       score: computeScore(c, context),
- *       provenance: [{
- *         strategy: 'myGenerator',
- *         strategyName: 'My Generator',
- *         strategyId: 'MY_GENERATOR',
- *         action: 'generated',
- *         score: computeScore(c, context),
- *         reason: 'Explanation of selection'
- *       }]
- *     }));
- *   }
- * };
- * ```
- */
-interface CardGenerator {
-    /** Human-readable name for this generator */
-    name: string;
-    /**
-     * Produce candidate cards with initial scores.
-     *
-     * @param limit - Maximum number of cards to return
-     * @param context - Shared context (user, course, userElo, etc.)
-     * @returns Cards sorted by score descending, with provenance
-     */
-    getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
-}
-/**
- * Factory function type for creating generators from configuration.
- *
- * Used by PipelineAssembler to instantiate generators from strategy documents.
- */
-type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
-
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -432,6 +353,8 @@ interface PipelineRunReport {
     timestamp: Date;
     courseId: string;
     courseName?: string;
+    /** User's global ELO at the time of this pipeline run */
+    userElo?: number;
     generatorName: string;
     generators?: GeneratorSummary[];
     generatedCount: number;
@@ -444,6 +367,8 @@ interface PipelineRunReport {
         courseId: string;
         origin: 'new' | 'review' | 'unknown';
         finalScore: number;
+        /** Card's ELO (parsed from ELO generator provenance, if available) */
+        cardElo?: number;
         provenance: StrategyContribution[];
         tags?: string[];
         selected: boolean;
@@ -473,6 +398,17 @@ declare const pipelineDebugAPI: {
      * Explain why reviews may or may not have been selected.
      */
     explainReviews(): void;
+    /**
+     * Show prescribed-related cards from the most recent run.
+     *
+     * Highlights:
+     * - cards directly generated by the prescribed strategy
+     * - blocked prescribed targets mentioned in provenance
+     * - support tags resolved for blocked targets
+     *
+     * @param groupId - Optional prescribed group ID filter (e.g. 'intro-core')
+     */
+    showPrescribed(groupId?: string): void;
     /**
      * Show all runs in compact format.
      */
@@ -508,6 +444,13 @@ declare const pipelineDebugAPI: {
      * @param threshold - Score threshold for "well indicated" (default 0.10)
      */
     diagnoseCardSpace(threshold?: number): Promise<CardSpaceDiagnosis | null>;
+    /**
+     * Show user's per-tag ELO data. Useful for diagnosing hierarchy gate status.
+     *
+     * @param tagFilter - Optional glob pattern(s) to filter tags.
+     *   Examples: 'gpc:expose:*', 'gpc:intro:t-T', ['gpc:expose:t-*', 'gpc:intro:t-*']
+     */
+    showTagElo(tagFilter?: string | string[]): Promise<void>;
     /**
      * Show help.
      */
@@ -700,4 +643,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorContext, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };