@vue-skuilder/db 0.2.7 → 0.2.8

package/dist/impl/couch/index.mjs

@@ -716,6 +716,7 @@ __export(PipelineDebugger_exports, {
   buildRunReport: () => buildRunReport,
   captureRun: () => captureRun,
   clearRunHistory: () => clearRunHistory,
+  getActivePipeline: () => getActivePipeline,
   mountPipelineDebugger: () => mountPipelineDebugger,
   pipelineDebugAPI: () => pipelineDebugAPI,
   registerPipelineForDebug: () => registerPipelineForDebug
@@ -723,6 +724,9 @@ __export(PipelineDebugger_exports, {
 function registerPipelineForDebug(pipeline) {
   _activePipeline = pipeline;
 }
+function getActivePipeline() {
+  return _activePipeline;
+}
 function clearRunHistory() {
   runHistory.length = 0;
 }
@@ -4509,6 +4513,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.
@@ -4806,6 +4872,7 @@ __export(navigators_exports, {
   NavigatorRoles: () => NavigatorRoles,
   Navigators: () => Navigators,
   diversityRerank: () => diversityRerank,
+  getActivePipeline: () => getActivePipeline,
   getCardOrigin: () => getCardOrigin,
   getRegisteredNavigator: () => getRegisteredNavigator,
   getRegisteredNavigatorNames: () => getRegisteredNavigatorNames,