documentation for VM, cursor manager and namespace

8 files changed, 112 insertions, 38 deletions

diff --git a/Makefile b/Makefile
index 7a09a1f..4b444d9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 CXX = cl
 TARGET = RNT.exe
-OBJECTS = NT.obj ObjectManager.obj PermissionsManager.obj NamespaceReferenceManager.obj CursorManager.obj IdentityManager.obj LifecycleManager.obj HandlerManager.obj WAM.obj
+OBJECTS = NT.obj ObjectManager.obj PermissionsManager.obj NamespaceReferenceManager.obj CursorManager.obj IdentityManager.obj LifecycleManager.obj HandlerManager.obj VM.obj
 INCDIR = include
 DEFINES = /DNT_CONSOLE_APP /DNT_WAIT_ON_EXIT
 INCLUDE_FLAG = /I$(INCDIR)
@@ -15,12 +15,12 @@ all: $(TARGET)
 windows: all
 
 unix:
-	$(MAKE) CXX=c++ TARGET=RNT OBJECTS="NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o WAM.o" DEFINES=-DNT_CONSOLE_APP INCLUDE_FLAG=-Iinclude COMPILE_FLAGS="-std=c++17 -Wall -Wextra" COMPILE_ONLY=-c LINK_FLAGS= TARGET_OUT="-o RNT" REMOVE="rm -f" all
+	$(MAKE) CXX=c++ TARGET=RNT OBJECTS="NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o VM.o" DEFINES=-DNT_CONSOLE_APP INCLUDE_FLAG=-Iinclude COMPILE_FLAGS="-std=c++17 -Wall -Wextra" COMPILE_ONLY=-c LINK_FLAGS= TARGET_OUT="-o RNT" REMOVE="rm -f" all
 
 linux: unix
 
 macos:
-	$(MAKE) CXX=c++ TARGET=RNT OBJECTS="NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o WAM.o" DEFINES=-DNT_CONSOLE_APP INCLUDE_FLAG=-Iinclude COMPILE_FLAGS="-std=c++17 -Wall -Wextra" COMPILE_ONLY=-c LINK_FLAGS= TARGET_OUT="-o RNT" REMOVE="rm -f" all
+	$(MAKE) CXX=c++ TARGET=RNT OBJECTS="NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o VM.o" DEFINES=-DNT_CONSOLE_APP INCLUDE_FLAG=-Iinclude COMPILE_FLAGS="-std=c++17 -Wall -Wextra" COMPILE_ONLY=-c LINK_FLAGS= TARGET_OUT="-o RNT" REMOVE="rm -f" all
 
 $(TARGET): $(OBJECTS)
 	$(CXX) $(LINK_FLAGS) $(OBJECTS) $(TARGET_OUT)
@@ -49,8 +49,8 @@ LifecycleManager.obj: src\LifecycleManager.cpp
 HandlerManager.obj: src\HandlerManager.cpp
 	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src\HandlerManager.cpp /Fo:HandlerManager.obj
 
-WAM.obj: src\WAM.cpp
-	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src\WAM.cpp /Fo:WAM.obj
+VM.obj: src\VM.cpp
+	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src\VM.cpp /Fo:VM.obj
 
 NT.o: src/NT.cpp
 	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src/NT.cpp -o NT.o
@@ -76,8 +76,8 @@ LifecycleManager.o: src/LifecycleManager.cpp
 HandlerManager.o: src/HandlerManager.cpp
 	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src/HandlerManager.cpp -o HandlerManager.o
 
-WAM.o: src/WAM.cpp
-	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src/WAM.cpp -o WAM.o
+VM.o: src/VM.cpp
+	$(CXX) $(DEFINES) $(INCLUDE_FLAG) $(COMPILE_FLAGS) $(COMPILE_ONLY) src/VM.cpp -o VM.o
 
 clean:
-	-$(REMOVE) RNT.exe RNT $(OBJECTS) NT.obj ObjectManager.obj PermissionsManager.obj NamespaceReferenceManager.obj CursorManager.obj IdentityManager.obj LifecycleManager.obj HandlerManager.obj WAM.obj NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o WAM.o RNT.exp RNT.lib
+	-$(REMOVE) RNT.exe RNT $(OBJECTS) NT.obj ObjectManager.obj PermissionsManager.obj NamespaceReferenceManager.obj CursorManager.obj IdentityManager.obj LifecycleManager.obj HandlerManager.obj VM.obj NT.o ObjectManager.o PermissionsManager.o NamespaceReferenceManager.o CursorManager.o IdentityManager.o LifecycleManager.o HandlerManager.o VM.o RNT.exp RNT.lib
diff --git a/RelationalNT.vcxproj b/RelationalNT.vcxproj
index 9827b07..2586587 100644
--- a/RelationalNT.vcxproj
+++ b/RelationalNT.vcxproj
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-
   <ItemGroup Label="ProjectConfigurations">
     <ProjectConfiguration Include="Debug|Win32">
       <Configuration>Debug</Configuration>
@@ -19,19 +18,16 @@
       <Platform>x64</Platform>
     </ProjectConfiguration>
   </ItemGroup>
-
   <PropertyGroup Label="Globals">
     <VCProjectVersion>18.0</VCProjectVersion>
     <ProjectGuid>{FBC1C0B4-8B54-4A18-A91E-8A72767C5AE7}</ProjectGuid>
     <RootNamespace>RelationalNT</RootNamespace>
     <Keyword>MakeFileProj</Keyword>
   </PropertyGroup>
-
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
-
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="Configuration">
     <ConfigurationType>Makefile</ConfigurationType>
-    <UseDebugLibraries>true</UseDebugLibraries>    
+    <UseDebugLibraries>true</UseDebugLibraries>
     <PlatformToolset>v145</PlatformToolset>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="Configuration">
@@ -41,7 +37,7 @@
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
     <ConfigurationType>Makefile</ConfigurationType>
-    <UseDebugLibraries>true</UseDebugLibraries>    
+    <UseDebugLibraries>true</UseDebugLibraries>
     <PlatformToolset>v145</PlatformToolset>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
@@ -50,13 +46,10 @@
     <PlatformToolset>v145</PlatformToolset>
   </PropertyGroup>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
-
   <ImportGroup Label="ExtensionSettings">
   </ImportGroup>
-
-  <ImportGroup Label="Shared" >
+  <ImportGroup Label="Shared">
   </ImportGroup>
-
   <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
     <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
   </ImportGroup>
@@ -69,7 +62,6 @@
   <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
     <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
   </ImportGroup>
-
   <PropertyGroup Label="UserMacros" />
   <PropertyGroup>
     <NMakeBuildCommandLine>nmake /f "$(ProjectDir)Makefile" windows</NMakeBuildCommandLine>
@@ -79,11 +71,12 @@
     <NMakePreprocessorDefinitions>NT_CONSOLE_APP;NT_WAIT_ON_EXIT;_CONSOLE</NMakePreprocessorDefinitions>
     <NMakeIncludeSearchPath>$(ProjectDir)include</NMakeIncludeSearchPath>
     <LocalDebuggerCommand>$(ProjectDir)RNT.exe</LocalDebuggerCommand>
-    <LocalDebuggerCommandArguments></LocalDebuggerCommandArguments>
+    <LocalDebuggerCommandArguments>
+    </LocalDebuggerCommandArguments>
     <LocalDebuggerWorkingDirectory>$(ProjectDir)</LocalDebuggerWorkingDirectory>
   </PropertyGroup>
-
-  <ItemDefinitionGroup></ItemDefinitionGroup>
+  <ItemDefinitionGroup>
+  </ItemDefinitionGroup>
   <ItemGroup>
     <ClCompile Include="src\CursorManager.cpp" />
     <ClCompile Include="src\HandlerManager.cpp" />
@@ -93,7 +86,7 @@
     <ClCompile Include="src\NT.cpp" />
     <ClCompile Include="src\ObjectManager.cpp" />
     <ClCompile Include="src\PermissionsManager.cpp" />
-    <ClCompile Include="src\WAM.cpp" />
+    <ClCompile Include="src\VM.cpp" />
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="include\Api.h" />
@@ -107,14 +100,12 @@
     <ClInclude Include="include\PermissionsManager.h" />
     <ClInclude Include="include\Runtime.h" />
     <ClInclude Include="include\Types.h" />
-    <ClInclude Include="include\WAM.h" />
+    <ClInclude Include="include\VM.h" />
   </ItemGroup>
   <ItemGroup>
     <None Include="Makefile" />
   </ItemGroup>
-
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
-
   <ImportGroup Label="ExtensionTargets">
   </ImportGroup>
-</Project>
+</Project>
\ No newline at end of file
diff --git a/include/CursorManager.h b/include/CursorManager.h
index 33230ab..61fba87 100644
--- a/include/CursorManager.h
+++ b/include/CursorManager.h
@@ -4,6 +4,32 @@
 
 namespace nt
 {
+	/**
+     * @class CursorManager
+     * @brief Orchestrates data pagination from storage backends to the query executor.
+     *
+     * The Cursor Manager implements the glue between the 'registry' objects
+     * and the Volcano-style iterator model. It translates high-level plan
+     * requests into low-level backend operations (LMDB, etcd, etc.).
+     *
+     * DUTIES:
+     * 1. Snapshot Anchoring & Pins:
+     *    We need to bind the retrieval to a multigroup snapshot, the object
+     *    for it should hold the reference for the tree that holds all the relations and tuples.
+     *
+     * 2. State Maintenance:
+     *    Tracks the current position (Iterators/Offsets) within a relation
+     *    to support sequential Next() calls from the algebra engine.
+     *
+     * 3. Prefetching & Buffering:
+     *    Abstracts the 'paging' logic of the backend. For remote backends
+     *    like etcd, it manages local buffers to hide latency from the executor.
+     *    Think of a driver for an operating system.
+     *
+     * 4. Boundary Enforcement:
+     *    Ensures scans do not cross commit boundaries or logical branch
+     *    definitions unless explicitly requested by the plan.
+     */
     class NT_API CursorManager
     {
     };
diff --git a/include/LifecycleManager.h b/include/LifecycleManager.h
index 2cd270d..8bf1a2c 100644
--- a/include/LifecycleManager.h
+++ b/include/LifecycleManager.h
@@ -10,6 +10,7 @@ namespace nt
     public:
         // If object is not being monitored already, monitors the lifecycle by updating the handle count.
         // Maybe also look at the reference count and kill some categories of disposable objects no longer referenced by other objects, like transactions.
+        // One use case is preventing compaction/prunning of history while cursors depend on old database snapshots, for example.
         // Think of other use cases later.
         void Monitor(ObjectManager::registry* object);
         // Serializes contention for the change of a mutable reference.
diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h
index 922a0ca..d5c3897 100644
--- a/include/NamespaceReferenceManager.h
+++ b/include/NamespaceReferenceManager.h
@@ -4,6 +4,26 @@
 
 namespace nt
 {
+    /**
+     * @class NamespaceReferenceManager
+     *
+     * @brief Handles the logical mapping and isolation of human-readable references.
+     *
+     * DESIGN NOTES:
+     * 1. Namespace Isolation:
+     *    Allows for private branch shadowing (e.g., /user_a/refs/branch/abc).
+     *    To maintain lookup clarity, protocol-level syntax must explicitly define
+     *    the scope to prevent non-deterministic shadowing during resolution.
+     *
+     * 2. Multi-Ref Atomic Updates:
+     *    Ensures that updates to multiple references (e.g., pushing to 'master'
+     *    and 'audit_log' simultaneously) are all-or-nothing. If any single
+     *    contention check fails, the entire batch is aborted to prevent
+     *    partial commits and maintain consistent audit trails. Considering we 
+     *    want to have a global access to audit, we would need to be dissociated
+     *    from the scope of a branch, and branches are the only points of contention 
+     *    for references, so it made sense to me to think of audit as an independent branch too.
+     */
     class NT_API NamespaceReferenceManager
     {
     };
diff --git a/include/VM.h b/include/VM.h
new file mode 100644
index 0000000..74ab982
--- /dev/null
+++ b/include/VM.h
@@ -0,0 +1,46 @@
+#pragma once
+
+#include "Api.h"
+
+namespace nt
+{
+	/**
+     * @class VM
+     * @brief The first-order logic (FOL) and second-order logic (SOL) dual cores
+     *
+     * This partitioning is here to ensure termination on retrieval with FOL.
+     * 1. Tarski Runtime (FOL):
+     *    A relational engine that implements Tarski's relational calculus.
+     *    It uses a deterministic Volcano-iterator model to perform relational algebra operations
+     *    (Joins, Projections, Selects, etc) directly against the Cursor Manager and a prepared plan.
+     *
+     * 2. Karuta Runtime (SOL):
+     *    An isolated WAM-based environment for higher-order logic programming. It
+     *    handles recursion, choice points, and other complex programming constructs
+     *    that do not guarantee termination.
+     *
+     * @remark Lazy Evaluation & Paging Strategy
+     *
+     * Both the Tarski (First-Order) and Karuta (Second-Order) engines are
+     * strictly pull-based. Data is streamed lazily from the Cursor Manager
+     * to ensure a constant memory footprint regardless of relation size.
+     *
+     * PIPELINE DYNAMICS:
+     * 1. Demand-Driven:
+     *    The Karuta WAM only requests a fact when a goal needs satisfaction.
+     *    A request propagates down the algebra tree as a chain of Next() calls.
+     *
+     * 2. Short-Circuiting:
+     *    If the Karuta engine finds a solution or hits a failure that
+     *    invalidates a branch, the Tarski iterator is discarded or reset
+     *    without ever having materialized the remaining tuples.
+     *
+     * 3. Resource Stewardship:
+     *    By maintaining laziness up to the highest logical level, we
+     *    minimize pressure on the ObjectManager and keep snapshots pinned
+     *    (via Monitor) only for the absolute minimum time required.
+     */
+    class NT_API WAM
+    {
+    };
+}
diff --git a/include/WAM.h b/include/WAM.h
deleted file mode 100644
index 8f0cb11..0000000
--- a/include/WAM.h
+++ /dev/null
@@ -1,10 +0,0 @@
-#pragma once
-
-#include "Api.h"
-
-namespace nt
-{
-    class NT_API WAM
-    {
-    };
-}
diff --git a/src/WAM.cpp b/src/VM.cpp
index 9088cd0..4e69b8e 100644
--- a/src/WAM.cpp
+++ b/src/VM.cpp
@@ -1,4 +1,4 @@
-#include "WAM.h"
+#include "VM.h"
 
 namespace nt
 {