@vibe-hero/server 0.1.0

package/dist/engine/graduation.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @file PURE tier-graduation engine with hysteresis + dwell (T043, US-3).
+ *
+ * Decides whether a learner graduates to a higher tier, is demoted/flagged for
+ * review, or stays put, given their current ability θ, their current graduated
+ * tier, and a DWELL counter of how many *consecutive* recent graded items have
+ * satisfied the same crossing condition. The hysteresis band (FR-008 / SC-014)
+ * plus the dwell requirement together prevent a single fluke item — or ability
+ * oscillating within ±margin of a boundary — from toggling the tier.
+ *
+ * This module is IO-FREE and time-free (invariant E5): it reads no clock, no
+ * filesystem, no network, and never calls `Math.random`. All inputs are passed
+ * explicitly; the same inputs always yield the same decision. Time-dependent
+ * lapse/staleness lives in `./lapse.ts`; tools read the clock and pass it in.
+ *
+ * Rules (OD-005 / research.md):
+ *   - PROMOTE to the next tier when θ ≥ (next boundary) + hysteresisMargin AND
+ *     this promotion-crossing condition has held for `dwell` consecutive graded
+ *     items (a single qualifying item is never enough — SC-014).
+ *   - DEMOTE / flag for review when θ ≤ (boundary below the current tier) −
+ *     hysteresisMargin. Demotion is immediate (no dwell): a confirmed drop below
+ *     the lower band should surface the topic promptly rather than hide a lapse.
+ *   - Otherwise NO change — in particular, ability anywhere inside the band
+ *     `[boundaryBelow − margin, nextBoundary + margin]` leaves the tier alone.
+ *
+ * Dwell tracking (see {@link evaluateGraduation}): the caller persists a small
+ * `dwell` counter on the AbilityEstimate. On each graded item the engine returns
+ * the *next* dwell value: it increments while the promotion-crossing condition
+ * holds and resets to 0 the moment an item fails to satisfy it. Promotion fires
+ * only when the (incremented) counter reaches `ASSESSMENT_CONFIG.dwell`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-007/008/008a/009,
+ * SC-010/SC-014), research.md (OD-005), data-model.md (TierGraduation).
+ */
+import type { Tier } from "../schemas/common.js";
+/** A graduated tier, or `0` for "not yet graduated". */
+export type TierOrZero = Tier | 0;
+/**
+ * Why the tier changed (or why review is due). Mirrors
+ * `TierGraduation.lastChangeReason`; `null` when nothing changed this item.
+ */
+export type GraduationChangeReason = "graduated" | "demoted" | "review_due" | null;
+/** The inputs the pure graduation evaluation needs. */
+export interface GraduationState {
+    /** The learner's current ability estimate (θ) AFTER the latest Elo update. */
+    readonly ability: number;
+    /**
+     * The tier the learner is currently graduated at (`0` = none yet). Drives
+     * which boundaries bound the hysteresis band.
+     */
+    readonly currentTier: TierOrZero;
+    /**
+     * Consecutive graded items (BEFORE this one) for which the promotion-crossing
+     * condition held. The engine increments this when the current item also
+     * satisfies promotion, and resets it to 0 otherwise. Persisted on the
+     * AbilityEstimate so dwell carries across `submit_answer` calls.
+     */
+    readonly dwell: number;
+}
+/** The decision returned by {@link evaluateGraduation} (pure, total). */
+export interface GraduationDecision {
+    /** Whether the tier (or review status) changed as a result of this item. */
+    readonly changed: boolean;
+    /** The new tier after applying the decision (unchanged when `changed` is false). */
+    readonly tier: TierOrZero;
+    /** The reason for the change, or `null` when nothing changed. */
+    readonly reason: GraduationChangeReason;
+    /**
+     * The dwell counter to persist for the NEXT evaluation. Incremented while the
+     * promotion-crossing condition holds; reset to 0 the moment it does not (and
+     * after a promotion fires, so the next tier starts fresh).
+     */
+    readonly dwell: number;
+    /**
+     * When `reason === "demoted"`, whether the drop should be surfaced as
+     * `due_for_review` (the spec demotes *to review* rather than silently
+     * un-graduating — FR-009). Always `true` for a demotion; `false` otherwise.
+     */
+    readonly dueForReview: boolean;
+}
+/**
+ * Decide the graduation outcome for one graded item (PURE, total).
+ *
+ * Evaluation order, given ability θ, `currentTier`, and the prior `dwell`:
+ *
+ *  1. **Promotion check** — if there is a tier above and
+ *     `θ ≥ boundaryAbove + hysteresisMargin`, the promotion-crossing condition
+ *     holds: the dwell counter is incremented. When it reaches
+ *     `ASSESSMENT_CONFIG.dwell`, promote (reason `"graduated"`, dwell reset to
+ *     0). If it has not yet reached `dwell`, NO change is reported but the
+ *     incremented counter is returned so the streak is remembered.
+ *  2. **Demotion check** — else, if the learner is graduated and
+ *     `θ ≤ boundaryBelow − hysteresisMargin`, demote/flag for review (reason
+ *     `"demoted"`, `dueForReview: true`, tier steps down one). Demotion does not
+ *     require dwell and resets the counter to 0.
+ *  3. **No change** — otherwise the tier holds (ability is inside the band or
+ *     promotion has insufficient dwell). The dwell counter resets to 0 because
+ *     this item did NOT satisfy the promotion-crossing condition.
+ *
+ * Because promotion needs `dwell` consecutive qualifying items and demotion
+ * needs a clear `margin` below the lower boundary, ability oscillating inside
+ * the band never toggles the tier (SC-014).
+ *
+ * @param state - {@link GraduationState}: current ability, tier, and prior dwell.
+ * @returns A {@link GraduationDecision}; `changed: false` leaves tier untouched.
+ */
+export declare const evaluateGraduation: (state: GraduationState) => GraduationDecision;
+//# sourceMappingURL=graduation.d.ts.map

