@holoscript/plugin-education-lms 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-education-lms
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies [c64fc1a]
+  - @holoscript/core@8.0.6
+
+## 2.0.0
+
+### Patch Changes
+
+- @holoscript/core@6.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@holoscript/plugin-education-lms",
+  "version": "2.0.1",
+  "description": "HoloScript domain plugin for education-lms",
+  "main": "src/index.ts",
+  "peerDependencies": {
+    "@holoscript/core": "8.0.6"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  }
+}

package/src/__tests__/educationsolver.test.ts

@@ -0,0 +1,424 @@
+/**
+ * Education LMS solver tests — education-lms-plugin
+ *
+ * Reference values verified against:
+ *  - Lord FM (1980) Applications of Item Response Theory. ETS.
+ *  - Wozniak P (1990) Optimization of Learning. SuperMemo SM-2.
+ *  - Bloom BS et al. (1956) Taxonomy of Educational Objectives.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  irtAbilityEstimate,
+  sm2Review,
+  learningPathOptimizer,
+  gradePredictor,
+  bloomClassifier,
+  quizPsychometrics,
+  buildEducationReceipt,
+} from '../educationsolver';
+
+// ─── IRT 3PL ─────────────────────────────────────────────────────────────────
+
+describe('irtAbilityEstimate', () => {
+  /**
+   * Simple 1PL (a=1, c=0): student answers all correctly.
+   * MLE θ → unbounded; clamped to +6.
+   */
+  it('all correct → high positive ability estimate', () => {
+    const items = [
+      { id: 'i1', b: -1 },
+      { id: 'i2', b:  0 },
+      { id: 'i3', b:  1 },
+    ];
+    const responses = [
+      { itemId: 'i1', correct: true },
+      { itemId: 'i2', correct: true },
+      { itemId: 'i3', correct: true },
+    ];
+    const r = irtAbilityEstimate(items, responses);
+    expect(r.abilityTheta).toBeGreaterThan(1);
+  });
+
+  it('all incorrect → low negative ability estimate', () => {
+    const items = [
+      { id: 'i1', b: -1 },
+      { id: 'i2', b:  0 },
+      { id: 'i3', b:  1 },
+    ];
+    const responses = [
+      { itemId: 'i1', correct: false },
+      { itemId: 'i2', correct: false },
+      { itemId: 'i3', correct: false },
+    ];
+    const r = irtAbilityEstimate(items, responses);
+    expect(r.abilityTheta).toBeLessThan(-1);
+  });
+
+  it('ability near item difficulty for 50/50 pattern', () => {
+    // Items with difficulties -1, +1; student gets easy correct, hard wrong
+    const items = [{ id: 'easy', b: -2 }, { id: 'hard', b: 2 }];
+    const responses = [{ itemId: 'easy', correct: true }, { itemId: 'hard', correct: false }];
+    const r = irtAbilityEstimate(items, responses);
+    // Ability should be in middle range
+    expect(r.abilityTheta).toBeGreaterThan(-2);
+    expect(r.abilityTheta).toBeLessThan(2);
+  });
+
+  it('testInformation = sum of itemInformation', () => {
+    const items = [{ id: 'i1', b: 0 }, { id: 'i2', b: 1 }];
+    const responses = [{ itemId: 'i1', correct: true }, { itemId: 'i2', correct: false }];
+    const r = irtAbilityEstimate(items, responses);
+    const manualSum = r.itemInformation.reduce((s, x) => s + x.information, 0);
+    expect(r.testInformation).toBeCloseTo(manualSum, 6);
+  });
+
+  it('standardError = 1/sqrt(testInformation)', () => {
+    const items = [{ id: 'i1', b: 0 }, { id: 'i2', b: 0.5 }];
+    const responses = [{ itemId: 'i1', correct: true }, { itemId: 'i2', correct: true }];
+    const r = irtAbilityEstimate(items, responses);
+    expect(r.standardError).toBeCloseTo(1 / Math.sqrt(r.testInformation), 4);
+  });
+
+  it('itemFit length matches items length', () => {
+    const items = [{ id: 'i1', b: 0 }, { id: 'i2', b: 1 }, { id: 'i3', b: -1 }];
+    const responses = items.map(it => ({ itemId: it.id, correct: true }));
+    const r = irtAbilityEstimate(items, responses);
+    expect(r.itemFit).toHaveLength(3);
+  });
+
+  it('higher discrimination a → more information near item difficulty', () => {
+    // Use mixed responses: easy item correct, hard item wrong → theta stays near 0
+    // where discrimination parameter a is most influential
+    const itemsLow  = [{ id: 'easy', a: 0.5, b: -2 }, { id: 'hard', a: 0.5, b: 2 }];
+    const itemsHigh = [{ id: 'easy', a: 2.0, b: -2 }, { id: 'hard', a: 2.0, b: 2 }];
+    const responsesLow  = [{ itemId: 'easy', correct: true }, { itemId: 'hard', correct: false }];
+    const responsesHigh = [{ itemId: 'easy', correct: true }, { itemId: 'hard', correct: false }];
+    const rLow  = irtAbilityEstimate(itemsLow,  responsesLow);
+    const rHigh = irtAbilityEstimate(itemsHigh, responsesHigh);
+    // Higher discrimination → higher test information at estimated theta
+    expect(rHigh.testInformation).toBeGreaterThan(rLow.testInformation);
+  });
+
+  it('throws for empty items', () => {
+    expect(() => irtAbilityEstimate([], [])).toThrow();
+  });
+
+  it('throws when responses length ≠ items length', () => {
+    const items = [{ id: 'i1', b: 0 }];
+    expect(() => irtAbilityEstimate(items, [])).toThrow();
+  });
+});
+
+// ─── SM-2 ─────────────────────────────────────────────────────────────────────
+
+describe('sm2Review', () => {
+  /**
+   * First review quality=5 (perfect recall):
+   * EF' = 2.5 + (0.1 - (5-5)(0.08 + 0)) = 2.5
+   * rep=1 → interval=1
+   */
+  it('first review quality=5 → interval=1, repetitions=1', () => {
+    const card = { id: 'c1' };
+    const r = sm2Review(card, 5);
+    expect(r.interval).toBe(1);
+    expect(r.repetitions).toBe(1);
+  });
+
+  it('second review quality=5 → interval=6', () => {
+    const card = { id: 'c1', interval: 1, repetitions: 1, ef: 2.5 };
+    const r = sm2Review(card, 5);
+    expect(r.interval).toBe(6);
+    expect(r.repetitions).toBe(2);
+  });
+
+  it('third review quality=5 → interval = round(6 × EF)', () => {
+    const card = { id: 'c1', interval: 6, repetitions: 2, ef: 2.5 };
+    const r = sm2Review(card, 5);
+    expect(r.interval).toBe(Math.round(6 * 2.5));
+  });
+
+  it('quality < 3 resets repetitions to 0 and interval to 1', () => {
+    const card = { id: 'c1', interval: 10, repetitions: 4, ef: 2.3 };
+    const r = sm2Review(card, 2);
+    expect(r.repetitions).toBe(0);
+    expect(r.interval).toBe(1);
+  });
+
+  it('EF decreases on poor recall (quality=2)', () => {
+    const card = { id: 'c1', ef: 2.5 };
+    const r = sm2Review(card, 2);
+    expect(r.ef).toBeLessThan(2.5);
+  });
+
+  it('EF clamped to [1.3, 2.5]', () => {
+    const card = { id: 'c1', ef: 1.3 };
+    const r0 = sm2Review(card, 0);
+    expect(r0.ef).toBeGreaterThanOrEqual(1.3);
+    const cardHigh = { id: 'c1', ef: 2.5 };
+    const r5 = sm2Review(cardHigh, 5);
+    expect(r5.ef).toBeLessThanOrEqual(2.5);
+  });
+
+  it('dueDays equals interval', () => {
+    const card = { id: 'c1', interval: 6, repetitions: 2, ef: 2.5 };
+    const r = sm2Review(card, 4);
+    expect(r.dueDays).toBe(r.interval);
+  });
+
+  it('throws for quality out of [0,5]', () => {
+    // @ts-expect-error testing invalid input
+    expect(() => sm2Review({ id: 'c1' }, 6)).toThrow();
+  });
+});
+
+// ─── Learning Path Optimizer ──────────────────────────────────────────────────
+
+describe('learningPathOptimizer', () => {
+  const nodes = [
+    { id: 'A', label: 'Algebra',      prerequisites: [],      estimatedMinutes: 60 },
+    { id: 'B', label: 'Calculus',     prerequisites: ['A'],   estimatedMinutes: 90 },
+    { id: 'C', label: 'Statistics',   prerequisites: ['A'],   estimatedMinutes: 45 },
+    { id: 'D', label: 'ML Basics',    prerequisites: ['B','C'], estimatedMinutes: 120 },
+  ];
+
+  it('path is in topological order (prerequisites before dependents)', () => {
+    const mastery: { nodeId: string; masteryScore: number }[] = [];
+    const r = learningPathOptimizer(nodes, mastery);
+    const pos = (id: string) => r.path.indexOf(id);
+    // A before B and C (if both appear)
+    if (pos('A') !== -1 && pos('B') !== -1) expect(pos('A')).toBeLessThan(pos('B'));
+    if (pos('A') !== -1 && pos('C') !== -1) expect(pos('A')).toBeLessThan(pos('C'));
+  });
+
+  it('mastered nodes excluded from path', () => {
+    const mastery = [{ nodeId: 'A', masteryScore: 0.95 }];
+    const r = learningPathOptimizer(nodes, mastery);
+    expect(r.path).not.toContain('A');
+  });
+
+  it('totalMinutes = sum of estimatedMinutes for unmastered path nodes', () => {
+    const mastery: { nodeId: string; masteryScore: number }[] = [];
+    const r = learningPathOptimizer(nodes, mastery);
+    const expected = r.path.reduce((acc, id) => {
+      const n = nodes.find(x => x.id === id);
+      return acc + (n?.estimatedMinutes ?? 30);
+    }, 0);
+    expect(r.totalMinutes).toBe(expected);
+  });
+
+  it('feasible=true for acyclic DAG', () => {
+    const r = learningPathOptimizer(nodes, []);
+    expect(r.feasible).toBe(true);
+  });
+
+  it('throws if prerequisite node not found', () => {
+    const badNodes = [
+      { id: 'X', label: 'X', prerequisites: ['MISSING'], estimatedMinutes: 30 },
+    ];
+    expect(() => learningPathOptimizer(badNodes, [])).toThrow();
+  });
+
+  it('throws for empty nodes', () => {
+    expect(() => learningPathOptimizer([], [])).toThrow();
+  });
+});
+
+// ─── Grade Predictor ──────────────────────────────────────────────────────────
+
+describe('gradePredictor', () => {
+  it('uniform grades → predictedGrade ≈ score', () => {
+    const grades = [
+      { weight: 1, score: 0.85, recencyIndex: 1 },
+      { weight: 1, score: 0.85, recencyIndex: 2 },
+      { weight: 1, score: 0.85, recencyIndex: 3 },
+    ];
+    const r = gradePredictor(grades);
+    expect(r.predictedGrade).toBeCloseTo(0.85, 2);
+  });
+
+  it('recent grades weighted more heavily with decay < 1', () => {
+    const grades = [
+      { weight: 1, score: 0.50, recencyIndex: 1 }, // old, low
+      { weight: 1, score: 0.95, recencyIndex: 5 }, // recent, high
+    ];
+    const r = gradePredictor(grades, 0.5);
+    // Should be closer to 0.95 than to plain average
+    expect(r.predictedGrade).toBeGreaterThan(0.70);
+  });
+
+  it('predictedGrade 0.93+ → letter A, gpa=4.0', () => {
+    const grades = [{ weight: 1, score: 0.95, recencyIndex: 1 }];
+    const r = gradePredictor(grades);
+    expect(r.letterGrade).toBe('A');
+    expect(r.gpa).toBe(4.0);
+  });
+
+  it('predictedGrade below 0.60 → letter F, gpa=0.0', () => {
+    const grades = [{ weight: 1, score: 0.50, recencyIndex: 1 }];
+    const r = gradePredictor(grades);
+    expect(r.letterGrade).toBe('F');
+    expect(r.gpa).toBe(0.0);
+  });
+
+  it('throws for empty grades', () => {
+    expect(() => gradePredictor([])).toThrow();
+  });
+
+  it('throws for decay > 1', () => {
+    const grades = [{ weight: 1, score: 0.8, recencyIndex: 1 }];
+    expect(() => gradePredictor(grades, 1.5)).toThrow();
+  });
+});
+
+// ─── Bloom Classifier ─────────────────────────────────────────────────────────
+
+describe('bloomClassifier', () => {
+  it('"define the term" → L1 Remember', () => {
+    const r = bloomClassifier('define the term photosynthesis');
+    expect(r.level).toBe(1);
+    expect(r.label).toBe('Remember');
+  });
+
+  it('"explain how the algorithm works" → L2 Understand', () => {
+    const r = bloomClassifier('explain how the algorithm works and summarize results');
+    expect(r.level).toBe(2);
+    expect(r.label).toBe('Understand');
+  });
+
+  it('"apply the formula to solve the equation" → L3 Apply', () => {
+    const r = bloomClassifier('apply the formula to calculate and solve the problem');
+    expect(r.level).toBe(3);
+    expect(r.label).toBe('Apply');
+  });
+
+  it('"analyze and differentiate" → L4 Analyze', () => {
+    const r = bloomClassifier('analyze the data and differentiate between approaches');
+    expect(r.level).toBe(4);
+    expect(r.label).toBe('Analyze');
+  });
+
+  it('"evaluate and critique the design" → L5 Evaluate', () => {
+    const r = bloomClassifier('evaluate and critique the design choices and assess tradeoffs');
+    expect(r.level).toBe(5);
+    expect(r.label).toBe('Evaluate');
+  });
+
+  it('"design and create a new system" → L6 Create', () => {
+    const r = bloomClassifier('design and create a new system, then develop the plan');
+    expect(r.level).toBe(6);
+    expect(r.label).toBe('Create');
+  });
+
+  it('unrecognized text → L1 with confidence=0', () => {
+    const r = bloomClassifier('the quick brown fox');
+    expect(r.level).toBe(1);
+    expect(r.confidence).toBe(0);
+  });
+});
+
+// ─── Quiz Psychometrics ───────────────────────────────────────────────────────
+
+describe('quizPsychometrics', () => {
+  /**
+   * 5 students, 3 items
+   * Easy item (p=1), medium (p=0.6), hard (p=0.2)
+   */
+  const responses = [
+    [1, 1, 1], // student 1: 3/3
+    [1, 1, 0], // student 2: 2/3
+    [1, 1, 0], // student 3: 2/3
+    [1, 0, 0], // student 4: 1/3
+    [1, 0, 0], // student 5: 1/3
+  ];
+  const itemIds = ['easy', 'medium', 'hard'];
+
+  it('pValues correct for each item', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    expect(r.pValues[0]).toBeCloseTo(1.0, 4); // all got easy
+    expect(r.pValues[1]).toBeCloseTo(0.6, 4); // 3/5
+    expect(r.pValues[2]).toBeCloseTo(0.2, 4); // 1/5
+  });
+
+  it('meanScore = average total score', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    const expected = (3 + 2 + 2 + 1 + 1) / 5;
+    expect(r.meanScore).toBeCloseTo(expected, 4);
+  });
+
+  it('cronbachAlpha in [0, 1] for valid quiz', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    expect(r.cronbachAlpha).toBeGreaterThanOrEqual(0);
+    expect(r.cronbachAlpha).toBeLessThanOrEqual(1);
+  });
+
+  it('perfect item (p=1) has 0 discrimination index', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    // Easy item everyone got right → no discrimination
+    expect(r.discriminationIndices[0]).toBeCloseTo(0, 4);
+  });
+
+  it('hard item shows positive discrimination', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    // High scorers got hard item; low scorers did not → positive D
+    expect(r.discriminationIndices[2]).toBeGreaterThan(0);
+  });
+
+  it('itemCount and n correct', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    expect(r.itemCount).toBe(3);
+    expect(r.n).toBe(5);
+  });
+
+  it('poorItems includes items with D < 0.2', () => {
+    const r = quizPsychometrics(responses, itemIds);
+    for (const id of r.poorItems) {
+      const idx = itemIds.indexOf(id);
+      expect(r.discriminationIndices[idx]).toBeLessThan(0.2);
+    }
+  });
+
+  it('throws for < 2 respondents', () => {
+    expect(() => quizPsychometrics([[1, 0]], itemIds)).toThrow();
+  });
+});
+
+// ─── Receipt ─────────────────────────────────────────────────────────────────
+
+describe('buildEducationReceipt', () => {
+  it('plugin=education-lms and CAEL event correct', () => {
+    const items = [{ id: 'i1', b: 0 }];
+    const irt = irtAbilityEstimate(items, [{ itemId: 'i1', correct: true }]);
+    const receipt = buildEducationReceipt({ irt, converged: true });
+    expect(receipt.plugin).toBe('education-lms');
+    expect(receipt.cael.event).toBe('education_lms.learning_analysis');
+    expect(receipt.payloadHash).toBeTruthy();
+  });
+
+  it('accepted=true for converged result', () => {
+    const receipt = buildEducationReceipt({ converged: true });
+    expect(receipt.acceptance.accepted).toBe(true);
+  });
+
+  it('accepted=false when quiz has poor reliability (α < 0.70)', () => {
+    // Psychometrics with very low cronbach alpha triggers a violation
+    const badPsychometrics = {
+      itemCount: 3,
+      n: 10,
+      pValues: [0.5, 0.5, 0.5],
+      discriminationIndices: [0.05, 0.05, 0.05],  // all poor → > 50% poor items
+      cronbachAlpha: 0.30,  // below 0.70 threshold
+      meanScore: 1.5,
+      stdDevScore: 0.5,
+      poorItems: ['i1', 'i2', 'i3'],
+    };
+    const receipt = buildEducationReceipt({ psychometrics: badPsychometrics, converged: true });
+    expect(receipt.acceptance.accepted).toBe(false);
+    expect(receipt.acceptance.violations.length).toBeGreaterThan(0);
+  });
+
+  it('uses provided runId', () => {
+    const receipt = buildEducationReceipt({ converged: true }, { runId: 'edu-run-99' });
+    expect(receipt.runId).toBe('edu-run-99');
+  });
+});

