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

package/dist/{types-CJrLM1Ew.d.ts → types-DZ5dUqbL.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.js';
+import { D as DocType } from './types-legacy-C7r0T4OV.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-W8n-B6HG.d.cts → types-ZL8tOPQZ.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-JXDxinpU.cjs';
+import { D as DocType } from './types-legacy-C7r0T4OV.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-JXDxinpU.d.cts → types-legacy-C7r0T4OV.d.cts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CourseListData as b, type DisplayableData as c, type DataShapeData as d, type QuestionData as e, DocTypePrefixes as f, type CardHistory as g, type CardRecord as h, type QuestionRecord as i, log as l };

package/dist/{types-legacy-JXDxinpU.d.ts → types-legacy-C7r0T4OV.d.ts}

@@ -157,4 +157,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
     priorAttemps: number;
 }
 
-export { type CardHistory as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, DocTypePrefixes as b, type CardRecord as c, type CardData as d, type CourseListData as e, type DisplayableData as f, type DataShapeData as g, type QuestionData as h, type QuestionRecord as i, log as l };
+export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QualifiedCardID as Q, type SkuilderCourseData as S, type TagStub as T, type Tag as a, type CourseListData as b, type DisplayableData as c, type DataShapeData as d, type QuestionData as e, DocTypePrefixes as f, type CardHistory as g, type CardRecord as h, type QuestionRecord as i, log as l };

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-W8n-B6HG.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-Ba7hYbHj.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-ZL8tOPQZ.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-m8MMGxxR.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.cjs';
+import '../../types-legacy-C7r0T4OV.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CJrLM1Ew.js';
-export { C as CouchDBToStaticPacker } from '../../index-BWvO-_rJ.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DZ5dUqbL.js';
+export { C as CouchDBToStaticPacker } from '../../index-X6wHrURm.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-JXDxinpU.js';
+import '../../types-legacy-C7r0T4OV.js';
 import 'moment';

package/docs/navigators-architecture.md

@@ -48,7 +48,7 @@ interface CardGenerator {
 **Implementations:**
 - `ELONavigator` — New cards scored by ELO proximity to user skill (scores 0.0-1.0)
 - `SRSNavigator` — Review cards scored by overdueness, interval recency, and **backlog pressure** (scores 0.5-1.0)
-- `HardcodedOrderNavigator` — Fixed sequence defined by course author
+- `HardcodedOrderNavigator` — Fixed sequence defined by course author // NB this no longer exists but /home/colin/pn/vue-skuilder/master/packages/db/src/core/navigators/generators/prescribed.ts does - please update the doc in place
 - `CompositeGenerator` — Merges multiple generators with frequency boost
 
 #### SRS Backlog Pressure
@@ -620,4 +620,4 @@ return { ...card, score: card.score * multiplier };
 - `todo-review-adaptation.md` — Planned per-user review urgency adaptation
 - `future-orchestration-vision.md` — Long-term adaptive strategy vision (beyond current implementation)
 - `devlog/1004` — Implementation details for tag hydration optimization
-- `devlog/1032-orchestrator` — Evolutionary orchestration implementation details
+- `devlog/1032-orchestrator` — Evolutionary orchestration implementation details

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.32-b",
+  "version": "0.1.32-c",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.32-b",
+    "@vue-skuilder/common": "0.1.32-c",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",

package/src/core/interfaces/contentSource.ts

@@ -5,6 +5,7 @@ import { WeightedCard } from '../navigators';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
 import { OrchestrationContext } from '../orchestration';
+import type { ReplanHints } from '@db/study/SessionController';
 
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
@@ -84,7 +85,7 @@ export 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;
 }
 // #endregion docs_StudyContentSource
 

package/src/core/navigators/Pipeline.ts

@@ -22,31 +22,9 @@ import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSum
 //   'gpc:exercise:t-*'   — all t-variant exercises
 //
 
-/**
- * Ephemeral pipeline hints for a single run.
- * All fields are optional. Tag/card patterns support `*` wildcards.
- */
-export 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.
-   * Attached to provenance entries so card scoring history
-   * can be traced back to the originating event.
-   * Prefixed with `_` to signal it's metadata, not a scoring hint.
-   */
-  _label?: string;
-}
+// ReplanHints is the canonical type — re-export for consumers that import from Pipeline
+import { ReplanHints } from '@db/study/SessionController';
+export { ReplanHints };
 
 /**
  * Convert a glob pattern (with `*` wildcards) to a RegExp.
@@ -296,8 +274,8 @@ export class Pipeline extends ContentNavigator {
    *
    * Overrides ContentNavigator.setEphemeralHints() no-op.
    */
