@vue-skuilder/db 0.2.5 → 0.2.8

package/src/core/navigators/index.ts

@@ -5,17 +5,29 @@ export type { CardFilter, FilterContext, CardFilterFactory } from './filters/typ
 
 // Re-export generator types
 export type { CardGenerator, GeneratorContext, CardGeneratorFactory, GeneratorResult, ReplanHints } from './generators/types';
+
+// Re-export the diversity re-rank stage (pipeline stage 3)
+export {
+  diversityRerank,
+  DIVERSITY_STRENGTH,
+  DIVERSITY_FLOOR,
+  type DiversityRerankOptions,
+} from './diversityRerank';
 import type { GeneratorResult, ReplanHints } from './generators/types';
 
 // Re-export pipeline debugger API
 export {
   pipelineDebugAPI,
   mountPipelineDebugger,
+  getActivePipeline,
   type PipelineRunReport,
   type GeneratorSummary,
   type FilterImpact,
 } from './PipelineDebugger';
 
+// Re-export the commit-free forecast capability surface.
+export type { PipelineForecaster } from './Pipeline';
+
 import { LearnableWeight } from '../types/contentNavigationStrategy';
 export type { ContentNavigationStrategyData, LearnableWeight } from '../types/contentNavigationStrategy';
 import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';

package/src/study/ItemQueue.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { ItemQueue } from './ItemQueue';
+
+type Item = { cardID: string };
+const id = (i: Item) => i.cardID;
+const item = (cardID: string): Item => ({ cardID });
+const ids = (q: ItemQueue<Item>): string[] =>
+  Array.from({ length: q.length }, (_, i) => q.peek(i).cardID);
+
+describe('ItemQueue.mergeToFront', () => {
+  it('adds new items to the front, preserving batch order', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('a'), item('b')], id);
+
+    const added = q.mergeToFront([item('x'), item('y')], id);
+
+    expect(added).toBe(2);
+    expect(ids(q)).toEqual(['x', 'y', 'a', 'b']);
+  });
+
+  it('skips an ordinary duplicate, leaving it in place', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('a'), item('b'), item('c')], id);
+
+    // 'b' already queued and not mandatory → left where it is; 'x' fronted.
+    const added = q.mergeToFront([item('x'), item('b')], id);
+
+    expect(added).toBe(1);
+    expect(ids(q)).toEqual(['x', 'a', 'b', 'c']);
+  });
+
+  it('re-fronts an already-queued mandatory card instead of burying it', () => {
+    // Repro of the require-card burial: 'req' was fronted by a prior burst
+    // replan, then an additive merge brings fresh non-required cards. Without
+    // the mandatory re-front, 'x'/'y' would leapfrog 'req' and sink it.
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a'), item('b')], id);
+
+    const added = q.mergeToFront(
+      [item('req'), item('x'), item('y')],
+      id,
+      new Set(['req'])
+    );
+
+    // 'req' is not a *new* add, so it isn't counted...
+    expect(added).toBe(2);
+    // ...but it leads the queue (ahead of the freshly merged 'x'/'y').
+    expect(ids(q)).toEqual(['req', 'x', 'y', 'a', 'b']);
+    // and isn't duplicated.
+    expect(ids(q).filter((c) => c === 'req')).toHaveLength(1);
+  });
+
+  it('keeps a mandatory card already at the front at the front', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a')], id);
+
+    q.mergeToFront([item('req'), item('x')], id, new Set(['req']));
+
+    expect(ids(q)).toEqual(['req', 'x', 'a']);
+  });
+
+  it('without forceFrontIds, preserves the legacy skip-duplicate behavior', () => {
+    const q = new ItemQueue<Item>();
+    q.addAll([item('req'), item('a')], id);
+
+    // No mandatory set → 'req' stays put and is buried behind the merged 'x'.
+    q.mergeToFront([item('req'), item('x')], id);
+
+    expect(ids(q)).toEqual(['x', 'req', 'a']);
+  });
+});

package/src/study/ItemQueue.ts