package/dist/engine/graduation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graduation.d.ts","sourceRoot":"","sources":["../../src/engine/graduation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC9B,WAAW,GACX,SAAS,GACT,YAAY,GACZ,IAAI,CAAC;AAET,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,eAAe,KACrB,kBA4DF,CAAC"}

package/dist/engine/graduation.js

@@ -0,0 +1,161 @@
+/**
+ * @file PURE tier-graduation engine with hysteresis + dwell (T043, US-3).
+ *
+ * Decides whether a learner graduates to a higher tier, is demoted/flagged for
+ * review, or stays put, given their current ability θ, their current graduated
+ * tier, and a DWELL counter of how many *consecutive* recent graded items have
+ * satisfied the same crossing condition. The hysteresis band (FR-008 / SC-014)
+ * plus the dwell requirement together prevent a single fluke item — or ability
+ * oscillating within ±margin of a boundary — from toggling the tier.
+ *
+ * This module is IO-FREE and time-free (invariant E5): it reads no clock, no
+ * filesystem, no network, and never calls `Math.random`. All inputs are passed
+ * explicitly; the same inputs always yield the same decision. Time-dependent
+ * lapse/staleness lives in `./lapse.ts`; tools read the clock and pass it in.
+ *
+ * Rules (OD-005 / research.md):
+ *   - PROMOTE to the next tier when θ ≥ (next boundary) + hysteresisMargin AND
+ *     this promotion-crossing condition has held for `dwell` consecutive graded
+ *     items (a single qualifying item is never enough — SC-014).
+ *   - DEMOTE / flag for review when θ ≤ (boundary below the current tier) −
+ *     hysteresisMargin. Demotion is immediate (no dwell): a confirmed drop below
+ *     the lower band should surface the topic promptly rather than hide a lapse.
+ *   - Otherwise NO change — in particular, ability anywhere inside the band
+ *     `[boundaryBelow − margin, nextBoundary + margin]` leaves the tier alone.
+ *
+ * Dwell tracking (see {@link evaluateGraduation}): the caller persists a small
+ * `dwell` counter on the AbilityEstimate. On each graded item the engine returns
+ * the *next* dwell value: it increments while the promotion-crossing condition
+ * holds and resets to 0 the moment an item fails to satisfy it. Promotion fires
+ * only when the (incremented) counter reaches `ASSESSMENT_CONFIG.dwell`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-007/008/008a/009,
+ * SC-010/SC-014), research.md (OD-005), data-model.md (TierGraduation).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+/** Sorted tier ladder (`[100,200,300,400,500]`), typed as {@link Tier}. */
+const TIERS = ASSESSMENT_CONFIG.tierCenters;
+/**
+ * The boundary the learner must clear (plus margin) to graduate FROM
+ * `currentTier` to the next one, or `undefined` if already at the top tier
+ * (500) — there is nothing higher to promote into.
+ *
+ * Boundaries are `[150,250,350,450]`; the boundary above tier `T` is the one
+ * sitting between `T` and the next center (e.g. above tier 300 ⇒ 350, the bar
+ * into tier 400). For `currentTier === 0` (not graduated) the relevant boundary
+ * is the first one (150), the bar into tier 100.
+ */
+const boundaryAbove = (currentTier) => {
+    const { tierBoundaries } = ASSESSMENT_CONFIG;
+    if (currentTier === 0)
+        return tierBoundaries[0];
+    const idx = TIERS.indexOf(currentTier);
+    // idx is the index of the current center; the boundary into the NEXT tier is
+    // at the same index in tierBoundaries (centers[i] → boundaries[i] → centers[i+1]).
+    return tierBoundaries[idx];
+};
+/**
+ * The boundary BELOW the current tier — the floor of the hysteresis band; a
+ * drop of `margin` below it triggers demotion/review. `undefined` when the
+ * learner is not graduated (`currentTier === 0`): there is no lower band, so a
+ * non-graduate can never be demoted.
+ *
+ * The boundary below tier `T` sits between the previous center and `T` (e.g.
+ * below tier 300 ⇒ 250, the bar that was crossed to enter tier 300).
+ */
+const boundaryBelow = (currentTier) => {
+    const { tierBoundaries } = ASSESSMENT_CONFIG;
+    if (currentTier === 0)
+        return undefined;
+    const idx = TIERS.indexOf(currentTier);
+    // centers[i] is bounded below by boundaries[i-1].
+    return idx > 0 ? tierBoundaries[idx - 1] : undefined;
+};
+/** The tier one step above `currentTier`, or `undefined` at the top (500). */
+const nextTier = (currentTier) => {
+    if (currentTier === 0)
+        return TIERS[0];
+    const idx = TIERS.indexOf(currentTier);
+    return TIERS[idx + 1];
+};
+/**
+ * Decide the graduation outcome for one graded item (PURE, total).
+ *
+ * Evaluation order, given ability θ, `currentTier`, and the prior `dwell`:
+ *
+ *  1. **Promotion check** — if there is a tier above and
+ *     `θ ≥ boundaryAbove + hysteresisMargin`, the promotion-crossing condition
+ *     holds: the dwell counter is incremented. When it reaches
+ *     `ASSESSMENT_CONFIG.dwell`, promote (reason `"graduated"`, dwell reset to
+ *     0). If it has not yet reached `dwell`, NO change is reported but the
+ *     incremented counter is returned so the streak is remembered.
+ *  2. **Demotion check** — else, if the learner is graduated and
+ *     `θ ≤ boundaryBelow − hysteresisMargin`, demote/flag for review (reason
+ *     `"demoted"`, `dueForReview: true`, tier steps down one). Demotion does not
+ *     require dwell and resets the counter to 0.
+ *  3. **No change** — otherwise the tier holds (ability is inside the band or
+ *     promotion has insufficient dwell). The dwell counter resets to 0 because
+ *     this item did NOT satisfy the promotion-crossing condition.
+ *
+ * Because promotion needs `dwell` consecutive qualifying items and demotion
+ * needs a clear `margin` below the lower boundary, ability oscillating inside
+ * the band never toggles the tier (SC-014).
+ *
+ * @param state - {@link GraduationState}: current ability, tier, and prior dwell.
+ * @returns A {@link GraduationDecision}; `changed: false` leaves tier untouched.
+ */
+export const evaluateGraduation = (state) => {
+    const { ability, currentTier, dwell } = state;
+    const { hysteresisMargin, dwell: dwellTarget } = ASSESSMENT_CONFIG;
+    // --- 1. Promotion -------------------------------------------------------
+    const promoteBar = boundaryAbove(currentTier);
+    const target = nextTier(currentTier);
+    if (promoteBar !== undefined &&
+        target !== undefined &&
+        ability >= promoteBar + hysteresisMargin) {
+        const nextDwell = dwell + 1;
+        if (nextDwell >= dwellTarget) {
+            // Streak satisfied → graduate, reset dwell for the new tier.
+            return {
+                changed: true,
+                tier: target,
+                reason: "graduated",
+                dwell: 0,
+                dueForReview: false,
+            };
+        }
+        // Crossing held but dwell not yet met: remember the streak, no change.
+        return {
+            changed: false,
+            tier: currentTier,
+            reason: null,
+            dwell: nextDwell,
+            dueForReview: false,
+        };
+    }
+    // --- 2. Demotion / review (only when graduated) -------------------------
+    const demoteFloor = boundaryBelow(currentTier);
+    if (currentTier !== 0 &&
+        demoteFloor !== undefined &&
+        ability <= demoteFloor - hysteresisMargin) {
+        const idx = TIERS.indexOf(currentTier);
+        const lower = idx > 0 ? TIERS[idx - 1] : 0;
+        return {
+            changed: true,
+            tier: lower,
+            reason: "demoted",
+            dwell: 0,
+            dueForReview: true,
+        };
+    }
+    // --- 3. No change (inside the band, or promotion lacked dwell) ----------
+    // This item did not satisfy promotion, so the consecutive streak resets.
+    return {
+        changed: false,
+        tier: currentTier,
+        reason: null,
+        dwell: 0,
+        dueForReview: false,
+    };
+};
+//# sourceMappingURL=graduation.js.map

