port docs to doxygen

12 files changed, 298 insertions, 94 deletions

diff --git a/include/Api.h b/include/Api.h
index d47636d..33a7f6d 100644
--- a/include/Api.h
+++ b/include/Api.h
@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file Api.h
+ * @brief Defines symbol visibility for the Relational NT public API.
+ */
+
 #if defined(_WIN32) && defined(NT_CONSOLE_APP)
 #define NT_API
 #elif defined(_WIN32) && defined(NT_EXPORTS)
diff --git a/include/CursorManager.h b/include/CursorManager.h
index 61fba87..7e1ebe0 100644
--- a/include/CursorManager.h
+++ b/include/CursorManager.h
@@ -2,33 +2,36 @@
 
 #include "Api.h"
 
+/**
+ * @file CursorManager.h
+ * @brief Declares paging and cursor orchestration for query execution.
+ */
+
 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.).
+     * The cursor manager is the glue between registry objects and the
+     * Volcano-style iterator model. It translates high-level plan requests into
+     * low-level backend operations such as LMDB or etcd reads.
      *
-     * 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.
+     * Responsibilities:
+     * - Snapshot anchoring and pins: bind retrieval to a multigroup snapshot.
+     *   The snapshot object should hold the reference to the tree containing
+     *   all relations and tuples.
      *
-     * 2. State Maintenance:
-     *    Tracks the current position (Iterators/Offsets) within a relation
-     *    to support sequential Next() calls from the algebra engine.
+     * - State maintenance: track the current iterator or offset inside 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.
+     * - Prefetching and buffering: abstract backend paging. For remote
+     *   backends like etcd, manage local buffers to hide latency from the
+     *   executor. Think of this as a database equivalent of an operating-system
+     *   driver.
      *
