@vue-skuilder/db 0.2.7 → 0.2.8

package/dist/core/index.d.cts

@@ -340,6 +340,37 @@ declare const DIVERSITY_FLOOR = 0.3;
  */
 declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
 
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -361,6 +392,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -742,4 +780,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, 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, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -340,6 +340,37 @@ declare const DIVERSITY_FLOOR = 0.3;
  */
 declare function diversityRerank(cards: WeightedCard[], opts?: DiversityRerankOptions): WeightedCard[];
 
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+interface PipelineForecaster {
+    forecast(opts?: {
+        hints?: ReplanHints;
+        unseenOnly?: boolean;
+        threshold?: number;
+        limit?: number;
+    }): Promise<WeightedCard[]>;
+}
 /**
  * Diagnosis of the full card space for the current user.
  */
@@ -361,6 +392,13 @@ interface CardSpaceDiagnosis {
     elapsedMs: number;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+declare function getActivePipeline(): PipelineForecaster | null;
 /**
  * Summary of a single generator's contribution.
  */
@@ -742,4 +780,4 @@ declare const userDBDebugAPI: {
  */
 declare function mountUserDBDebugger(): void;
 
-export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, CardHistory, CardRecord, CourseDBInterface, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, 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, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, type DiversityRerankOptions, DocType, DocTypePrefixes, type FilterContext, type FilterImpact, type GeneratorSummary, type GradientObservation, type GradientResult, type ImportResult, LearnableWeight, Loggable, OrchestrationContext, type PeriodUpdateInput, type PeriodUpdateResult, type PipelineForecaster, type PipelineRunReport, QuestionRecord, ReplanHints, type SignalConfig, StrategyContribution, type StrategyLearningState, type StrategyStateDoc, type StrategyStateId, UserDBInterface, UserOutcomeRecord, WeightedCard, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getActivePipeline, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig };

package/dist/core/index.js

@@ -814,6 +814,7 @@ __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
   clearRunHistory: () => clearRunHistory,
+  getActivePipeline: () => getActivePipeline,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -821,6 +822,9 @@ __export(PipelineDebugger_exports, {
 function registerPipelineForDebug(pipeline) {
   _activePipeline = pipeline;
 }
+function getActivePipeline() {
+  return _activePipeline;
+}
 function clearRunHistory() {
   runHistory.length = 0;
 }
@@ -4853,6 +4857,68 @@ var init_Pipeline = __esm({
       // ---------------------------------------------------------------------------
       // Card-space diagnostic
       // ---------------------------------------------------------------------------
+      /**
+       * Commit-free forecast: score the user's full card space through the filter
+       * chain and return the cards that are currently *reachable* (score >=
+       * threshold), optionally nudged by caller-supplied hints and/or restricted
+       * to cards the user hasn't seen yet.
+       *
+       * This is a GENERIC primitive — it returns scored, tag-hydrated cards and
+       * stops there. It has no knowledge of any particular tag convention; callers
+       * decide what the surviving cards mean (e.g. filter to their own "intro"
+       * tag family). Nothing is written and no session is started.
+       *
+       * The optional `hints` are the "out-of-band kick": they run through the same
+       * {@link applyHints} path a live replan uses, so the two semantics carry over —
+       *   - `boostTags`/`boostCards` reweight *within* gating (a gated score-0 card
+       *     stays out), and
+       *   - `requireTags`/`requireCards` inject from the full pre-filter pool,
+       *     *bypassing* gating (use when you want a card regardless of reachability).
+       * Note `unseenOnly` is applied LAST, so it can drop a `require`d card that the
+       * user has already seen — pass `unseenOnly: false` if that matters.
+       *
+       * Cost note: like {@link diagnoseCardSpace}, this scans every card through the
+       * filters, so it's heavier than a normal replan. Intended for one-shot
+       * out-of-band use (e.g. a session-end "what's next" snapshot), not the hot path.
+       *
+       * @param opts.hints       Optional ephemeral hints to apply after the filter chain.
+       * @param opts.unseenOnly  Only return cards the user hasn't encountered (default true).
+       * @param opts.threshold   Min score to count as reachable (default 0.10).
+       * @param opts.limit       Optional cap on results (already sorted desc).
+       */
+      async forecast(opts) {
+        const threshold = opts?.threshold ?? 0.1;
+        const unseenOnly = opts?.unseenOnly ?? true;
+        const courseId = this.course.getCourseID();
+        const allCardIds = await this.course.getAllCardIds();
+        let cards = allCardIds.map((cardId) => ({
+          cardId,
+          courseId,
+          score: 1,
+          provenance: []
+        }));
+        cards = await this.hydrateTags(cards);
+        const fullPool = cards.slice();
+        const context = await this.buildContext();
+        for (const filter of this.filters) {
+          cards = await filter.transform(cards, context);
+        }
+        if (opts?.hints) {
+          cards = this.applyHints(cards, opts.hints, fullPool);
+        }
+        cards = cards.filter((c) => c.score >= threshold);
+        if (unseenOnly) {
+          let encountered;
+          try {
+            encountered = new Set(await this.user.getSeenCards(courseId));
+          } catch {
+            encountered = /* @__PURE__ */ new Set();
+          }
+          cards = cards.filter((c) => !encountered.has(c.cardId));
+        }
+        cards.sort((a, b) => b.score - a.score);
+        return opts?.limit ? cards.slice(0, opts.limit) : cards;
+      }
       /**
        * Scan every card in the course through the filter chain and report
        * how many are "well indicated" (score >= threshold) for the current user.
@@ -5150,6 +5216,7 @@ __export(navigators_exports, {
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
   diversityRerank: () => diversityRerank,
+  getActivePipeline: () => getActivePipeline,
   getCardOrigin: () => getCardOrigin,
   getRegisteredNavigator: () => getRegisteredNavigator,
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,
@@ -8261,6 +8328,7 @@ __export(core_exports, {
   createOrchestrationContext: () => createOrchestrationContext,
   diversityRerank: () => diversityRerank,
   docIsDeleted: () => docIsDeleted,
+  getActivePipeline: () => getActivePipeline,
   getCardHistoryID: () => getCardHistoryID,
   getCardOrigin: () => getCardOrigin,
   getDefaultLearnableWeight: () => getDefaultLearnableWeight,
@@ -8329,6 +8397,7 @@ init_core();
   createOrchestrationContext,
   diversityRerank,
   docIsDeleted,
+  getActivePipeline,
   getCardHistoryID,
   getCardOrigin,
   getDefaultLearnableWeight,