package/dist/engine/graduation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graduation.js","sourceRoot":"","sources":["../../src/engine/graduation.ts"],"names":[],"mappings":"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"}

package/dist/engine/lapse.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file PURE knowledge-lapse / staleness engine (T044, US-3, OD-003).
+ *
+ * Implements the "staleness threshold + exponential ability decay" review model
+ * (research.md OD-003) without any separate per-item scheduler: it reuses the
+ * Elo ability already stored on the profile and decays it toward the tier center
+ * over calendar time, then asks whether a previously-graduated topic has gone
+ * stale enough to surface for review (FR-009 / FR-010).
+ *
+ * The decay is PURE math; the only "time" input is `daysSinceLast` /
+ * explicit timestamps, which the CALLER computes from an injected `now` (E5 —
+ * the engine itself never reads the clock). Tools read `new Date()` and pass it
+ * in; the engine stays deterministic and unit-testable.
+ *
+ * Model (research.md OD-003):
+ *   θ_effective(t) = tier_center + (θ_last − tier_center) · exp(−daysSinceLast / H)
+ *   H = decayHalfLifeDays (60d; tier-tunable)
+ *   due_for_review  ⟺  daysSinceLast ≥ stalenessWindowDays
+ *                      AND θ_effective < (tier_boundary_below + hysteresisMargin)
+ *
+ * A correct review resets the clock (lastAssessedAt) and restores ability; a
+ * wrong review lets normal Elo demote — both handled by the submit path, not
+ * here. This module only *detects* the due-for-review condition.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-003), spec.md
+ * FR-009/FR-010, config.ts (decayHalfLifeDays, stalenessWindowDays).
+ */
+import type { AbilityEstimate, TierGraduation } from "../schemas/profile.js";
+/**
+ * Whole/fractional days between two ISO timestamps (`now − then`), clamped at 0
+ * so a clock skew or future `lastAssessedAt` never yields a negative age. PURE:
+ * both instants are passed in; the engine reads no clock itself.
+ *
+ * @param then - The earlier ISO datetime (e.g. `lastAssessedAt`).
+ * @param now - The reference ISO datetime (injected by the caller).
+ * @returns Days elapsed, ≥ 0.
+ */
+export declare const daysBetween: (then: string, now: string) => number;
+/**
+ * Exponentially-decayed effective ability (PURE).
+ *
+ * `θ_effective = tierCenter + (θ_last − tierCenter) · exp(−daysSinceLast / H)`.
+ *
+ * Ability relaxes toward the tier center as time passes: a learner who graduated
+ * *well above* center decays downward, and one who was *just* above center barely
+ * moves. At `daysSinceLast = 0` the result equals `θ_last`; as days → ∞ it tends
+ * to `tierCenter`. Negative `daysSinceLast` is treated as 0 (no decay).
+ *
+ * @param lastAbility - The stored ability at last assessment (θ_last).
+ * @param center - The tier center to decay toward (see {@link tierCenter}).
+ * @param daysSinceLast - Days since the last assessment (≥ 0).
+ * @param halfLifeDays - Decay constant `H` in days
+ *   (default {@link ASSESSMENT_CONFIG.decayHalfLifeDays}).
+ * @returns The decayed effective ability.
+ */
+export declare const effectiveAbility: (lastAbility: number, center: number, daysSinceLast: number, halfLifeDays?: number) => number;
+/**
+ * Whether a graduated topic is now due for review (PURE; clock injected as
+ * `now`). Implements OD-003:
+ *
+ *   `daysSinceLast ≥ stalenessWindowDays`
+ *   AND `effectiveAbility < (boundaryBelow(currentTier) + hysteresisMargin)`
+ *
+ * Returns `false` for an ungraduated topic (`currentTier === 0`) — there is
+ * nothing to lapse from — and for a topic already flagged `due_for_review`
+ * (idempotent: it is already surfaced, so re-flagging is a no-op decision).
+ *
+ * The two-part test means a topic only surfaces when it is BOTH stale (enough
+ * time has passed) AND its decayed ability has fallen near/under the tier's
+ * lower band. A frequently-practiced or comfortably-above-center topic never
+ * goes due.
+ *
+ * @param graduation - The topic's graduation state (tier + status).
+ * @param ability - The stored ability estimate (its `value` and
+ *   `lastAssessedAt` drive decay + staleness).
+ * @param now - The reference ISO datetime, injected by the caller (E5).
+ * @returns `true` iff the topic should be surfaced for review.
+ */
+export declare const isDueForReview: (graduation: TierGraduation, ability: AbilityEstimate, now: string) => boolean;
+//# sourceMappingURL=lapse.d.ts.map

