@vue-skuilder/db 0.2.4 → 0.2.7

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { D as DataLayerProvider } from './dataLayerProvider-CiA2Rr0v.cjs';
 import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.cjs';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.cjs';
 import { Loggable } from './core/index.cjs';
-export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
+export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.cjs';
 import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
 import { S as StaticCourseManifest } from './types-BFUa1pa3.cjs';
 export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-BFUa1pa3.cjs';
@@ -315,6 +315,21 @@ interface SessionQueueDebug {
     /** cardIDs in queue order, head (next draw) first. */
     cards: string[];
 }
+/**
+ * A card the learner has interacted with this session (one entry per card in
+ * the session record, regardless of which queue — if any — still holds it).
+ */
+interface SessionDrawnCardDebug {
+    cardID: string;
+    /** Queue status at draw time: 'new' | 'review' | 'failed-new' | 'failed-review'. */
+    status: string;
+    /** Number of CardRecords logged for this card this session (≥1). */
+    attempts: number;
+    /** Latest record's correctness; null for non-question (info) records. */
+    correct: boolean | null;
+    /** Total time spent across all of this card's records, in ms. */
+    timeSpentMs: number;
+}
 /** Live snapshot of the controller, read fresh on each overlay tick. */
 interface SessionDebugSnapshot {
     secondsRemaining: number;
@@ -332,6 +347,8 @@ interface SessionDebugSnapshot {
     reviewQ: SessionQueueDebug;
     newQ: SessionQueueDebug;
     failedQ: SessionQueueDebug;
+    /** Every card the learner has interacted with this session, draw order. */
+    drawnCards: SessionDrawnCardDebug[];
 }
 
 /**
@@ -366,6 +383,21 @@ interface ReplanOptions {
      * multiply, require/exclude lists concatenate).
      */
     sessionHints?: ReplanHints;
+    /**
+     * Like `sessionHints`, but *merged* into the existing session-durable hints
+     * (via `mergeHints`) instead of replacing them. Use when emphasis should
+     * *accumulate* across replans rather than clobber — e.g. introducing a second
+     * concept mid-session must not wipe the first concept's boost, nor any
+     * `difficultyBooster`/`conceptBackoff` state on other concepts.
+     *
+     * Merge semantics (see `mergeHints`): boosts MULTIPLY, require/exclude lists
+     * concat-dedup. Re-emphasising the *same* tag therefore compounds — callers
+     * boosting a tag they may have already boosted should clamp at the call site.
+     *
+     * If both `sessionHints` and `mergeSessionHints` are supplied, the replace is
+     * applied first, then the merge — but they are normally mutually exclusive.
+     */
+    mergeSessionHints?: ReplanHints;
     /**
      * Maximum number of new cards to return from the pipeline.
      * Default: 20 (the standard session batch size).
@@ -549,6 +581,21 @@ declare class SessionController<TView = unknown> extends Loggable {
      * recomputed per-run in `_runReplan` and would otherwise go stale.
      */
     private _sessionHints;
+    /**
+     * Card IDs that have been *served* (drawn/consumed) this session. Populated
+     * at the single consumption choke-point (removeItemFromQueue), so it reflects
+     * a draw the instant it happens — earlier than `_sessionRecord`, which only
+     * lands once the card is *responded to*.
+     *
+     * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+     * card shown once must never re-enter newQ this session. This is the general
+     * guard against re-presentation — including the case where a replan in flight
+     * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+     * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+     * legitimately recur and are tracked by their own queues, so this only gates
+     * `new`-origin candidates.
+     */
+    private _servedCardIds;
     /**
      * Consumer-supplied hooks invoked after each question response is processed.
      * Seeded from constructor options (threaded from
@@ -863,6 +910,17 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Remove an item from its source queue after consumption by nextCard().
      */
     private removeItemFromQueue;
+    /**
+     * Remove a satisfied card ID from the durable session-hint `requireCards`
+     * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+     * the card was not a durable requirement.
+     *
+     * Matches literal IDs only: a glob/pattern requirement (which may stand for
+     * several cards) is NOT considered satisfied by a single draw and is left in
+     * place — durable patterns are the caller's responsibility, one-shot `hints`
+     * remain the right tool for them.
+     */
+    private _clearDurableRequirement;
     /**
      * End the session and record learning outcomes.
      *

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { D as DataLayerProvider } from './dataLayerProvider-DrBqOUa3.js';
 import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.js';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.js';
 import { Loggable } from './core/index.js';
-export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.js';
+export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, DIVERSITY_FLOOR, DIVERSITY_STRENGTH, DiversityRerankOptions, FilterContext, FilterImpact, GeneratorSummary, GradientObservation, GradientResult, ImportResult, PeriodUpdateInput, PeriodUpdateResult, PipelineRunReport, SignalConfig, StrategyLearningState, StrategyStateDoc, StrategyStateId, aggregateOutcomesForGradient, areQuestionRecords, buildStrategyStateId, computeOutcomeSignal, computeStrategyGradient, diversityRerank, docIsDeleted, getCardHistoryID, getDefaultLearnableWeight, importParsedCards, isQuestionRecord, mountPipelineDebugger, mountUserDBDebugger, parseCardHistoryID, pipelineDebugAPI, recordUserOutcome, runPeriodUpdate, scoreAccuracyInZone, updateLearningState, updateStrategyWeight, userDBDebugAPI, validateProcessorConfig } from './core/index.js';
 import { TaggedPerformance, TagFilter, DataShape, CourseConfig } from '@vue-skuilder/common';
 import { S as StaticCourseManifest } from './types-CHgpWQAY.js';
 export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CHgpWQAY.js';
@@ -315,6 +315,21 @@ interface SessionQueueDebug {
     /** cardIDs in queue order, head (next draw) first. */
     cards: string[];
 }