package/src/educationsolver.ts

@@ -0,0 +1,481 @@
+/**
+ * Learning analytics solvers — education-lms-plugin
+ *
+ * Implements:
+ *  - Item Response Theory (3PL logistic model, MLE ability estimation)
+ *  - SM-2 spaced repetition scheduler (Wozniak 1990)
+ *  - Knowledge space prerequisite graph + mastery tracking
+ *  - Grade prediction (recency-weighted moving average)
+ *  - Learning path optimization (Dijkstra on prerequisite DAG)
+ *  - Bloom's taxonomy classification (verb heuristic)
+ *  - Quiz psychometrics (p-value, discrimination index, Cronbach's α)
+ *
+ * References:
+ *  - Lord FM (1980) Applications of Item Response Theory. ETS.
+ *  - Wozniak P (1990) Optimization of Learning. SuperMemo SM-2.
+ *  - Bloom BS et al. (1956) Taxonomy of Educational Objectives.
+ *  - Doignon JP, Falmagne JC (1985) Psych.Rev. 92:201-224
+ */
+
+import { buildDomainSimulationReceipt, type DomainSimulationReceipt } from '@holoscript/core';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface IRTItem {
+  id: string;
+  /** Discrimination parameter a > 0 (default 1.0) */
+  a?: number;
+  /** Difficulty parameter b (logit scale, ~-3 to +3) */
+  b: number;
+  /** Pseudo-guessing parameter c ∈ [0,1] (default 0) */
+  c?: number;
+}
+
+export interface IRTResponse {
+  itemId: string;
+  correct: boolean;
+}
+
+export interface IRTResult {
+  /** Estimated ability θ (logit scale) */
+  abilityTheta: number;
+  /** Standard error of estimate */
+  standardError: number;
+  /** Item information at estimated θ */
+  itemInformation: Array<{ itemId: string; information: number }>;
+  /** Test information (sum) */
+  testInformation: number;
+  /** Item fit residuals */
+  itemFit: Array<{ itemId: string; residual: number }>;
+}
+
+export interface SM2Card {
+  id: string;
+  /** Ease factor EF ∈ [1.3, 2.5], default 2.5 */
+  ef?: number;
+  /** Current interval days */
+  interval?: number;
+  /** Total repetitions */
+  repetitions?: number;
+}
+
+export interface SM2Result {
+  id: string;
+  /** New ease factor */
+  ef: number;
+  /** Next review interval days */
+  interval: number;
+  /** Total repetitions after this review */
+  repetitions: number;
+  /** Due date (days from now) */
+  dueDays: number;
+  /** Quality of recall 0-5 */
+  quality: number;
+}
+
+export interface KnowledgeNode {
+  id: string;
+  label: string;
+  /** IDs of prerequisite nodes */
+  prerequisites: string[];
+  /** Estimated minutes to master */
+  estimatedMinutes?: number;
+}
+
+export interface MasteryState {
+  nodeId: string;
+  masteryScore: number; // 0–1
+}
+
+export interface LearningPathResult {
+  /** Ordered list of node IDs to study */
+  path: string[];
+  /** Total estimated minutes */
+  totalMinutes: number;
+  /** Whether all prerequisites are satisfiable */
+  feasible: boolean;
+}
+
+export interface QuizPsychometrics {
+  /** Number of items */
+  itemCount: number;
+  /** Number of respondents */
+  n: number;
+  /** Per-item p-value (proportion correct) */
+  pValues: number[];
+  /** Per-item discrimination index D = (upper27% - lower27%) correct rate */
+  discriminationIndices: number[];
+  /** Cronbach's alpha */
+  cronbachAlpha: number;
+  /** Mean score */
+  meanScore: number;
+  /** Score standard deviation */
+  stdDevScore: number;
+  /** Items flagged for poor discrimination (D < 0.2) */
+  poorItems: string[];
+}
+
+export interface BloomLevel {
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  label: 'Remember' | 'Understand' | 'Apply' | 'Analyze' | 'Evaluate' | 'Create';
+  confidence: number; // 0–1, fraction of matched verbs
+}
+
+export interface EducationReceiptOptions {
+  runId?: string;
+}
+
+// ─── IRT 3-Parameter Logistic Model ──────────────────────────────────────────
+
+/** P(correct | θ, a, b, c) = c + (1-c) / (1 + exp(-a(θ-b))) */
+function irt3PL(theta: number, a: number, b: number, c: number): number {
+  return c + (1 - c) / (1 + Math.exp(-a * (theta - b)));
+}
+
+/** Item information I(θ) = a²(1-P)(P-c)² / ((1-c)²P) */
+function itemInfo(theta: number, a: number, b: number, c: number): number {
+  const P = irt3PL(theta, a, b, c);
+  const Q = 1 - P;
+  if (P <= c || P >= 1) return 0;
+  return (a * a * Q * (P - c) * (P - c)) / ((1 - c) * (1 - c) * P);
+}
+
+/**
+ * Estimate student ability θ via Newton-Raphson MLE.
+ * Iterates until convergence or max 50 steps.
+ */
+export function irtAbilityEstimate(
+  items: IRTItem[],
+  responses: IRTResponse[],
+): IRTResult {
+  if (items.length === 0) throw new Error('No items provided');
+  if (responses.length !== items.length) throw new Error('responses must match items length');
+
+  const itemMap = new Map(items.map(it => [it.id, it]));
+  const responseMap = new Map(responses.map(r => [r.itemId, r.correct ? 1 : 0]));
+
+  // Newton-Raphson MLE
+  let theta = 0.0;
+  for (let iter = 0; iter < 50; iter++) {
+    let firstDeriv = 0, secondDeriv = 0;
+    for (const item of items) {
+      const a = item.a ?? 1.0, b = item.b, c = item.c ?? 0;
+      const P = irt3PL(theta, a, b, c);
+      const u = responseMap.get(item.id) ?? 0;
+      const W = (P - c) / ((1 - c) * P * (1 - P) + 1e-15);
+      const dP = a * (P - c) * (1 - P) / (1 - c + 1e-15);
+      firstDeriv  += (u - P) * dP / (P * (1 - P) + 1e-15);
+      secondDeriv -= dP * dP / (P * (1 - P) + 1e-15);
+    }
+    if (Math.abs(secondDeriv) < 1e-12) break;
+    const step = firstDeriv / secondDeriv;
+    theta -= step;
+    theta = Math.max(-6, Math.min(6, theta));
+    if (Math.abs(step) < 1e-6) break;
+  }
+
+  // Standard error = 1 / sqrt(test information)
+  const infoArr = items.map(item => {
+    const a = item.a ?? 1.0, b = item.b, c = item.c ?? 0;
+    return { itemId: item.id, information: itemInfo(theta, a, b, c) };
+  });
+  const testInformation = infoArr.reduce((s, x) => s + x.information, 0);
+  const standardError = testInformation > 0 ? 1 / Math.sqrt(testInformation) : Infinity;
+
+  // Item fit residuals
+  const itemFit = items.map(item => {
+    const a = item.a ?? 1.0, b = item.b, c = item.c ?? 0;
+    const P = irt3PL(theta, a, b, c);
+    const u = responseMap.get(item.id) ?? 0;
+    const residual = (u - P) / Math.sqrt(P * (1 - P) + 1e-15);
+    return { itemId: item.id, residual };
+  });
+
+  return { abilityTheta: theta, standardError, itemInformation: infoArr, testInformation, itemFit };
+}
+
+// ─── SM-2 Spaced Repetition ───────────────────────────────────────────────────
+
+/**
+ * Apply one SM-2 review to a flashcard.
+ * quality: 0=complete blackout, 5=perfect recall
+ * EF' = EF + (0.1 - (5-q)(0.08 + (5-q)×0.02))
+ * If quality < 3: reset repetitions and interval.
+ */
+export function sm2Review(card: SM2Card, quality: 0 | 1 | 2 | 3 | 4 | 5): SM2Result {
+  if (quality < 0 || quality > 5) throw new Error('quality must be 0-5');
+
+  let ef  = card.ef ?? 2.5;
+  let rep = card.repetitions ?? 0;
+  let interval = card.interval ?? 1;
+
+  // Update EF (clamp to [1.3, 2.5])
+  ef = Math.max(1.3, Math.min(2.5, ef + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))));
+
+  if (quality < 3) {
+    // Failure — restart
+    rep = 0;
+    interval = 1;
+  } else {
+    rep++;
+    if (rep === 1) interval = 1;
+    else if (rep === 2) interval = 6;
+    else interval = Math.round(interval * ef);
+  }
+
+  return { id: card.id, ef, interval, repetitions: rep, dueDays: interval, quality };
+}
+
+// ─── Knowledge Space + Learning Path ─────────────────────────────────────────
+
+/**
+ * Topological sort of prerequisite DAG.
+ * Returns nodes in study order starting from unmastered leaves.
+ */
+export function learningPathOptimizer(
+  nodes: KnowledgeNode[],
+  masteryStates: MasteryState[],
+  masteryThreshold = 0.80,
+): LearningPathResult {
+  if (nodes.length === 0) throw new Error('No knowledge nodes provided');
+
+  const masteryMap = new Map(masteryStates.map(m => [m.nodeId, m.masteryScore]));
+  const nodeMap = new Map(nodes.map(n => [n.id, n]));
+
+  // Validate prerequisites exist
+  for (const node of nodes) {
+    for (const prereq of node.prerequisites) {
+      if (!nodeMap.has(prereq)) throw new Error(`Prerequisite ${prereq} not found for node ${node.id}`);
+    }
+  }
+
+  // Kahn's topological sort
+  const inDegree = new Map(nodes.map(n => [n.id, 0]));
+  for (const node of nodes) {
+    for (const prereq of node.prerequisites) {
+      inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+    }
+  }
+
+  const queue: string[] = nodes.filter(n => (inDegree.get(n.id) ?? 0) === 0).map(n => n.id);
+  const topoOrder: string[] = [];
+  const adj = new Map<string, string[]>();
+  for (const node of nodes) {
+    for (const prereq of node.prerequisites) {
+      if (!adj.has(prereq)) adj.set(prereq, []);
+      adj.get(prereq)!.push(node.id);
+    }
+  }
+
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    topoOrder.push(cur);
+    for (const child of (adj.get(cur) ?? [])) {
+      const newDeg = (inDegree.get(child) ?? 0) - 1;
+      inDegree.set(child, newDeg);
+      if (newDeg === 0) queue.push(child);
+    }
+  }
+
+  const feasible = topoOrder.length === nodes.length;
+
+  // Filter to nodes that need study (mastery < threshold)
+  const path = topoOrder.filter(id => (masteryMap.get(id) ?? 0) < masteryThreshold);
+  const totalMinutes = path.reduce((acc, id) => acc + (nodeMap.get(id)?.estimatedMinutes ?? 30), 0);
+
+  return { path, totalMinutes, feasible };
+}
+
+// ─── Grade prediction ─────────────────────────────────────────────────────────
+
+export interface GradeEntry {
+  /** Assignment weight */
+  weight: number;
+  /** Score as fraction [0,1] */
+  score: number;
+  /** Recency index (higher = more recent) */
+  recencyIndex: number;
+}
+
+/**
+ * Predict final grade using recency-weighted moving average.
+ * decay: exponential decay factor per recency unit (default 0.85)
+ */
+export function gradePredictor(
+  grades: GradeEntry[],
+  decay = 0.85,
+): { predictedGrade: number; letterGrade: string; gpa: number } {
+  if (grades.length === 0) throw new Error('No grade entries provided');
+  if (decay <= 0 || decay > 1) throw new Error('decay must be in (0, 1]');
+
+  const maxRecency = Math.max(...grades.map(g => g.recencyIndex));
+  let weightedSum = 0, totalWeight = 0;
+  for (const g of grades) {
+    const recencyWeight = Math.pow(decay, maxRecency - g.recencyIndex);
+    const w = g.weight * recencyWeight;
+    weightedSum += g.score * w;
+    totalWeight += w;
+  }
+  const predictedGrade = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
+  // Letter grade (US standard)
+  const letter =
+    predictedGrade >= 0.93 ? 'A'  :
+    predictedGrade >= 0.90 ? 'A-' :
+    predictedGrade >= 0.87 ? 'B+' :
+    predictedGrade >= 0.83 ? 'B'  :
+    predictedGrade >= 0.80 ? 'B-' :
+    predictedGrade >= 0.77 ? 'C+' :
+    predictedGrade >= 0.73 ? 'C'  :
+    predictedGrade >= 0.70 ? 'C-' :
+    predictedGrade >= 0.67 ? 'D+' :
+    predictedGrade >= 0.60 ? 'D'  : 'F';
+
+  const gpaMap: Record<string, number> = {
+    'A':4.0,'A-':3.7,'B+':3.3,'B':3.0,'B-':2.7,'C+':2.3,'C':2.0,'C-':1.7,'D+':1.3,'D':1.0,'F':0.0,
+  };
+
+  return { predictedGrade, letterGrade: letter, gpa: gpaMap[letter] };
+}
+
+// ─── Bloom's Taxonomy classifier ──────────────────────────────────────────────
+
+const BLOOM_VERBS: Record<string, number> = {
+  // L1 Remember
+  define:1, list:1, recall:1, recognize:1, identify:1, name:1, state:1, describe:1, memorize:1,
+  // L2 Understand
+  explain:2, summarize:2, paraphrase:2, classify:2, compare:2, interpret:2, discuss:2, review:2,
+  // L3 Apply
+  apply:3, use:3, demonstrate:3, solve:3, implement:3, compute:3, execute:3, calculate:3, practice:3,
+  // L4 Analyze
+  analyze:4, differentiate:4, examine:4, distinguish:4, break:4, deconstruct:4, investigate:4, inspect:4,
+  // L5 Evaluate
+  evaluate:5, judge:5, critique:5, justify:5, assess:5, argue:5, defend:5, prioritize:5, rank:5,
+  // L6 Create
+  create:6, design:6, construct:6, develop:6, formulate:6, compose:6, plan:6, produce:6, generate:6,
+};
+
+const BLOOM_LABELS = ['','Remember','Understand','Apply','Analyze','Evaluate','Create'] as const;
+
+/**
+ * Classify learning objective text into Bloom's taxonomy level.
+ */
+export function bloomClassifier(objectiveText: string): BloomLevel {
+  const words = objectiveText.toLowerCase().replace(/[^a-z\s]/g, '').split(/\s+/);
+  const levelCounts = [0,0,0,0,0,0,0];
+  let matched = 0;
+  for (const word of words) {
+    const lvl = BLOOM_VERBS[word];
+    if (lvl) { levelCounts[lvl]++; matched++; }
+  }
+  if (matched === 0) {
+    return { level: 1, label: 'Remember', confidence: 0 };
+  }
+  let bestLevel = 1;
+  for (let l = 2; l <= 6; l++) if (levelCounts[l] > levelCounts[bestLevel]) bestLevel = l;
+  const level = bestLevel as 1|2|3|4|5|6;
+  return { level, label: BLOOM_LABELS[level], confidence: levelCounts[level] / words.length };
+}
+
+// ─── Quiz psychometrics ───────────────────────────────────────────────────────
+
+/**
+ * Compute classical test theory statistics for a quiz.
+ * responses: matrix [student][item] = 0/1
+ * itemIds: label per item
+ */
+export function quizPsychometrics(
+  responses: number[][],
+  itemIds: string[],
+): QuizPsychometrics {
+  const n = responses.length;
+  if (n < 2) throw new Error('At least 2 respondents required');
+  const k = itemIds.length;
+  if (responses.some(row => row.length !== k)) throw new Error('All response rows must match itemIds length');
+
+  // P-values
+  const pValues = itemIds.map((_, j) => {
+    const correct = responses.filter(r => r[j] === 1).length;
+    return correct / n;
+  });
+
+  // Total scores
+  const scores = responses.map(row => row.reduce((a, b) => a + b, 0));
+  const meanScore = scores.reduce((a, b) => a + b, 0) / n;
+  const variance  = scores.reduce((acc, s) => acc + (s - meanScore) ** 2, 0) / (n - 1);
+  const stdDevScore = Math.sqrt(variance);
+
+  // Discrimination indices (upper/lower 27%)
+  const sortedIndices = [...scores.keys()].sort((a, b) => scores[b] - scores[a]);
+  const k27 = Math.max(1, Math.floor(0.27 * n));
+  const upper = sortedIndices.slice(0, k27);
+  const lower = sortedIndices.slice(n - k27);
+
+  const discriminationIndices = itemIds.map((_, j) => {
+    const pU = upper.filter(i => responses[i][j] === 1).length / k27;
+    const pL = lower.filter(i => responses[i][j] === 1).length / k27;
+    return pU - pL;
+  });
+
+  // Cronbach's alpha: α = (k/(k-1)) × (1 − Σvar_i / var_total)
+  const itemVariances = itemIds.map((_, j) => {
+    const p = pValues[j];
+    return p * (1 - p);
+  });
+  const sumItemVar = itemVariances.reduce((a, b) => a + b, 0);
+  const cronbachAlpha = k > 1 && variance > 0
+    ? (k / (k - 1)) * (1 - sumItemVar / variance)
+    : 0;
+
+  const poorItems = itemIds.filter((_, j) => discriminationIndices[j] < 0.2);
+
+  return { itemCount: k, n, pValues, discriminationIndices, cronbachAlpha, meanScore, stdDevScore, poorItems };
+}
+
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+
+export interface EducationAnalysisResult {
+  irt?: IRTResult;
+  sm2?: SM2Result[];
+  learningPath?: LearningPathResult;
+  grade?: ReturnType<typeof gradePredictor>;
+  bloom?: BloomLevel;
+  psychometrics?: QuizPsychometrics;
+  converged: true;
+}
+
+export function buildEducationReceipt(
+  result: EducationAnalysisResult,
+  options?: EducationReceiptOptions,
+): DomainSimulationReceipt {
+  const violations: Array<{ criterion: string; message: string }> = [];
+
+  if (result.psychometrics) {
+    const { cronbachAlpha, poorItems } = result.psychometrics;
+    if (cronbachAlpha < 0.70) {
+      violations.push({ criterion: 'reliability', message: `Cronbach's α ${cronbachAlpha.toFixed(3)} < 0.70 — quiz reliability is poor` });
+    }
+    if (poorItems.length > result.psychometrics.itemCount / 2) {
+      violations.push({ criterion: 'discrimination', message: `${poorItems.length}/${result.psychometrics.itemCount} items have poor discrimination (D < 0.2)` });
+    }
+  }
+  if (result.learningPath && !result.learningPath.feasible) {
+    violations.push({ criterion: 'prerequisite_cycle', message: 'Prerequisite graph contains a cycle — learning path is infeasible' });
+  }
+
+  return buildDomainSimulationReceipt({
+    plugin: 'education-lms',
+    pluginVersion: '1.0.0',
+    runId: options?.runId ?? `edu-${Date.now().toString(36)}`,
+    solverConfig: { solverType: 'learning-analytics', scale: 'course' },
+    resultSummary: {
+      abilityTheta: result.irt?.abilityTheta ?? null,
+      cronbachAlpha: result.psychometrics?.cronbachAlpha ?? null,
+      predictedGrade: result.grade?.predictedGrade ?? null,
+      learningPathNodes: result.learningPath?.path.length ?? null,
+      bloomLevel: result.bloom?.level ?? null,
+    },
+    cael: { version: 'cael.v1', event: 'education_lms.learning_analysis', solverType: 'education-lms.irt-3pl' },
+    acceptance: { accepted: violations.length === 0, violations },
+  });
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './educationsolver';
+export { createCourseHandler, type CourseConfig, type CourseState, type Difficulty } from './traits/CourseTrait';
+export { createLessonHandler, type LessonConfig, type ContentType } from './traits/LessonTrait';
+export { createGradeHandler, type GradeConfig, type GradingScale } from './traits/GradeTrait';
+export { createEnrollmentHandler, type EnrollmentConfig, type EnrollmentStatus } from './traits/EnrollmentTrait';
+export { createQuizHandler, type QuizConfig, type QuizQuestion, type QuestionType } from './traits/QuizTrait';
+export * from './traits/types';
+
+import { createCourseHandler } from './traits/CourseTrait';
+import { createLessonHandler } from './traits/LessonTrait';
+import { createGradeHandler } from './traits/GradeTrait';
+import { createEnrollmentHandler } from './traits/EnrollmentTrait';
+import { createQuizHandler } from './traits/QuizTrait';
+
+export const pluginMeta = { name: '@holoscript/plugin-education-lms', version: '1.0.0', traits: ['course', 'lesson', 'grade', 'enrollment', 'quiz'] };
+export const traitHandlers = [createCourseHandler(), createLessonHandler(), createGradeHandler(), createEnrollmentHandler(), createQuizHandler()];

package/src/traits/CourseTrait.ts

@@ -0,0 +1,22 @@
+/** @course Trait — Course definition and management. @trait course */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type Difficulty = 'beginner' | 'intermediate' | 'advanced' | 'expert';
+export interface CourseConfig { title: string; description: string; instructor: string; durationHours: number; difficulty: Difficulty; prerequisites: string[]; modules: string[]; maxEnrollment: number; }
+export interface CourseState { enrolledCount: number; completionRate: number; averageScore: number; isPublished: boolean; }
+
+const defaultConfig: CourseConfig = { title: '', description: '', instructor: '', durationHours: 1, difficulty: 'beginner', prerequisites: [], modules: [], maxEnrollment: 100 };
+
+export function createCourseHandler(): TraitHandler<CourseConfig> {
+  return {
+    name: 'course', defaultConfig,
+    onAttach(node: HSPlusNode, config: CourseConfig, ctx: TraitContext) { node.__courseState = { enrolledCount: 0, completionRate: 0, averageScore: 0, isPublished: false }; ctx.emit?.('course:created', { title: config.title }); },
+    onDetach(node: HSPlusNode, _c: CourseConfig, ctx: TraitContext) { delete node.__courseState; ctx.emit?.('course:removed'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, _c: CourseConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__courseState as CourseState | undefined; if (!s) return;
+      if (event.type === 'course:publish') { s.isPublished = true; ctx.emit?.('course:published'); }
+      if (event.type === 'course:enroll') { s.enrolledCount++; ctx.emit?.('course:enrollment_updated', { count: s.enrolledCount }); }
+    },
+  };
+}

package/src/traits/EnrollmentTrait.ts

@@ -0,0 +1,22 @@
+/** @enrollment Trait — Student enrollment tracking. @trait enrollment */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type EnrollmentStatus = 'enrolled' | 'completed' | 'dropped' | 'waitlisted' | 'suspended';
+export interface EnrollmentConfig { studentId: string; courseId: string; status: EnrollmentStatus; enrolledDate: string; progressPercent: number; }
+
+const defaultConfig: EnrollmentConfig = { studentId: '', courseId: '', status: 'enrolled', enrolledDate: '', progressPercent: 0 };
+
+export function createEnrollmentHandler(): TraitHandler<EnrollmentConfig> {
+  return {
+    name: 'enrollment', defaultConfig,
+    onAttach(node: HSPlusNode, config: EnrollmentConfig, ctx: TraitContext) { node.__enrollState = { ...config }; ctx.emit?.('enrollment:created', { studentId: config.studentId, courseId: config.courseId }); },
+    onDetach(node: HSPlusNode, _c: EnrollmentConfig, ctx: TraitContext) { delete node.__enrollState; ctx.emit?.('enrollment:removed'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, _c: EnrollmentConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__enrollState as EnrollmentConfig | undefined; if (!s) return;
+      if (event.type === 'enrollment:update_progress') { s.progressPercent = event.payload?.progress as number; ctx.emit?.('enrollment:progress', { progress: s.progressPercent }); }
+      if (event.type === 'enrollment:complete') { s.status = 'completed'; s.progressPercent = 100; ctx.emit?.('enrollment:completed'); }
+      if (event.type === 'enrollment:drop') { s.status = 'dropped'; ctx.emit?.('enrollment:dropped'); }
+    },
+  };
+}

package/src/traits/GradeTrait.ts

@@ -0,0 +1,27 @@
+/** @grade Trait — Grade and scoring. @trait grade */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type GradingScale = 'letter' | 'percentage' | 'pass_fail' | 'points' | 'gpa';
+export interface GradeConfig { score: number; maxScore: number; weight: number; gradingScale: GradingScale; rubric?: string; }
+
+const defaultConfig: GradeConfig = { score: 0, maxScore: 100, weight: 1, gradingScale: 'percentage' };
+
+export function createGradeHandler(): TraitHandler<GradeConfig> {
+  return {
+    name: 'grade', defaultConfig,
+    onAttach(node: HSPlusNode, config: GradeConfig, ctx: TraitContext) { node.__gradeState = { ...config, letterGrade: computeLetter(config.score, config.maxScore) }; ctx.emit?.('grade:assigned'); },
+    onDetach(node: HSPlusNode, _c: GradeConfig, ctx: TraitContext) { delete node.__gradeState; ctx.emit?.('grade:removed'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, _c: GradeConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__gradeState as Record<string, unknown> | undefined; if (!s) return;
+      if (event.type === 'grade:update') { s.score = event.payload?.score as number; s.letterGrade = computeLetter(s.score as number, s.maxScore as number); ctx.emit?.('grade:updated', { score: s.score }); }
+    },
+  };
+}
+
+function computeLetter(score: number, max: number): string {
+  const pct = max > 0 ? (score / max) * 100 : 0;
+  if (pct >= 93) return 'A'; if (pct >= 90) return 'A-'; if (pct >= 87) return 'B+'; if (pct >= 83) return 'B';
+  if (pct >= 80) return 'B-'; if (pct >= 77) return 'C+'; if (pct >= 73) return 'C'; if (pct >= 70) return 'C-';
+  if (pct >= 60) return 'D'; return 'F';
+}

package/src/traits/LessonTrait.ts

@@ -0,0 +1,20 @@
+/** @lesson Trait — Lesson content unit. @trait lesson */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ContentType = 'video' | 'text' | 'interactive' | 'quiz' | 'assignment' | 'discussion';
+export interface LessonConfig { title: string; contentType: ContentType; durationMinutes: number; order: number; completionCriteria: 'view' | 'score' | 'submit'; passingScore?: number; }
+
+const defaultConfig: LessonConfig = { title: '', contentType: 'text', durationMinutes: 15, order: 0, completionCriteria: 'view' };
+
+export function createLessonHandler(): TraitHandler<LessonConfig> {
+  return {
+    name: 'lesson', defaultConfig,
+    onAttach(node: HSPlusNode, config: LessonConfig, ctx: TraitContext) { node.__lessonState = { isComplete: false, timeSpentMs: 0, score: null }; ctx.emit?.('lesson:attached', { title: config.title }); },
+    onDetach(node: HSPlusNode, _c: LessonConfig, ctx: TraitContext) { delete node.__lessonState; ctx.emit?.('lesson:detached'); },
+    onUpdate(node: HSPlusNode, _c: LessonConfig, _ctx: TraitContext, delta: number) { const s = node.__lessonState as Record<string, unknown> | undefined; if (s) s.timeSpentMs = ((s.timeSpentMs as number) || 0) + delta; },
+    onEvent(node: HSPlusNode, config: LessonConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__lessonState as Record<string, unknown> | undefined; if (!s) return;
+      if (event.type === 'lesson:complete') { s.isComplete = true; ctx.emit?.('lesson:completed', { title: config.title, timeSpent: s.timeSpentMs }); }
+    },
+  };
+}

package/src/traits/QuizTrait.ts

@@ -0,0 +1,30 @@
+/** @quiz Trait — Assessment with multiple question types. @trait quiz */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type QuestionType = 'multiple_choice' | 'true_false' | 'short_answer' | 'matching' | 'fill_blank';
+export interface QuizQuestion { id: string; type: QuestionType; text: string; options?: string[]; correctAnswer: string | string[]; points: number; }
+export interface QuizConfig { questions: QuizQuestion[]; timeLimitMinutes: number | null; attemptsAllowed: number; passingScore: number; shuffle: boolean; showCorrectAnswers: boolean; }
+export interface QuizState { currentQuestion: number; answers: Record<string, string>; score: number; attemptsUsed: number; isComplete: boolean; startedAt: number | null; }
+
+const defaultConfig: QuizConfig = { questions: [], timeLimitMinutes: null, attemptsAllowed: 3, passingScore: 70, shuffle: false, showCorrectAnswers: true };
+
+export function createQuizHandler(): TraitHandler<QuizConfig> {
+  return {
+    name: 'quiz', defaultConfig,
+    onAttach(node: HSPlusNode, config: QuizConfig, ctx: TraitContext) { node.__quizState = { currentQuestion: 0, answers: {}, score: 0, attemptsUsed: 0, isComplete: false, startedAt: null }; ctx.emit?.('quiz:ready', { questionCount: config.questions.length }); },
+    onDetach(node: HSPlusNode, _c: QuizConfig, ctx: TraitContext) { delete node.__quizState; ctx.emit?.('quiz:detached'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, config: QuizConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__quizState as QuizState | undefined; if (!s) return;
+      if (event.type === 'quiz:start') { s.startedAt = Date.now(); s.attemptsUsed++; ctx.emit?.('quiz:started', { attempt: s.attemptsUsed }); }
+      if (event.type === 'quiz:answer') { const qId = event.payload?.questionId as string; const ans = event.payload?.answer as string; s.answers[qId] = ans; }
+      if (event.type === 'quiz:submit') {
+        let correct = 0;
+        for (const q of config.questions) { if (s.answers[q.id] === q.correctAnswer) correct += q.points; }
+        const total = config.questions.reduce((sum, q) => sum + q.points, 0);
+        s.score = total > 0 ? (correct / total) * 100 : 0; s.isComplete = true;
+        ctx.emit?.('quiz:submitted', { score: s.score, passed: s.score >= config.passingScore });
+      }
+    },
+  };
+}

package/src/traits/types.ts

@@ -0,0 +1,4 @@
+export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitContext { emit?: (event: string, payload?: unknown) => void; getState?: () => Record<string, unknown>; setState?: (updates: Record<string, unknown>) => void; [key: string]: unknown; }
+export interface TraitEvent { type: string; source?: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<TConfig = unknown> { name: string; defaultConfig: TConfig; onAttach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onDetach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onUpdate(node: HSPlusNode, config: TConfig, ctx: TraitContext, delta: number): void; onEvent(node: HSPlusNode, config: TConfig, ctx: TraitContext, event: TraitEvent): void; }

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../../tsconfig.json", "compilerOptions": { "outDir": "dist", "rootDir": "src", "declaration": true, "declarationMap": true }, "include": ["src"] }

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});