learngraph 0.1.0

package/dist/types/types/edge.d.ts

@@ -0,0 +1,80 @@
+import type { SkillId } from './skill.js';
+/**
+ * Unique identifier for edges
+ */
+export type EdgeId = string & {
+    readonly __brand: unique symbol;
+};
+/**
+ * Create a typed EdgeId from a string
+ */
+export declare function createEdgeId(id: string): EdgeId;
+/**
+ * Types of prerequisite relationships
+ */
+export type EdgeType = 
+/** Absolutely required - cannot learn target without mastering this first */
+'hard'
+/** Important but not blocking - will struggle without it */
+ | 'soft'
+/** Enhances learning but is optional */
+ | 'recommended';
+/**
+ * Prerequisite edge representing a dependency between skills.
+ *
+ * Direction: source (prerequisite) -> target (dependent skill)
+ * Meaning: "You should master {source} before learning {target}"
+ */
+export interface PrerequisiteEdge {
+    /** Unique identifier for the edge */
+    id: EdgeId;
+    /** The prerequisite skill ID (what should be learned first) */
+    sourceId: SkillId;
+    /** The dependent skill ID (what requires the prerequisite) */
+    targetId: SkillId;
+    /**
+     * Strength of the dependency (0-1 scale)
+     * - 1.0: Absolutely essential
+     * - 0.7-0.9: Very important
+     * - 0.4-0.6: Helpful but not critical
+     * - 0.1-0.3: Nice to have
+     */
+    strength: number;
+    /** Type of prerequisite relationship */
+    type: EdgeType;
+    /**
+     * Optional reasoning for why this relationship exists
+     * Useful for debugging and educator review
+     */
+    reasoning?: string;
+    /** Arbitrary metadata for extensibility */
+    metadata: Record<string, unknown>;
+    /** ISO 8601 timestamp of creation */
+    createdAt: string;
+}
+/**
+ * Input for creating a new edge (without generated fields)
+ */
+export type PrerequisiteEdgeInput = Omit<PrerequisiteEdge, 'id' | 'createdAt'> & {
+    id?: EdgeId;
+};
+/**
+ * Default edge strength thresholds
+ */
+export declare const EDGE_STRENGTH_THRESHOLDS: {
+    /** Minimum strength to be considered a meaningful dependency */
+    readonly minimum: 0.3;
+    /** Strength threshold for "hard" prerequisites */
+    readonly hard: 0.8;
+    /** Strength threshold for "soft" prerequisites */
+    readonly soft: 0.5;
+};
+/**
+ * Validate an edge strength is in valid range
+ */
+export declare function isValidEdgeStrength(strength: number): boolean;
+/**
+ * Suggest edge type based on strength
+ */
+export declare function suggestEdgeType(strength: number): EdgeType;
+//# sourceMappingURL=edge.d.ts.map

package/dist/types/types/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../../src/types/edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAElE;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ;AAClB,6EAA6E;AAC3E,MAAM;AACR,4DAA4D;GAC1D,MAAM;AACR,wCAAwC;GACtC,aAAa,CAAC;AAElB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IAEX,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAElB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,wCAAwC;IACxC,IAAI,EAAE,QAAQ,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB;IACnC,gEAAgE;;IAEhE,kDAAkD;;IAElD,kDAAkD;;CAE1C,CAAC;AAEX;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAQ1D"}

package/dist/types/types/graph.d.ts

