Move away from inodes as direct db reference

trovedb/trove.py

@@ -1,12 +1,20 @@
-from typing import Protocol, runtime_checkable, Optional, Dict, List, Self
+from typing import Protocol, runtime_checkable, Optional, Dict, List, Self, NamedTuple, Iterable, MappingView
 from uuid import UUID
 from pathlib import PurePosixPath
 
-NODE_ROOT_ID = 1
+
+type ObjectId = int
+
+NODE_ROOT_ID: ObjectId = 1
 
 class BadNoteType(TypeError):
     """Raised when an invalid note type is encountered."""
 
+class TreeExists(TypeError):
+    """Raised when a label already exists."""
+
+class NoteNotFound(KeyError):
+    """Raised when a note is not found."""
 
 @runtime_checkable
 class Note(Protocol):
@@ -15,7 +23,7 @@ class Note(Protocol):
     Represents access to an individual note's content and metadata.
     """
     @property
-    def object_id(self) -> int:
+    def object_id(self) -> ObjectId:
         """The unique identifier for this note."""
         ...
 
@@ -37,6 +45,11 @@ class Blob(Protocol):
         """Write new content to the note."""
         ...
 
+
+class TreeEntry(NamedTuple):
+    name: str
+    object_id: ObjectId
+
 @runtime_checkable
 class Tree(Protocol):
     def link(self, name: str, note: Note):
@@ -56,7 +69,11 @@ class Tree(Protocol):
         ...
 
     def child(self, name: str) -> Note:
-        """Retrieve a child not by name."""
+        """Retrieve a child note by name."""
+        ...
+
+    def entries(self) -> Iterable[TreeEntry]:
+        """Return all entries in the directory"""
         ...
 
     def list(self) -> dict[str, int]:
@@ -78,8 +95,8 @@ class Trove(Protocol):
     Provides high-level access to notes and trees.
     """
 
-    def get_raw_note(self, note: int) -> Optional[Note]:
-        """Retrieve a note by a UUID"""
+    def get_raw_note(self, note: ObjectId) -> Note:
+        """Retrieve a note by a object id"""
         ...
 
     def create_blob(self, data: bytes | None = None) -> BlobNote: