@vue-skuilder/db 0.2.3 → 0.2.5

package/dist/index.d.cts

@@ -308,6 +308,49 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/** Per-queue debug view: total length, cumulative draws, and head-first cardIDs. */
+interface SessionQueueDebug {
+    length: number;
+    dequeueCount: number;
+    /** 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;
+    hasCardGuarantee: boolean;
+    minCardsGuarantee: number;
+    wellIndicatedRemaining: number;
+    /** cardID of the card currently in front of the learner, if any. */
+    currentCard: string | null;
+    /** Session-durable hints re-merged into every pipeline run this session. */
+    sessionHints: ReplanHints | null;
+    /** True while a replan is executing (in-flight). */
+    replanActive: boolean;
+    /** Reason for the in-flight replan (caller label, or '(auto)'); may be stale when idle. */
+    replanLabel: string | null;
+    reviewQ: SessionQueueDebug;
+    newQ: SessionQueueDebug;
+    failedQ: SessionQueueDebug;
+    /** Every card the learner has interacted with this session, draw order. */
+    drawnCards: SessionDrawnCardDebug[];
+}
+
 /**
  * Options for requesting a mid-session replan.
  *
@@ -340,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).
@@ -482,6 +540,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by nextCard() to await completion before drawing from queues.
      */
     private _replanPromise;
+    /**
+     * Reason for the replan currently executing in `_runReplan`, surfaced by the
+     * debug overlay's spinner. The caller's `opts.label` when present, else
+     * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+     * when the in-flight chain settles.
+     */
+    private _activeReplanLabel;
     /**
      * Number of well-indicated new cards remaining before the queue
      * degrades to poorly-indicated content. Decremented on each newQ
@@ -516,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
@@ -637,6 +717,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * e.g. an outcome observer that clamps a compounding boost).
      */
     getSessionHints(): ReplanHints | null;
+    /**
+     * Live state snapshot for the debug overlay (window.skuilder.session
+     * .dbgOverlay()). Reads directly from the private queues and hints, so it
+     * always reflects the current moment — unlike the passive SessionDebugger
+     * snapshots, which only capture what was explicitly pushed to them.
+     */
+    getDebugSnapshot(): SessionDebugSnapshot;
     /**
      * Merge `hints` into the durable session hints via the pipeline's
      * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
@@ -823,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.
      *
@@ -1060,6 +1158,11 @@ declare const sessionDebugAPI: {
      * Show current queue state.
      */
     showQueue(): void;
+    /**
+     * Toggle the pinned, live-updating DOM overlay for the active controller
+     * (queues, session hints, timer). No-ops in non-browser hosts.
+     */
+    dbgOverlay(): void;
     /**
      * Show presentation history for current or past session.
      */

package/dist/index.d.ts

@@ -308,6 +308,49 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/** Per-queue debug view: total length, cumulative draws, and head-first cardIDs. */
+interface SessionQueueDebug {
+    length: number;
+    dequeueCount: number;
+    /** 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;
+    hasCardGuarantee: boolean;
+    minCardsGuarantee: number;
+    wellIndicatedRemaining: number;
+    /** cardID of the card currently in front of the learner, if any. */
+    currentCard: string | null;
+    /** Session-durable hints re-merged into every pipeline run this session. */
+    sessionHints: ReplanHints | null;
+    /** True while a replan is executing (in-flight). */
+    replanActive: boolean;
+    /** Reason for the in-flight replan (caller label, or '(auto)'); may be stale when idle. */
+    replanLabel: string | null;
+    reviewQ: SessionQueueDebug;
+    newQ: SessionQueueDebug;
+    failedQ: SessionQueueDebug;
+    /** Every card the learner has interacted with this session, draw order. */
+    drawnCards: SessionDrawnCardDebug[];
+}
+
 /**
  * Options for requesting a mid-session replan.
  *
@@ -340,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).
@@ -482,6 +540,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by nextCard() to await completion before drawing from queues.
      */
     private _replanPromise;
+    /**
+     * Reason for the replan currently executing in `_runReplan`, surfaced by the
+     * debug overlay's spinner. The caller's `opts.label` when present, else
+     * `'(auto)'`. Only meaningful while `_replanPromise` is non-null; cleared
+     * when the in-flight chain settles.
+     */
+    private _activeReplanLabel;
     /**
      * Number of well-indicated new cards remaining before the queue
      * degrades to poorly-indicated content. Decremented on each newQ
@@ -516,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
@@ -637,6 +717,13 @@ declare class SessionController<TView = unknown> extends Loggable {
      * e.g. an outcome observer that clamps a compounding boost).
      */
     getSessionHints(): ReplanHints | null;
+    /**
+     * Live state snapshot for the debug overlay (window.skuilder.session
+     * .dbgOverlay()). Reads directly from the private queues and hints, so it
+     * always reflects the current moment — unlike the passive SessionDebugger
+     * snapshots, which only capture what was explicitly pushed to them.
+     */
+    getDebugSnapshot(): SessionDebugSnapshot;
     /**
      * Merge `hints` into the durable session hints via the pipeline's
      * `mergeHints` (boosts multiply, require/exclude lists concat-dedup).
@@ -823,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.
      *
@@ -1060,6 +1158,11 @@ declare const sessionDebugAPI: {
      * Show current queue state.
      */
     showQueue(): void;
+    /**
+     * Toggle the pinned, live-updating DOM overlay for the active controller
+     * (queues, session hints, timer). No-ops in non-browser hosts.
+     */
+    dbgOverlay(): void;
     /**
      * Show presentation history for current or past session.
      */