package/dist/engine/lapse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lapse.d.ts","sourceRoot":"","sources":["../../src/engine/lapse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ7E;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,KAAG,MAKvD,CAAC;AAwBF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,MAAM,EACnB,QAAQ,MAAM,EACd,eAAe,MAAM,EACrB,eAAc,MAA4C,KACzD,MAIF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GACzB,YAAY,cAAc,EAC1B,SAAS,eAAe,EACxB,KAAK,MAAM,KACV,OAYF,CAAC"}

package/dist/engine/lapse.js

@@ -0,0 +1,125 @@
+/**
+ * @file PURE knowledge-lapse / staleness engine (T044, US-3, OD-003).
+ *
+ * Implements the "staleness threshold + exponential ability decay" review model
+ * (research.md OD-003) without any separate per-item scheduler: it reuses the
+ * Elo ability already stored on the profile and decays it toward the tier center
+ * over calendar time, then asks whether a previously-graduated topic has gone
+ * stale enough to surface for review (FR-009 / FR-010).
+ *
+ * The decay is PURE math; the only "time" input is `daysSinceLast` /
+ * explicit timestamps, which the CALLER computes from an injected `now` (E5 —
+ * the engine itself never reads the clock). Tools read `new Date()` and pass it
+ * in; the engine stays deterministic and unit-testable.
+ *
+ * Model (research.md OD-003):
+ *   θ_effective(t) = tier_center + (θ_last − tier_center) · exp(−daysSinceLast / H)
+ *   H = decayHalfLifeDays (60d; tier-tunable)
+ *   due_for_review  ⟺  daysSinceLast ≥ stalenessWindowDays
+ *                      AND θ_effective < (tier_boundary_below + hysteresisMargin)
+ *
+ * A correct review resets the clock (lastAssessedAt) and restores ability; a
+ * wrong review lets normal Elo demote — both handled by the submit path, not
+ * here. This module only *detects* the due-for-review condition.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-003), spec.md
+ * FR-009/FR-010, config.ts (decayHalfLifeDays, stalenessWindowDays).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+/** Milliseconds in one day (UTC), for date-difference math. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Sorted tier ladder (`[100,200,300,400,500]`), typed as {@link Tier}. */
+const TIERS = ASSESSMENT_CONFIG.tierCenters;
+/**
+ * Whole/fractional days between two ISO timestamps (`now − then`), clamped at 0
+ * so a clock skew or future `lastAssessedAt` never yields a negative age. PURE:
+ * both instants are passed in; the engine reads no clock itself.
+ *
+ * @param then - The earlier ISO datetime (e.g. `lastAssessedAt`).
+ * @param now - The reference ISO datetime (injected by the caller).
+ * @returns Days elapsed, ≥ 0.
+ */
+export const daysBetween = (then, now) => {
+    const thenMs = Date.parse(then);
+    const nowMs = Date.parse(now);
+    if (Number.isNaN(thenMs) || Number.isNaN(nowMs))
+        return 0;
+    return Math.max(0, (nowMs - thenMs) / MS_PER_DAY);
+};
+/**
+ * The center ability of a tier (e.g. tier 300 → 300). For `currentTier === 0`
+ * (not graduated) decay has no meaningful center, so we fall back to the
+ * cold-start ability — but lapse only ever runs on graduated topics, so this
+ * branch is defensive.
+ */
+const tierCenter = (currentTier) => currentTier === 0 ? ASSESSMENT_CONFIG.startingAbility : currentTier;
+/**
+ * The boundary BELOW a graduated tier — the floor used in the due-for-review
+ * test (`θ_effective < boundaryBelow + margin`). Below tier `T` sits the
+ * boundary between the previous center and `T` (e.g. below 300 ⇒ 250). For tier
+ * 100 (the lowest) there is no lower boundary; we use `0` so the only way a
+ * tier-100 topic goes due is by decaying below the margin near the floor.
+ */
+const boundaryBelow = (currentTier) => {
+    const idx = TIERS.indexOf(currentTier);
+    const { tierBoundaries } = ASSESSMENT_CONFIG;
+    return idx > 0 ? (tierBoundaries[idx - 1] ?? 0) : 0;
+};
+/**
+ * Exponentially-decayed effective ability (PURE).
+ *
+ * `θ_effective = tierCenter + (θ_last − tierCenter) · exp(−daysSinceLast / H)`.
+ *
+ * Ability relaxes toward the tier center as time passes: a learner who graduated
+ * *well above* center decays downward, and one who was *just* above center barely
+ * moves. At `daysSinceLast = 0` the result equals `θ_last`; as days → ∞ it tends
+ * to `tierCenter`. Negative `daysSinceLast` is treated as 0 (no decay).
+ *
+ * @param lastAbility - The stored ability at last assessment (θ_last).
+ * @param center - The tier center to decay toward (see {@link tierCenter}).
+ * @param daysSinceLast - Days since the last assessment (≥ 0).
+ * @param halfLifeDays - Decay constant `H` in days
+ *   (default {@link ASSESSMENT_CONFIG.decayHalfLifeDays}).
+ * @returns The decayed effective ability.
+ */
+export const effectiveAbility = (lastAbility, center, daysSinceLast, halfLifeDays = ASSESSMENT_CONFIG.decayHalfLifeDays) => {
+    const days = Math.max(0, daysSinceLast);
+    const decay = Math.exp(-days / halfLifeDays);
+    return center + (lastAbility - center) * decay;
+};
+/**
+ * Whether a graduated topic is now due for review (PURE; clock injected as
+ * `now`). Implements OD-003:
+ *
+ *   `daysSinceLast ≥ stalenessWindowDays`
+ *   AND `effectiveAbility < (boundaryBelow(currentTier) + hysteresisMargin)`
+ *
+ * Returns `false` for an ungraduated topic (`currentTier === 0`) — there is
+ * nothing to lapse from — and for a topic already flagged `due_for_review`
+ * (idempotent: it is already surfaced, so re-flagging is a no-op decision).
+ *
+ * The two-part test means a topic only surfaces when it is BOTH stale (enough
+ * time has passed) AND its decayed ability has fallen near/under the tier's
+ * lower band. A frequently-practiced or comfortably-above-center topic never
+ * goes due.
+ *
+ * @param graduation - The topic's graduation state (tier + status).
+ * @param ability - The stored ability estimate (its `value` and
+ *   `lastAssessedAt` drive decay + staleness).
+ * @param now - The reference ISO datetime, injected by the caller (E5).
+ * @returns `true` iff the topic should be surfaced for review.
+ */
+export const isDueForReview = (graduation, ability, now) => {
+    if (graduation.currentTier === 0)
+        return false;
+    if (graduation.status === "due_for_review")
+        return false;
+    const daysSinceLast = daysBetween(ability.lastAssessedAt, now);
+    if (daysSinceLast < ASSESSMENT_CONFIG.stalenessWindowDays)
+        return false;
+    const center = tierCenter(graduation.currentTier);
+    const effective = effectiveAbility(ability.value, center, daysSinceLast);
+    const floor = boundaryBelow(graduation.currentTier) + ASSESSMENT_CONFIG.hysteresisMargin;
+    return effective < floor;
+};
+//# sourceMappingURL=lapse.js.map