@@ -0,0 +1,99 @@
+import type { SkillNode, SkillId } from './skill.js';
+import type { PrerequisiteEdge, EdgeId } from './edge.js';
+/**
+ * A subgraph extracted from the full knowledge graph
+ */
+export interface Subgraph {
+    /** Root node ID that the subgraph was extracted from */
+    rootId: SkillId;
+    /** Depth of traversal from root */
+    depth: number;
+    /** All nodes in the subgraph */
+    nodes: SkillNode[];
+    /** All edges in the subgraph */
+    edges: PrerequisiteEdge[];
+}
+/**
+ * Complete graph export format
+ */
+export interface GraphExport {
+    /** Schema version for compatibility */
+    version: string;
+    /** Export timestamp */
+    exportedAt: string;
+    /** All skill nodes */
+    nodes: SkillNode[];
+    /** All prerequisite edges */
+    edges: PrerequisiteEdge[];
+    /** Optional metadata about the graph */
+    metadata?: {
+        name?: string;
+        description?: string;
+        domain?: string;
+        source?: string;
+    };
+}
+/**
+ * Graph statistics for analysis
+ */
+export interface GraphStats {
+    /** Total number of skill nodes */
+    nodeCount: number;
+    /** Total number of prerequisite edges */
+    edgeCount: number;
+    /** Number of threshold concepts */
+    thresholdConceptCount: number;
+    /** Number of root nodes (no prerequisites) */
+    rootNodeCount: number;
+    /** Number of leaf nodes (no dependents) */
+    leafNodeCount: number;
+    /** Maximum depth of the graph */
+    maxDepth: number;
+    /** Average number of prerequisites per skill */
+    avgPrerequisites: number;
+    /** Average number of dependents per skill */
+    avgDependents: number;
+    /** Distribution of Bloom's levels */
+    bloomDistribution: Record<string, number>;
+    /** Distribution of difficulty levels */
+    difficultyDistribution: {
+        foundational: number;
+        basic: number;
+        intermediate: number;
+        advanced: number;
+        expert: number;
+    };
+}
+/**
+ * Result of graph validation
+ */
+export interface GraphValidation {
+    /** Whether the graph is valid */
+    isValid: boolean;
+    /** List of validation errors */
+    errors: GraphValidationError[];
+    /** List of validation warnings */
+    warnings: GraphValidationWarning[];
+}
+/**
+ * Graph validation error (prevents use)
+ */
+export interface GraphValidationError {
+    type: 'cycle_detected' | 'orphan_edge' | 'duplicate_node' | 'duplicate_edge' | 'self_reference' | 'invalid_bloom_level' | 'invalid_difficulty';
+    message: string;
+    nodeIds?: SkillId[];
+    edgeIds?: EdgeId[];
+}
+/**
+ * Graph validation warning (degraded experience)
+ */
+export interface GraphValidationWarning {
+    type: 'disconnected_component' | 'very_deep_path' | 'high_in_degree' | 'missing_threshold_scaffolds' | 'inconsistent_difficulty';
+    message: string;
+    nodeIds?: SkillId[];
+}
+/**
+ * Current graph version for exports
+ */
+export declare const GRAPH_VERSION = "1.0.0";
+//# sourceMappingURL=graph.d.ts.map

package/dist/types/types/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/types/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAEhB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,gCAAgC;IAChC,KAAK,EAAE,SAAS,EAAE,CAAC;IAEnB,gCAAgC;IAChC,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,sBAAsB;IACtB,KAAK,EAAE,SAAS,EAAE,CAAC;IAEnB,6BAA6B;IAC7B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAE1B,wCAAwC;IACxC,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAElB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAE9B,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IAEtB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IAEjB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC;IAEzB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IAEtB,qCAAqC;IACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,wCAAwC;IACxC,sBAAsB,EAAE;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;IAEjB,gCAAgC;IAChC,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAE/B,kCAAkC;IAClC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EACA,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,qBAAqB,GACrB,oBAAoB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EACA,wBAAwB,GACxB,gBAAgB,GAChB,gBAAgB,GAChB,6BAA6B,GAC7B,yBAAyB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,UAAU,CAAC"}

package/dist/types/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Core type definitions for LearnGraph (jali)
+ *
+ * @packageDocumentation
+ */
+export type { BloomLevel } from './bloom.js';
+export { BLOOM_LEVEL_ORDER, BLOOM_VERBS, detectBloomLevel, compareBloomLevels, meetsBloomThreshold, } from './bloom.js';
+export type { SkillId, SkillNode, SkillNodeInput, SkillNodeUpdate } from './skill.js';
+export { createSkillId, SKILL_DEFAULTS, THRESHOLD_CONCEPT_MASTERY, isValidDifficulty, isValidMasteryThreshold, } from './skill.js';
+export type { EdgeId, EdgeType, PrerequisiteEdge, PrerequisiteEdgeInput } from './edge.js';
+export { createEdgeId, EDGE_STRENGTH_THRESHOLDS, isValidEdgeStrength, suggestEdgeType, } from './edge.js';
+export type { MasteryState, ResponseRecord, MasteryTrajectory } from './mastery.js';
+export { MASTERY_THRESHOLDS, hasMastery, masteryGap } from './mastery.js';
+export type { Subgraph, GraphExport, GraphStats, GraphValidation, GraphValidationError, GraphValidationWarning, } from './graph.js';
+export { GRAPH_VERSION } from './graph.js';
+export type { QueryOperator, QueryFilter, QuerySort, QueryPagination, SkillQuery, ZPDResult, LearningPath, LearningSession, ReviewSchedule, ReviewItem, ZPDOptions, PathOptions, ReviewOptions, } from './query.js';
+export type { StorageBackend, StorageConfigBase, Neo4jConfig, LevelGraphConfig, MemoryConfig, StorageConfig, ConnectionStatus, ImportResult, GraphStorage, StorageFactory, } from './storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,cAAc,EACd,yBAAyB,EACzB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAKpB,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,WAAW,CAAC;AAKnB,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK1E,YAAY,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK3C,YAAY,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,eAAe,EACf,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/types/types/mastery.d.ts

