documentation for VM, cursor manager and namespace

5 files changed, 93 insertions, 10 deletions

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
-    {
-    };
-}