package/dist/engine/lapse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lapse.js","sourceRoot":"","sources":["../../src/engine/lapse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAIjD,+DAA+D;AAC/D,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,KAAK,GAAoB,iBAAiB,CAAC,WAA8B,CAAC;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CAAC,WAAqB,EAAU,EAAE,CACnD,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,aAAa,GAAG,CAAC,WAAiB,EAAU,EAAE;IAClD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,EAAE,cAAc,EAAE,GAAG,iBAAiB,CAAC;IAC7C,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,WAAmB,EACnB,MAAc,EACd,aAAqB,EACrB,eAAuB,iBAAiB,CAAC,iBAAiB,EAClD,EAAE;IACV,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;IAC7C,OAAO,MAAM,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC;AACjD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,UAA0B,EAC1B,OAAwB,EACxB,GAAW,EACF,EAAE;IACX,IAAI,UAAU,CAAC,WAAW,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,UAAU,CAAC,MAAM,KAAK,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAEzD,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IAC/D,IAAI,aAAa,GAAG,iBAAiB,CAAC,mBAAmB;QAAE,OAAO,KAAK,CAAC;IAExE,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IACzE,MAAM,KAAK,GACT,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,iBAAiB,CAAC,gBAAgB,CAAC;IAC7E,OAAO,SAAS,GAAG,KAAK,CAAC;AAC3B,CAAC,CAAC"}

package/dist/engine/selection.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file PURE item-selection engine (T011, OD-005 / research.md).
+ *
+ * Chooses the items for one quiz session for a single (topic × class) given the
+ * learner's current ability θ, the topic's candidate items (with FIXED authored
+ * difficulties), the target tier's next boundary, and a recent-item exclusion
+ * set. Difficulty-targets at the promotion bar so "passing a set" ≈ "ready to
+ * graduate", while an information-weighted window avoids always serving the
+ * hardest item.
+ *
+ * This module is IO-FREE and time-free (E5) and never mutates item difficulty
+ * (E3): items are read-only inputs.
+ *
+ * Selection rule (OD-005):
+ *   target = min(θ + targetOffset, nextBoundary + hysteresisMargin)
+ *   pool   = items with |difficulty − target| ≤ selectWindow, excluding recents
+ *   weight = p · (1 − p), p = expectedScore(θ, difficulty)  // Fisher info ∝ p(1−p)
+ *   pick `length` items by weight; ALWAYS include one "anchor" item within
+ *   ±anchorWindow of θ if one exists in the pool.
+ *
+ * Determinism: this function NEVER calls `Math.random`. Sampling is deterministic
+ * given the inputs. By default it picks the top-weighted items (ties broken by
+ * item id for total order). Callers that want stochastic-but-reproducible
+ * sampling may inject a seeded {@link Rng}; the same seed ⇒ the same output.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/research.md (OD-005);
+ * constants in ../config.ts (ASSESSMENT_CONFIG).
+ */
+import type { ContentItem } from "../schemas/content.js";
+/**
+ * A deterministic, reproducible random source returning values in `[0, 1)`.
+ * Injecting one makes weighted sampling stochastic yet repeatable. Omit it for
+ * the default deterministic top-weighted strategy.
+ */
+export type Rng = () => number;
+/** Parameters for {@link selectItems}. */
+export interface SelectItemsParams {
+    /** The learner's current ability estimate (θ). */
+    readonly ability: number;
+    /**
+     * Candidate items for the topic (any tier). FIXED authored difficulties;
+     * read-only — never mutated by selection.
+     */
+    readonly candidates: readonly ContentItem[];
+    /**
+     * Difficulty of the next tier boundary above the learner (the promotion bar
+     * the target is clamped to). E.g. for tier 300 this is the 350 boundary.
+     */
+    readonly nextBoundary: number;
+    /** Item ids to exclude (recently served), to avoid immediate repeats. */
+    readonly recentItemIds?: readonly string[];
+    /**
+     * Number of items to return (3–5). Defaults to
+     * {@link ASSESSMENT_CONFIG.defaultQuizLength}. If fewer eligible candidates
+     * exist, returns what is available.
+     */
+    readonly length?: number;
+    /**
+     * Optional injected RNG for reproducible weighted sampling. When omitted,
+     * selection is deterministic top-weighted (no `Math.random`).
+     */
+    readonly rng?: Rng;
+}
+/**
+ * Select 3–5 items for a quiz session (PURE; see file header for the rule).
+ *
+ * Items are read-only inputs; their difficulty is never mutated (E3). No clock,
+ * file, or network access (E5). Output is deterministic for identical inputs
+ * (and identical injected {@link Rng} sequence, if any).
+ *
+ * Behaviour summary:
+ * - Builds `target = min(θ + targetOffset, nextBoundary + hysteresisMargin)`.
+ * - Pool = candidates within ±`selectWindow` of `target`, excluding
+ *   `recentItemIds`.
+ * - Weights each by `p·(1−p)` (`p = expectedScore(θ, difficulty)`).
+ * - Guarantees one anchor item within ±`anchorWindow` of θ (the most
+ *   informative such item) is included when one exists in the pool.
+ * - Returns at most `length` items; fewer if the pool is smaller.
+ *
+ * @returns The chosen items, length ≤ `length`, anchor-first when an anchor
+ *   exists, then the remaining picks.
+ */
+export declare const selectItems: (params: SelectItemsParams) => ContentItem[];
+//# sourceMappingURL=selection.d.ts.map

package/dist/engine/selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../src/engine/selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD;;;;GAIG;AACH,MAAM,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC;AAE/B,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAoDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,iBAAiB,KAAG,WAAW,EAkDlE,CAAC"}