triedb/pathdb: update comment

triedb/pathdb/history_indexer.go

@@ -479,6 +479,9 @@ func (i *historyIndexer) close() {
 	i.initer.close()
 }
 
+// inited returns a flag indicating whether the existing state histories
+// have been fully indexed, in other words, whether they are available
+// for external access.
 func (i *historyIndexer) inited() bool {
 	return i.initer.inited()
 }

triedb/pathdb/history_reader.go

@@ -311,7 +311,8 @@ func (r *historyReader) read(state stateIdentQuery, stateID uint64, lastID uint6
 	lastIndexedID := rawdb.ReadLastStateHistoryIndex(r.disk)
 
 	// To serve the request, all state histories from stateID+1 to lastID
-	// must be indexed
+	// must be indexed. It's not supposed to happen unless system is very
+	// wrong.
 	if lastIndexedID == nil || *lastIndexedID < lastID {
 		indexed := "null"
 		if lastIndexedID != nil {

triedb/pathdb/reader.go

@@ -210,8 +210,19 @@ func (db *Database) HistoricReader(root common.Hash) (*HistoricalStateReader, er
 	if db.indexer == nil || !db.indexer.inited() {
 		return nil, errors.New("state histories haven't been fully indexed yet")
 	}
-	// States older than current disk layer (disk layer is included) are available
-	// for accessing.
+	if db.freezer == nil {
+		return nil, errors.New("state histories are not available")
+	}
+	// States at the current disk layer or above are directly accessible via
+	// db.StateReader.
+	//
+	// States older than the current disk layer (including the disk layer
+	// itself) are available through historic state access.
+	//
+	// Note: the requested state may refer to a stale historic state that has
+	// already been pruned. This function does not validate availability, as
+	// underlying states may be pruned dynamically. Validity is checked during
+	// each actual state retrieval.
 	id := rawdb.ReadStateID(db.diskdb, root)
 	if id == nil {
 		return nil, fmt.Errorf("state %#x is not available", root)