1 files changed, 25 insertions, 0 deletions
diff --git a/tvix/proto/castore.proto b/tvix/proto/castore.proto
index f9cffc3ebed9..b479595820fb 100644
--- a/tvix/proto/castore.proto
+++ b/tvix/proto/castore.proto
@@ -5,26 +5,51 @@ syntax = "proto3";
 
 package fossil.store;
 
+// A Directory can contain Directory, File or Link nodes.
+// Each of these nodes have a name attribute, which is the basename in that directory
+// and node type specific attributes.
+// The name attribute:
+//  - may not contain slashes or null bytes
+//  - needs to be unique across all three lists
+// Elements in each list need to be lexicographically ordered by the name
+// attribute.
 message Directory {
     repeated DirectoryNode directories = 1;
     repeated FileNode files = 2;
     repeated LinkNode links = 3;
 }
 
+// A DirectoryNode represents a directory in a Directory.
 message DirectoryNode {
+    // The (base)name of the directory
     string name = 1;
+    // The blake3 hash of a Directory message, serialized in protobuf canonical form.
     bytes ref = 2;
+    // Number of child elements in the Directory referred to by ref.
+    // Calculated by summing up the numbers of `directories`, `files` and `links`,
+    // and for each directory, its size field. Used for inode number calculation
+    // TODO(flokli): These numbers can't really be verified until you know the whole graph.
+    //               Is this a problem? Should we instead only have this field
+    //               in our local representation?
     uint32 size = 3;
 }
 
+// A FileNode represents a regular or executable file in a Directory.
 message FileNode {
+    // The (base)name of the file
     string name = 1;
+    // The blake3 hash of the file contents
     bytes ref = 2;
+    // The file content size
     uint32 size = 3;
+    // Whether the file is executable
     bool executable = 4;
 }
 
+// A LinkNode represents a symbolic link in a Directory.
 message LinkNode {
+    // The (base)name of the symlink
     string name = 1;
+    // The target of the symlink.
     string target = 2;
 }