-     * 4. Boundary Enforcement:
-     *    Ensures scans do not cross commit boundaries or logical branch
-     *    definitions unless explicitly requested by the plan.
+     * - Boundary enforcement: ensure scans do not cross commit boundaries or
+     *   logical branch definitions unless explicitly requested by the plan.
      */
     class NT_API CursorManager
     {
diff --git a/include/HandlerManager.h b/include/HandlerManager.h
index d126680..185cc55 100644
--- a/include/HandlerManager.h
+++ b/include/HandlerManager.h
@@ -6,20 +6,50 @@
 #include <string>
 #include <vector>
 
+/**
+ * @file HandlerManager.h
+ * @brief Declares handle allocation and release for authorized object access.
+ */
+
 namespace nt
 {
+    /** @brief Opens and closes authorized handles to registry objects. */
     class NT_API HandlerManager
     {
     public:
-        // This is supposed to represent an authorized access to a certain object in the registry
-        // This increases the handle count in the object manager
-        // We should consider adding on the object manager a vector of all the handles that refer to an object
+        /**
+         * @brief Represents authorized access to an object in the registry.
+         *
+         * This increases the handle count in the object manager. We should
+         * consider adding a vector to the object manager with all handles that
+         * refer to an object.
+         */
         struct handle {
+            /** Object referenced by this handle. */
             ObjectManager::registry* object = nullptr;
+            /** Connection metadata associated with the authorized access. */
             void* connection_context = nullptr;
         };
+
+        /**
+         * @brief Releases a handle allocation.
+         * @param handle Handle to release.
+         */
         void DeallocateHandle(struct handle* handle);
-        struct handle Open(std::vector<std::string> object_path, void* connection_context);
+
+        /**
+         * @brief Opens an object by path for a connection.
+         * @param object_path Logical object path.
+         * @param connection_context Connection metadata for the caller.
+         * @return A valid handle pointer on success, or nullptr on failure.
+         */
+        struct handle* Open(std::vector<std::string> object_path, void* connection_context);
+
+        /**
+         * @brief Closes a previously opened handle.
+         * @param handle Handle to close.
+         * @return True when the handle was closed successfully.
+         */
         bool Close(struct handle* handle);
     };
 }
diff --git a/include/IdentityManager.h b/include/IdentityManager.h
index 1a03fff..0e2d08f 100644
--- a/include/IdentityManager.h
+++ b/include/IdentityManager.h
@@ -3,13 +3,29 @@
 #include "Api.h"
 #include "ObjectManager.h"
 
+/**
+ * @file IdentityManager.h
+ * @brief Declares object capability checks.
+ */
+
 namespace nt
 {
+    /** @brief Checks whether an object supports identity-level operations. */
     class NT_API IdentityManager
     {
     public:
-        // Looks into the methods of the object type and asserts if it can be opened
+        /**
+         * @brief Looks into the methods of the object type and asserts if it can be opened.
+         * @param object Object to inspect.
+         * @return True when the object can be opened.
+         */
         const bool CanOpen(ObjectManager::registry* object);
+
+        /**
+         * @brief Checks whether an object can be closed.
+         * @param object Object to inspect.
+         * @return True when the object can be closed.
+         */
         const bool CanClose(ObjectManager::registry* object);
     };
 }
diff --git a/include/LifecycleManager.h b/include/LifecycleManager.h
index 8bf1a2c..914ce0a 100644
--- a/include/LifecycleManager.h
+++ b/include/LifecycleManager.h
@@ -3,27 +3,60 @@
 #include "Api.h"
 #include "ObjectManager.h"
 
+/**
+ * @file LifecycleManager.h
+ * @brief Declares monitoring, pinning, cleanup, and contention operations.
+ */
+
 namespace nt
 {
+    /** @brief Manages runtime lifecycle concerns for registry objects. */
     class NT_API LifecycleManager
     {
     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.
+        /**
+         * @brief Starts monitoring an object's lifecycle.
+         *
+         * If the object is not being monitored already, monitor 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/pruning of history while
+         * cursors depend on old database snapshots, for example. Think of
+         * other use cases later.
+         *
+         * @param object Object to monitor.
+         */
         void Monitor(ObjectManager::registry* object);
-        // Serializes contention for the change of a mutable reference.
-        // This can be used in, for example, the HEAD of a branch to serialize the access.
-        // If the object does not causes contention, like a relation (since they are immutable, just like multigroups, all snapshots)
-        // then just approve, as they do not cause any contention. Transactions also do not cause any, 
-        // the only things that do are mutable reference states in shared sessions,
-        // for example: the HEAD of a branch, namespace collisions (creating two branches with the same name, or two multigroups with the same name from the same state, etc),
-        // multi-branch atomic commits (which I wish to not have as it damages isolation), 
-        // garbage collection of old state (as in, we want to delete an old-enough history to save up space), etc.
+
+        /**
+         * @brief Serializes contention for changes to mutable references.
+         *
+         * This can be used for the HEAD of a branch to serialize access. If the
+         * object does not cause contention, such as a relation, then this can
+         * approve the operation because relations and multigroups are immutable
+         * snapshots. Transactions also do not cause contention.
+         *
+         * The objects that do cause contention are mutable reference states in
+         * shared sessions. Examples include the HEAD of a branch, namespace
+         * collisions, multi-branch atomic commits (which may damage isolation),
+         * and garbage collection of old state when old-enough history is removed
+         * to save space.
+         *
+         * @param object Object to check for contention.
+         * @return True when the operation may proceed.
+         */
         const bool Contention(ObjectManager::registry* object);
-        // The inverse of `Monitor`, stops monitoring.
-        // Maybe garbage collect here also if the counters goes to zero.
+
+        /**
+         * @brief Stops monitoring an object.
+         *
+         * The inverse of Monitor. Maybe garbage collect here also if the
+         * counters go to zero.
+         *
+         * @param object Object to stop monitoring.
+         */
         void Unmonitor(ObjectManager::registry* object);
     };
 }
diff --git a/include/NT.h b/include/NT.h
index a97f6c8..0fc5514 100644
--- a/include/NT.h
+++ b/include/NT.h
@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file NT.h
+ * @brief Includes for the Relational NT public API.
+ */
+
 #include "Types.h"
 #include "ObjectManager.h"
 #include "PermissionsManager.h"
@@ -8,5 +13,5 @@
 #include "IdentityManager.h"
 #include "LifecycleManager.h"
 #include "HandlerManager.h"
-#include "WAM.h"
+#include "VM.h"
 #include "Runtime.h"
diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h
index d5c3897..59068f7 100644
--- a/include/NamespaceReferenceManager.h
+++ b/include/NamespaceReferenceManager.h
@@ -2,27 +2,31 @@
 
 #include "Api.h"
 
+/**
+ * @file NamespaceReferenceManager.h
+ * @brief Declares logical reference mapping and namespace isolation.
+ */
+
 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.
+     * Design notes:
+     * - Namespace isolation: allow private branch shadowing, such as
+     *   /user_a/refs/branch/abc. To preserve lookup clarity, protocol-level
+     *   syntax must explicitly define scope and prevent non-deterministic
+     *   shadowing during resolution.
+     *
+     * - Multi-reference atomic updates: ensure updates to multiple references,
+     *   such as pushing to master and audit_log simultaneously, are
+     *   all-or-nothing. If any contention check fails, the whole batch is
+     *   aborted to prevent partial commits and preserve audit consistency.
      *
-     * 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.
+     * Audit needs global access, which means it should be dissociated from a
+     * branch scope. Since branches are the only contention points for
+     * references, it makes sense to model audit as an independent branch too.
      */
     class NT_API NamespaceReferenceManager
     {
diff --git a/include/ObjectManager.h b/include/ObjectManager.h
index 8abf44c..52ba602 100644
--- a/include/ObjectManager.h
+++ b/include/ObjectManager.h
@@ -8,40 +8,79 @@
 #include <string>
 #include <vector>
 
+/**
+ * @file ObjectManager.h
+ * @brief Declares the registry responsible for runtime-managed database objects.
+ */
+
 namespace nt
 {
+    /**
+     * @brief Owns the registry used to locate and reference database objects.
+     *
+     * The object manager is the central directory for runtime objects. It keeps
+     * the metadata needed to reason about object type, path, references, and
+     * handles while the concrete storage model is still being designed.
+     */
     class NT_API ObjectManager
     {
     public:
+        /** @brief Base type for objects stored in the registry. */
         class IObject {
         public:
             virtual ~IObject() = default;
         };
+
+        /** @brief Object representing a multigroup. */
         class Multigroup : IObject {};
+        /** @brief Object representing a relation. */
         class Relation : IObject {};
+        /** @brief Object representing a tuple. */
         class Tuple : IObject {};
+        /** @brief Object representing a transaction. */
         class Transaction : IObject {};
+
+        /** @brief Describes the behavior and capabilities of an object category. */
         struct object_type {
+            /** Object category label. */
             OBJECT_TYPE label;
-            // If the object is not durable. E.g.: TRANSACTION
+            /** True when the object is not durable. For example: TRANSACTION. */
             bool disposable;
+            /** Methods supported by this object type. */
             std::set<METHOD> methods;
         };
+
+        /** @brief Shared metadata stored at the head of a registry entry. */
         struct registry_head {
+            /** Number of object-to-object references. */
             uint32_t reference_count;
+            /** Number of open handles. */
             uint32_t handle_count;
+            /** Object type metadata. */
             struct object_type* type;
+            /** Logical object path inside the namespace. */
             std::vector<std::string> path;
-            //security_descriptor to be added later, maybe also a set of labels
+            /** security_descriptor to be added later, maybe also a set of labels */
         };
+
+        /** @brief Node in the object registry. */
         struct registry {
+            /** Shared metadata for this object. */
             struct registry_head* head;
+            /** Stored object payload. */
             IObject object;
-            // TODO: Treat as a list for now, but ideally it's a tree
+            /** TODO: Treat as a list for now, but ideally it is a tree. */
             struct registry* next;
         };
+
+        /** Root registry entries. */
         struct registry** entries;
-        // Looks into this registry and attempts to retrieve the entry
+
+        /**
+         * @brief Looks into this registry and attempts to retrieve an entry.
+         * @param object_path Logical path to search for.
+         * @return Matching registry entry, or nullptr when no object is found.
+         */
         struct registry* Find(const std::vector<std::string> object_path);
     };
 }
diff --git a/include/PermissionsManager.h b/include/PermissionsManager.h
index c51bd27..6d79642 100644
--- a/include/PermissionsManager.h
+++ b/include/PermissionsManager.h
@@ -6,14 +6,44 @@
 
 #include <set>
 
+/**
+ * @file PermissionsManager.h
+ * @brief Declares authentication and object-access checks.
+ */
+
 namespace nt
 {
+    /**
+     * @brief Evaluates connection claims and object permissions.
+     *
+     * Permission checks are intentionally separated from lookup. The object
+     * manager can retrieve a candidate object, while this manager decides
+     * whether the caller is allowed to use it.
+     */
     class NT_API PermissionsManager
     {
     public:
-        // For validating connections at login
+        /**
+         * @brief Validates a connection during login.
+         * @param method Authentication method used by the connection.
+         * @return Claims granted to the authenticated connection.
+         */
         std::set<AUTH_CLAIM> Firewall(AUTH_METHOD method);
-        // For validating permission to an object
+
+        /**
+         * @brief Validates permission to an object.
+         *
+         * Checks the security descriptor on the head of the object found in
+         * ObjectManager::registry. It should also check connection metadata
+         * that is still to be defined, such as user group and policy.
+         *
+         * It is still undecided whether this should run on every attempt to get
+         * hold of an object, since that might produce significant overhead.
+         *
+         * @param object Object being accessed.
+         * @param connection_context Connection metadata for the caller.
+         * @return True when access is allowed.
+         */
         const bool Access(const ObjectManager::registry* object, const void* connection_context);
     };
 }
diff --git a/include/Runtime.h b/include/Runtime.h
index 60a0b90..aeac136 100644
--- a/include/Runtime.h
+++ b/include/Runtime.h
@@ -2,12 +2,24 @@
 
 #include "Api.h"
 
+/**
+ * @file Runtime.h
+ * @brief Declares the top-level Relational NT runtime facade.
+ */
+
 namespace nt
 {
+    /** @brief Top-level runtime object used by applications and the console entry point. */
     class NT_API NT
     {
     public:
+        /**
+         * @brief Reports whether the runtime is active.
+         * @return True when the runtime is running.
+         */
         bool IsRunning() const;
+
+        /** @brief Simulates an external entry call into the runtime. */
         void SimulateEntryCall();
     };
 }
diff --git a/include/Types.h b/include/Types.h
index fe6afed..9d55765 100644
--- a/include/Types.h
+++ b/include/Types.h
@@ -1,26 +1,48 @@
 #pragma once
 
+/**
+ * @file Types.h
+ * @brief Shared enum types used by the runtime managers.
+ */
+
+/** @brief Runtime object categories known by the object manager. */
 enum OBJECT_TYPE {
+    /** A database snapshot grouping relations and tuples. */
     MULTIGROUP,
+    /** A relation object. */
     RELATION,
+    /** A tuple object. */
     TUPLE,
+    /** An attribute object. */
     ATTRIBUTE,
+    /** A transaction object. */
     TRANSACTION
 };
 
+/** @brief Operations that may be supported by an object type. */
 enum METHOD {
+    /** Opens an object and creates an authorized handle. */
     OPEN,
+    /** Closes a previously opened handle. */
     CLOSE,
-    PARSE, // To plug a secondary namespace
+    /** Parses through a secondary namespace. */
+    PARSE,
+    /** Performs security checks. */
     SECURITY
 };
 
+/** @brief Claims granted to an authenticated connection. */
 enum AUTH_CLAIM {
+    /** Permission to read object state. */
     READ,
+    /** Permission to mutate object state. */
     WRITE
 };
 
+/** @brief Authentication strategies supported by the permissions layer. */
 enum AUTH_METHOD {
+    /** Certificate-based authentication. */
     CERTIFICATE,
+    /** Plain-text authentication. */
     PLAIN_TEXT
 };
diff --git a/include/VM.h b/include/VM.h
index 74ab982..2defe79 100644
--- a/include/VM.h
+++ b/include/VM.h
@@ -2,45 +2,50 @@
 
 #include "Api.h"
 
+/**
+ * @file VM.h
+ * @brief Declares the logic execution boundary for relational and higher-order workloads.
+ */
+
 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.
+     * @brief Hosts the first-order logic (FOL) and second-order logic (SOL) cores.
+     *
+     * This partitioning exists to ensure retrieval terminates when execution is
+     * constrained to first-order logic.
+     *
+     * - Tarski runtime (FOL): a relational engine that implements Tarski's
+     *   relational calculus. It uses a deterministic Volcano-iterator model to
+     *   perform relational algebra operations such as joins, projections, and
+     *   selects directly against the CursorManager and a prepared plan.
+     *
+     * - Karuta runtime (SOL): an isolated WAM-based environment for
+     *   higher-order logic programming. It handles recursion, choice points, and
+     *   other programming constructs that do not guarantee termination.
+     *
+     * @remark Lazy evaluation and paging strategy
+     *
+     * Both the Tarski first-order engine and the Karuta second-order engine are
+     * strictly pull-based. Data is streamed lazily from the CursorManager to
+     * preserve a constant memory footprint regardless of relation size.
+     *
+     * Pipeline dynamics:
+     * - Demand-driven: the Karuta WAM requests a fact only when a goal needs
+     *   satisfaction. A request propagates down the algebra tree as a chain of
+     *   Next() calls.
+     *
+     * - Short-circuiting: if the Karuta engine finds a solution or reaches a
+     *   failure that invalidates a branch, the Tarski iterator is discarded or
+     *   reset without materializing the remaining tuples.
+     *
+     * - Resource stewardship: by maintaining laziness up to the highest logical
+     *   level, the runtime minimizes pressure on ObjectManager and keeps
+     *   snapshots pinned through LifecycleManager::Monitor only for the minimum
+     *   time required.
      */
-    class NT_API WAM
+    class NT_API VM
     {
     };
 }