@@ -73,8 +73,21 @@ export class ItemQueue<T> {
    * Merge new items into the front of the queue, skipping duplicates.
    * Used by additive replans to inject high-quality candidates without
    * discarding the existing queue contents.
+   *
+   * `forceFrontIds` carries the mandatory (`+INF`) cards in this batch — a
+   * durable `requireCard`/`requireTag` re-asserted by every replan. An ordinary
+   * duplicate is left in place (skip), but a mandatory one that's *already*
+   * queued is pulled out of its current slot so it rejoins at the front in batch
+   * order. Without this, an additive merge unshifts fresh non-required cards
+   * ahead of an already-present required card, steadily burying it until it never
+   * gets drawn — defeating the "must appear" guarantee. Returns the count of
+   * genuinely new cards added (re-fronted duplicates are not counted).
    */
-  public mergeToFront(items: T[], cardIdExtractor: (item: T) => string): number {
+  public mergeToFront(
+    items: T[],
+    cardIdExtractor: (item: T) => string,
+    forceFrontIds?: ReadonlySet<string>
+  ): number {
     let added = 0;
     const toInsert: T[] = [];
     for (const item of items) {
@@ -83,6 +96,11 @@ export class ItemQueue<T> {
         this.seenCardIds.push(cardId);
         toInsert.push(item);
         added++;
+      } else if (forceFrontIds?.has(cardId)) {
+        const idx = this.q.findIndex((qi) => cardIdExtractor(qi) === cardId);
+        if (idx >= 0) {
+          toInsert.push(...this.q.splice(idx, 1));
+        }
       }
     }
     this.q.unshift(...toInsert);

package/src/study/SessionController.ts

@@ -1161,9 +1161,22 @@ export class SessionController<TView = unknown> extends Loggable {
     // additive merge, or a stale generator candidate. This is the general guard
     // (see _servedCardIds); it makes re-presentation structurally impossible
     // rather than relying on each upstream path to exclude correctly.
-    const newWeighted = mixedWeighted
-      .filter((w) => getCardOrigin(w) === 'new' && !this._servedCardIds.has(w.cardId))
-      .slice(0, newLimit);
+    const newCandidates = mixedWeighted.filter(
+      (w) => getCardOrigin(w) === 'new' && !this._servedCardIds.has(w.cardId)
+    );
+    // `+INF` is the hard "include at all costs" sentinel applied by require*
+    // injection (see Pipeline.applyRequirement). Partition these mandatory cards
+    // to the front and exempt them from the newLimit slice, so neither the
+    // mixer's source-shuffle/round-robin nor the cap can bury or drop a required
+    // card before it reaches newQ. The set is also handed to mergeToFront so an
+    // already-queued required card gets re-fronted rather than leapfrogged.
+    const mandatoryWeighted = newCandidates.filter((w) => w.score === Number.POSITIVE_INFINITY);
+    const optionalWeighted = newCandidates.filter((w) => w.score !== Number.POSITIVE_INFINITY);
+    const newWeighted = [
+      ...mandatoryWeighted,
+      ...optionalWeighted.slice(0, Math.max(0, newLimit - mandatoryWeighted.length)),
+    ];
+    const mandatoryIds = new Set(mandatoryWeighted.map((w) => w.cardId));
 
     logger.debug(`[reviews] got ${reviewWeighted.length} reviews from mixer`);
 
@@ -1206,8 +1219,10 @@ export class SessionController<TView = unknown> extends Loggable {
     }
 
     if (additive) {
-      // Additive replan: merge new candidates into front of existing queue
-      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID);
+      // Additive replan: merge new candidates into front of existing queue.
+      // Pass mandatory (+INF) ids so an already-queued required card is pulled
+      // back to the front instead of being buried by fresh non-required cards.
+      const added = this.newQ.mergeToFront(newItems, (item) => item.cardID, mandatoryIds);
       report += `Additive merge: ${added} new cards added to front of newQ\n`;
     } else if (replan) {
       // Atomic swap: replace entire newQ contents at once (no empty-queue window)