+/**
+ * A card the learner has interacted with this session (one entry per card in
+ * the session record, regardless of which queue — if any — still holds it).
+ */
+interface SessionDrawnCardDebug {
+    cardID: string;
+    /** Queue status at draw time: 'new' | 'review' | 'failed-new' | 'failed-review'. */
+    status: string;
+    /** Number of CardRecords logged for this card this session (≥1). */
+    attempts: number;
+    /** Latest record's correctness; null for non-question (info) records. */
+    correct: boolean | null;
+    /** Total time spent across all of this card's records, in ms. */
+    timeSpentMs: number;
+}
 /** Live snapshot of the controller, read fresh on each overlay tick. */
 interface SessionDebugSnapshot {
     secondsRemaining: number;
@@ -332,6 +347,8 @@ interface SessionDebugSnapshot {
     reviewQ: SessionQueueDebug;
     newQ: SessionQueueDebug;
     failedQ: SessionQueueDebug;
+    /** Every card the learner has interacted with this session, draw order. */
+    drawnCards: SessionDrawnCardDebug[];
 }
 
 /**
@@ -366,6 +383,21 @@ interface ReplanOptions {
      * multiply, require/exclude lists concatenate).
      */
     sessionHints?: ReplanHints;
+    /**
+     * Like `sessionHints`, but *merged* into the existing session-durable hints
+     * (via `mergeHints`) instead of replacing them. Use when emphasis should
+     * *accumulate* across replans rather than clobber — e.g. introducing a second
+     * concept mid-session must not wipe the first concept's boost, nor any
+     * `difficultyBooster`/`conceptBackoff` state on other concepts.
+     *
+     * Merge semantics (see `mergeHints`): boosts MULTIPLY, require/exclude lists
+     * concat-dedup. Re-emphasising the *same* tag therefore compounds — callers
+     * boosting a tag they may have already boosted should clamp at the call site.
+     *
+     * If both `sessionHints` and `mergeSessionHints` are supplied, the replace is
+     * applied first, then the merge — but they are normally mutually exclusive.
+     */
+    mergeSessionHints?: ReplanHints;
     /**
      * Maximum number of new cards to return from the pipeline.
      * Default: 20 (the standard session batch size).
@@ -549,6 +581,21 @@ declare class SessionController<TView = unknown> extends Loggable {
      * recomputed per-run in `_runReplan` and would otherwise go stale.
      */
     private _sessionHints;
+    /**
+     * Card IDs that have been *served* (drawn/consumed) this session. Populated
+     * at the single consumption choke-point (removeItemFromQueue), so it reflects
+     * a draw the instant it happens — earlier than `_sessionRecord`, which only
+     * lands once the card is *responded to*.
+     *
+     * Used to keep already-served cards out of newQ on every (re)plan: a `new`
+     * card shown once must never re-enter newQ this session. This is the general
+     * guard against re-presentation — including the case where a replan in flight
+     * captured a now-drawn card (e.g. a +INF require-injected follow-up the
+     * depletion prefetch grabbed just before it was drawn). Reviews/failed cards
+     * legitimately recur and are tracked by their own queues, so this only gates
+     * `new`-origin candidates.
+     */
+    private _servedCardIds;
     /**
      * Consumer-supplied hooks invoked after each question response is processed.
      * Seeded from constructor options (threaded from
@@ -863,6 +910,17 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Remove an item from its source queue after consumption by nextCard().
      */
     private removeItemFromQueue;
+    /**
+     * Remove a satisfied card ID from the durable session-hint `requireCards`
+     * list. Called when a card is consumed (see removeItemFromQueue). No-op if
+     * the card was not a durable requirement.
+     *
+     * Matches literal IDs only: a glob/pattern requirement (which may stand for
+     * several cards) is NOT considered satisfied by a single draw and is left in
+     * place — durable patterns are the caller's responsibility, one-shot `hints`
+     * remain the right tool for them.
+     */
+    private _clearDurableRequirement;
     /**
      * End the session and record learning outcomes.
      *