-  override setEphemeralHints(hints: Record<string, unknown>): void {
-    this._ephemeralHints = hints as ReplanHints;
+  override setEphemeralHints(hints: ReplanHints): void {
+    this._ephemeralHints = hints;
     logger.info(`[Pipeline] Ephemeral hints set: ${JSON.stringify(hints)}`);
   }
 
@@ -439,6 +417,9 @@ export class Pipeline extends ContentNavigator {
     // Capture run for debug API
     try {
       const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
+      // Use the full post-filter sorted array (not just top N) so that
+      // showCard() can inspect provenance for cards that didn't make the cut.
+      // `cards` is the post-filter, post-hints, sorted array.
       const report = buildRunReport(
         this.course?.getCourseID() || 'unknown',
         courseName,
@@ -446,8 +427,9 @@ export class Pipeline extends ContentNavigator {
         generatorSummaries,
         generatedCount,
         filterImpacts,
-        allCardsBeforeFiltering,
-        result
+        cards,
+        result,
+        context.userElo
       );
       captureRun(report);
     } catch (e) {
@@ -707,6 +689,42 @@ export class Pipeline extends ContentNavigator {
     return [...new Set(ids)];
   }
 
+  // ---------------------------------------------------------------------------
+  // Tag ELO diagnostic
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get the user's per-tag ELO data for specified tags (or all tags).
+   * Useful for diagnosing why hierarchy gates are open/closed.
+   */
+  async getTagEloStatus(
+    tagFilter?: string | string[]
+  ): Promise<Record<string, { score: number; count: number }>> {
+    const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
+    const courseElo = toCourseElo(courseReg.elo);
+
+    const result: Record<string, { score: number; count: number }> = {};
+
+    if (!tagFilter) {
+      // Return all tags
+      for (const [tag, data] of Object.entries(courseElo.tags)) {
+        result[tag] = { score: data.score, count: data.count };
+      }
+    } else {
+      const patterns = Array.isArray(tagFilter) ? tagFilter : [tagFilter];
+      for (const pattern of patterns) {
+        const regex = globToRegex(pattern);
+        for (const [tag, data] of Object.entries(courseElo.tags)) {
+          if (regex.test(tag)) {
+            result[tag] = { score: data.score, count: data.count };
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
   // ---------------------------------------------------------------------------
   // Card-space diagnostic
   // ---------------------------------------------------------------------------

package/src/core/navigators/PipelineDebugger.ts

@@ -71,6 +71,9 @@ export interface PipelineRunReport {
   courseId: string;
   courseName?: string;
 
+  /** User's global ELO at the time of this pipeline run */
+  userElo?: number;
+
   // Generator phase
   generatorName: string;
   generators?: GeneratorSummary[];
@@ -90,6 +93,8 @@ export 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;
@@ -133,6 +138,17 @@ export function captureRun(report: Omit<PipelineRunReport, 'runId' | 'timestamp'
 /**
  * Build a capture-ready report from pipeline execution data.
  */
+/**
+ * Parse card ELO from the ELO generator's provenance reason string.
+ * Format: "ELO distance XX (card: YYYY, user: ZZZZ), ..."
+ */
+function parseCardElo(provenance: StrategyContribution[]): number | undefined {
+  const eloEntry = provenance.find((p) => p.strategy === 'elo');
+  if (!eloEntry?.reason) return undefined;
+  const match = eloEntry.reason.match(/card:\s*(\d+)/);
+  return match ? parseInt(match[1], 10) : undefined;
+}
+
 export function buildRunReport(
   courseId: string,
   courseName: string | undefined,
@@ -141,7 +157,8 @@ export function buildRunReport(
   generatedCount: number,
   filters: FilterImpact[],
   allCards: WeightedCard[],
-  selectedCards: WeightedCard[]
+  selectedCards: WeightedCard[],
+  userElo?: number
 ): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
   const selectedIds = new Set(selectedCards.map((c) => c.cardId));
 
@@ -150,6 +167,7 @@ export function buildRunReport(
     courseId: card.courseId,
     origin: getOrigin(card),
     finalScore: card.score,
+    cardElo: parseCardElo(card.provenance),
     provenance: card.provenance,
     tags: card.tags,
     selected: selectedIds.has(card.cardId),
@@ -161,6 +179,7 @@ export function buildRunReport(
   return {
     courseId,
     courseName,
+    userElo,
     generatorName,
     generators,
     generatedCount,
@@ -203,6 +222,7 @@ function printRunSummary(run: PipelineRunReport): void {
   console.group(`🔍 Pipeline Run: ${run.courseId} (${run.courseName || 'unnamed'})`);
   logger.info(`Run ID: ${run.runId}`);
   logger.info(`Time: ${run.timestamp.toISOString()}`);
+  logger.info(`User ELO: ${run.userElo ?? 'unknown'}`);
   logger.info(`Generator: ${run.generatorName} → ${run.generatedCount} candidates`);
 
   if (run.generators && run.generators.length > 0) {
@@ -293,8 +313,12 @@ export const pipelineDebugAPI = {
         console.group(`🎴 Card: ${cardId}`);
         logger.info(`Course: ${card.courseId}`);
         logger.info(`Origin: ${card.origin}`);
+        logger.info(`Card ELO: ${card.cardElo ?? 'unknown'} | User ELO: ${run.userElo ?? 'unknown'}`);
         logger.info(`Final score: ${card.finalScore.toFixed(3)}`);
         logger.info(`Selected: ${card.selected ? 'Yes ✅' : 'No ❌'}`);
+        if (card.tags && card.tags.length > 0) {
+          logger.info(`Tags (${card.tags.length}): ${card.tags.join(', ')}`);
+        }
         logger.info('Provenance:');
         logger.info(formatProvenance(card.provenance));
         // eslint-disable-next-line no-console
@@ -492,6 +516,29 @@ export const pipelineDebugAPI = {
     return _activePipeline.diagnoseCardSpace({ threshold });
   },
 
+  /**
+   * 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-*']
+   */
+  async showTagElo(tagFilter?: string | string[]): Promise<void> {
+    if (!_activePipeline) {
+      logger.info('[Pipeline Debug] No active pipeline. Run a session first.');
+      return;
+    }
+    const status = await _activePipeline.getTagEloStatus(tagFilter);
+    const entries = Object.entries(status).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0) {
+      logger.info(`[Pipeline Debug] No tag ELO data found${tagFilter ? ` for pattern: ${tagFilter}` : ''}.`);
+      return;
+    }
+    // eslint-disable-next-line no-console
+    console.table(
+      Object.fromEntries(entries.map(([tag, data]) => [tag, { score: Math.round(data.score), count: data.count }]))
+    );
+  },
+
   /**
    * Show help.
    */
@@ -503,6 +550,7 @@ Commands:
   .showLastRun()         Show summary of most recent pipeline run
   .showRun(id|index)     Show summary of a specific run (by index or ID suffix)
   .showCard(cardId)      Show provenance trail for a specific card
+  .showTagElo(pattern)   Show user's tag ELO data (async). E.g. 'gpc:expose:*'
   .explainReviews()      Analyze why reviews were/weren't selected
   .diagnoseCardSpace()   Scan full card space through filters (async)
   .showRegistry()        Show navigator registry (classes + roles)

package/src/core/navigators/filters/hierarchyDefinition.ts

@@ -30,6 +30,18 @@ interface TagPrerequisite {
    * tagged `gpc:expose:t-T` while `gpc:intro:t-T` is still locked.
    */
   preReqBoost?: number;
+  /**
+   * Score multiplier applied to cards carrying the *gated* tag once the
+   * gate opens (all prereqs met). Ensures newly-unlocked content surfaces
+   * promptly before natural ELO/SRS scoring takes over.
+   *
+   * Falls away naturally as generators stop surfacing the card after
+   * the user interacts with it.
+   *
+   * Example: `targetBoost: 4` on intro-t-T's prerequisite gives a 4×
+   * score increase to intro-t-T cards once their expose gate is met.
+   */
+  targetBoost?: number;
 }
 
 /**
@@ -240,21 +252,68 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
     return boosts;
   }
 
+  /**
+   * Build a map of gated tag → max configured targetBoost for all *open* gates.
+   *
+   * When a gate opens (prereqs met), cards carrying the gated tag get boosted —
+   * ensuring newly-unlocked content surfaces promptly. The boost is a static
+   * multiplier; natural ELO/SRS deprioritization after interaction handles decay.
+   */
+  private getTargetBoosts(unlockedTags: Set<string>): Map<string, number> {
+    const boosts = new Map<string, number>();
+
+    const configKeys = Object.keys(this.config.prerequisites);
+    const unlockedArr = [...unlockedTags];
+    logger.info(
+      `[HierarchyDefinition:targetBoost:trace] ${this.name} | configKeys=${configKeys.length}, unlocked=${unlockedArr.length} (${unlockedArr.slice(0, 5).join(', ')}${unlockedArr.length > 5 ? '...' : ''})`
+    );
+
+    for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+      // Only boost targets of open gates
+      if (!unlockedTags.has(tagId)) continue;
+
+      // TRACE: dump prereq details for unlocked tags
+      logger.info(
+        `[HierarchyDefinition:targetBoost:trace] UNLOCKED ${tagId}: ${prereqs.length} prereqs, raw=${JSON.stringify(prereqs.map(p => ({ tag: p.tag, tb: p.targetBoost })))}`
+      );
+
+      for (const prereq of prereqs) {
+        if (!prereq.targetBoost || prereq.targetBoost <= 1.0) continue;
+
+        const existing = boosts.get(tagId) ?? 1.0;
+        boosts.set(tagId, Math.max(existing, prereq.targetBoost));
+      }
+    }
+
+    if (boosts.size > 0) {
+      logger.info(
+        `[HierarchyDefinition] targetBoosts active: ${[...boosts.entries()].map(([t, b]) => `${t}=×${b}`).join(', ')}`
+      );
+    } else {
+      logger.info(
+        `[HierarchyDefinition:targetBoost:trace] no targetBoosts found despite ${unlockedArr.length} unlocked tags`
+      );
+    }
+
+    return boosts;
+  }
+
   /**
    * CardFilter.transform implementation.
    *
-   * Two effects:
-   * 1. Cards with locked tags receive score * 0.05 (gating penalty)
-   * 2. Cards carrying prereq tags of closed gates receive a configured
-   *    boost (preReqBoost), steering toward content that unlocks gates
+   * Three effects:
+   * 1. Cards with locked tags receive score * 0.02 (gating penalty)
+   * 2. Cards carrying prereq tags of closed gates receive preReqBoost
+   * 3. Cards carrying gated tags of open gates receive targetBoost
    */
   async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
     // Get mastery state
     const masteredTags = await this.getMasteredTags(context);
     const unlockedTags = this.getUnlockedTags(masteredTags);
     const preReqBoosts = this.getPreReqBoosts(unlockedTags, masteredTags);
+    const targetBoosts = this.getTargetBoosts(unlockedTags);
 
-    // Apply prerequisite gating + prereq boosting
+    // Apply prerequisite gating + prereq/target boosting
     const gated: WeightedCard[] = [];
 
     for (const card of cards) {
@@ -293,6 +352,30 @@ export default class HierarchyDefinitionNavigator extends ContentNavigator imple
         }
       }
 
+      // Apply target boost to unlocked cards whose gated tag just opened
+      if (isUnlocked && targetBoosts.size > 0) {
+        const cardTags = card.tags ?? [];
+        let maxTargetBoost = 1.0;
+        const boostedTargets: string[] = [];
+
+        for (const tag of cardTags) {
+          const boost = targetBoosts.get(tag);
+          if (boost && boost > maxTargetBoost) {
+            maxTargetBoost = boost;
+            boostedTargets.push(tag);
+          }
+        }
+
+        if (maxTargetBoost > 1.0) {
+          finalScore *= maxTargetBoost;
+          action = 'boosted';
+          finalReason = `${finalReason} | targetBoost ×${maxTargetBoost.toFixed(2)} for ${boostedTargets.join(', ')}`;
+          logger.info(
+            `[HierarchyDefinition] targetBoost ×${maxTargetBoost.toFixed(2)} applied to card ${card.cardId} via tags [${boostedTargets.join(', ')}] (score: ${card.score.toFixed(3)} → ${finalScore.toFixed(3)})`
+          );
+        }
+      }
+
       gated.push({
         ...card,
         score: finalScore,