@@ -0,0 +1,89 @@
+import type { SkillId } from './skill.js';
+/**
+ * Mastery state for a learner on a specific skill.
+ *
+ * This is the primary interface for tracking learner progress.
+ * Note: LearnGraph stores the graph structure, not learner data.
+ * This interface is provided for consuming applications.
+ */
+export interface MasteryState {
+    /** The skill this mastery state refers to */
+    skillId: SkillId;
+    /**
+     * Current mastery estimate (0-1 scale)
+     * Updated via BKT or similar algorithm
+     */
+    mastery: number;
+    /** Timestamp of last practice attempt */
+    lastAttempt: Date | null;
+    /** Total number of practice attempts */
+    attempts: number;
+    /** Consecutive correct responses (for streak tracking) */
+    streak: number;
+    /**
+     * Spaced repetition interval (in milliseconds)
+     * Time until next recommended review
+     */
+    nextReviewInterval?: number;
+    /**
+     * SM-2 easiness factor (1.3 - 2.5)
+     * Used for spaced repetition calculations
+     */
+    easinessFactor?: number;
+}
+/**
+ * Response record for a single practice attempt
+ */
+export interface ResponseRecord {
+    /** Skill being practiced */
+    skillId: SkillId;
+    /** Whether the response was correct */
+    correct: boolean;
+    /** Timestamp of the response */
+    timestamp: Date;
+    /** Time taken to respond (in milliseconds) */
+    responseTimeMs?: number;
+    /** Selected answer (for wrong answer analysis) */
+    selectedAnswer?: string;
+    /** Correct answer (for comparison) */
+    correctAnswer?: string;
+    /** Item/question identifier */
+    itemId?: string;
+    /** Session identifier for grouping responses */
+    sessionId?: string;
+}
+/**
+ * Mastery trajectory showing progression over time
+ */
+export interface MasteryTrajectory {
+    /** Mastery values after each response */
+    trajectory: number[];
+    /** Final mastery value */
+    finalMastery: number;
+    /** Whether mastery threshold was achieved */
+    masteryAchieved: boolean;
+    /** Estimated responses until mastery (null if uncertain) */
+    responsesUntilMastery: number | null;
+}
+/**
+ * Mastery threshold values
+ */
+export declare const MASTERY_THRESHOLDS: {
+    /** Default mastery threshold for standard skills */
+    readonly default: 0.8;
+    /** Mastery threshold for threshold concepts */
+    readonly thresholdConcept: 0.9;
+    /** Minimum mastery to be considered "learned" */
+    readonly minimum: 0.5;
+    /** High mastery for expert-level */
+    readonly expert: 0.95;
+};
+/**
+ * Check if mastery level meets threshold
+ */
+export declare function hasMastery(mastery: number, threshold?: number): boolean;
+/**
+ * Calculate mastery gap (how much more is needed)
+ */
+export declare function masteryGap(current: number, threshold?: number): number;
+//# sourceMappingURL=mastery.d.ts.map

package/dist/types/types/mastery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastery.d.ts","sourceRoot":"","sources":["../../../src/types/mastery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAEzB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IAEjB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IAEjB,gCAAgC;IAChC,SAAS,EAAE,IAAI,CAAC;IAEhB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IAEzB,4DAA4D;IAC5D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B,oDAAoD;;IAEpD,+CAA+C;;IAE/C,iDAAiD;;IAEjD,oCAAoC;;CAE5B,CAAC;AAEX;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmC,GAAG,OAAO,CAEnG;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmC,GAAG,MAAM,CAElG"}

package/dist/types/types/query.d.ts

@@ -0,0 +1,155 @@
+import type { SkillNode, SkillId } from './skill.js';
+/**
+ * Query operators for filtering
+ */
+export type QueryOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith';
+/**
+ * Single filter condition
+ */
+export interface QueryFilter {
+    field: keyof SkillNode | string;
+    operator: QueryOperator;
+    value: unknown;
+}
+/**
+ * Sort specification
+ */
+export interface QuerySort {
+    field: keyof SkillNode | string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * Pagination parameters
+ */
+export interface QueryPagination {
+    offset: number;
+    limit: number;
+}
+/**
+ * Complete skill query specification
+ */
+export interface SkillQuery {
+    filters: QueryFilter[];
+    sorting: QuerySort[];
+    pagination: QueryPagination;
+}
+/**
+ * ZPD (Zone of Proximal Development) calculation result
+ */
+export interface ZPDResult {
+    /**
+     * Skills in the ZPD - ready to learn
+     * Prerequisites met, not yet mastered
+     */
+    zpd: SkillNode[];
+    /**
+     * Skills that are "ready" (in ZPD and within difficulty tolerance)
+     */
+    ready: SkillNode[];
+    /**
+     * Skills blocked by unmet prerequisites
+     * Map of skill ID -> list of unmet prerequisite names
+     */
+    blocked: Map<SkillId, string[]>;
+    /** Summary statistics */
+    stats: {
+        totalSkills: number;
+        mastered: number;
+        inZPD: number;
+        blocked: number;
+    };
+}
+/**
+ * Learning path from current state to target skill
+ */
+export interface LearningPath {
+    /** Target skill */
+    target: SkillNode;
+    /** Ordered list of skills to learn */
+    skills: SkillNode[];
+    /** Total estimated time in minutes */
+    totalMinutes: number;
+    /** Skills grouped into suggested sessions */
+    sessions: LearningSession[];
+    /** Key checkpoint skills along the path */
+    checkpoints: SkillNode[];
+}
+/**
+ * A single learning session (grouping of skills)
+ */
+export interface LearningSession {
+    /** Session number (1-indexed) */
+    sessionNumber: number;
+    /** Skills in this session */
+    skills: SkillNode[];
+    /** Estimated duration in minutes */
+    durationMinutes: number;
+    /** Focus area or theme for the session */
+    focus?: string;
+}
+/**
+ * Review schedule for spaced repetition
+ */
+export interface ReviewSchedule {
+    /** Skills due for review now */
+    dueNow: ReviewItem[];
+    /** Upcoming reviews (scheduled but not yet due) */
+    upcoming: ReviewItem[];
+    /** Total estimated review time in minutes */
+    totalReviewMinutes: number;
+}
+/**
+ * Single review item
+ */
+export interface ReviewItem {
+    /** Skill to review */
+    skill: SkillNode;
+    /** Current mastery state */
+    state: {
+        mastery: number;
+        lastAttempt: Date | null;
+        streak: number;
+    };
+    /** When the review is due */
+    nextReview: Date;
+    /** Priority score for ordering (higher = more urgent) */
+    priority: number;
+}
+/**
+ * Options for ZPD calculation
+ */
+export interface ZPDOptions {
+    /** Difficulty tolerance above learner level (default: 0.2) */
+    difficultyTolerance?: number;
+    /** Whether to prioritize threshold concepts (default: true) */
+    prioritizeThresholdConcepts?: boolean;
+    /** Maximum number of skills to return in ZPD (default: unlimited) */
+    maxResults?: number;
+    /** Filter to specific tags */
+    filterTags?: string[];
+    /** Filter to specific domain */
+    filterDomain?: string;
+}
+/**
+ * Options for learning path generation
+ */
+export interface PathOptions {
+    /** Target session length in minutes (default: 30) */
+    sessionMinutes?: number;
+    /** Maximum total path length in skills (default: unlimited) */
+    maxPathLength?: number;
+    /** Whether to include already-mastered skills for review (default: false) */
+    includeReview?: boolean;
+}
+/**
+ * Options for review schedule generation
+ */
+export interface ReviewOptions {
+    /** Include upcoming reviews (not just due now) */
+    includeUpcoming?: boolean;
+    /** How far ahead to look for upcoming reviews (in days) */
+    upcomingDays?: number;
+    /** Maximum number of reviews to return */
+    maxReviews?: number;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/types/types/query.d.ts.map

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

package/dist/types/types/skill.d.ts

@@ -0,0 +1,107 @@
+import type { BloomLevel } from './bloom.js';
+/**
+ * Unique identifier for skills
+ */
+export type SkillId = string & {
+    readonly __brand: unique symbol;
+};
+/**
+ * Create a typed SkillId from a string
+ */
+export declare function createSkillId(id: string): SkillId;
+/**
+ * Core skill node representing a discrete, teachable competency.
+ *
+ * This is the primary vertex type in the knowledge graph.
+ * Each skill represents something a learner can master.
+ */
+export interface SkillNode {
+    /** Unique identifier for the skill */
+    id: SkillId;
+    /** Concise name (3-8 words recommended) */
+    name: string;
+    /** Detailed description of what mastery looks like */
+    description: string;
+    /** Bloom's Taxonomy cognitive level */
+    bloomLevel: BloomLevel;
+    /**
+     * Normalized difficulty score (0-1 scale)
+     * - 0.0-0.2: Foundational/introductory
+     * - 0.2-0.4: Basic
+     * - 0.4-0.6: Intermediate
+     * - 0.6-0.8: Advanced
+     * - 0.8-1.0: Expert/mastery-level
+     */
+    difficulty: number;
+    /**
+     * Whether this is a threshold concept.
+     *
+     * Threshold concepts are transformative ideas that:
+     * - Fundamentally change understanding
+     * - Expose previously hidden interrelations
+     * - Are unlikely to be forgotten once learned
+     * - May be initially counter-intuitive
+     *
+     * @see Meyer & Land (2003)
+     */
+    isThresholdConcept: boolean;
+    /**
+     * Mastery threshold required before progression (0-1 scale)
+     * - Default: 0.80 (80%)
+     * - Threshold concepts: 0.90 (90%)
+     */
+    masteryThreshold: number;
+    /**
+     * Estimated time to achieve mastery (in minutes)
+     * Based on typical learner, includes practice time
+     */
+    estimatedMinutes: number;
+    /** Categorization tags for filtering and organization */
+    tags: string[];
+    /**
+     * Optional standard alignment (Common Core, NGSS, etc.)
+     * Format: "STANDARD_CODE" (e.g., "CCSS.MATH.6.EE.A.2")
+     */
+    standardAlignment?: string[];
+    /**
+     * Subject domain (e.g., "mathematics", "physics", "programming")
+     */
+    domain?: string;
+    /**
+     * Grade level or audience (e.g., "6", "undergraduate", "professional")
+     */
+    gradeLevel?: string;
+    /** Arbitrary metadata for extensibility */
+    metadata: Record<string, unknown>;
+    /** ISO 8601 timestamp of creation */
+    createdAt: string;
+    /** ISO 8601 timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Input for creating a new skill (without generated fields)
+ */
+export type SkillNodeInput = Omit<SkillNode, 'id' | 'createdAt' | 'updatedAt'> & {
+    id?: SkillId;
+};
+/**
+ * Partial update for an existing skill
+ */
+export type SkillNodeUpdate = Partial<Omit<SkillNode, 'id' | 'createdAt' | 'updatedAt'>>;
+/**
+ * Default values for optional skill fields
+ */
+export declare const SKILL_DEFAULTS: Pick<SkillNode, 'masteryThreshold' | 'isThresholdConcept' | 'tags' | 'metadata'>;
+/**
+ * Mastery threshold for threshold concepts
+ */
+export declare const THRESHOLD_CONCEPT_MASTERY = 0.9;
+/**
+ * Validate a difficulty value is in valid range
+ */
+export declare function isValidDifficulty(difficulty: number): boolean;
+/**
+ * Validate a mastery threshold is in valid range
+ */
+export declare function isValidMasteryThreshold(threshold: number): boolean;
+//# sourceMappingURL=skill.d.ts.map

package/dist/types/types/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/types/skill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEnE;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,EAAE,EAAE,OAAO,CAAC;IAEZ,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,UAAU,EAAE,UAAU,CAAC;IAEvB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB,yDAAyD;IACzD,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IAC/E,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC;AAEzF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,IAAI,CAC/B,SAAS,EACT,kBAAkB,GAAG,oBAAoB,GAAG,MAAM,GAAG,UAAU,CAMvD,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAElE"}