cleanup: update stale comments

kernel/src/Api/Filesystem.hpp

@@ -62,9 +62,9 @@ namespace montauk::abi {
         if (proc == nullptr) return -1;
 
         // Use a rotating ring of scratch pages below the heap instead of
-        // bumping heapNext on every call. This keeps repeated directory scans
-        // from leaking user heap space while still allowing nested callers to
-        // hold multiple readdir results at once.
+        // extending the heap high-water mark on every call. This keeps repeated
+        // directory scans from consuming user heap address space while still
+        // allowing nested callers to hold multiple readdir results at once.
         uint32_t slot = proc->readdirCursor % Sched::UserReadDirSlots;
         proc->readdirCursor = (slot + 1) % Sched::UserReadDirSlots;
 

kernel/src/Api/Syscall.hpp

@@ -617,7 +617,7 @@ namespace montauk::abi {
         uint8_t  state;        // 0=Free, 1=Ready, 2=Running, 3=Blocked, 4=Terminated
         uint8_t  _pad[3];
         char     name[64];
-        uint64_t heapUsed;     // heapNext - UserHeapBase (bytes)
+        uint64_t heapUsed;     // Distance from UserHeapBase to high-water mark
         uint64_t cpuTimeMs;    // accumulated scheduler runtime
     };
 

kernel/src/Sched/Scheduler.hpp

@@ -80,7 +80,7 @@ namespace Sched {
         uint64_t pml4Phys;        // Physical address of per-process PML4
         uint64_t kernelStackTop;  // Top of kernel stack (for TSS RSP0 / SYSCALL)
         uint64_t userStackTop;    // User-space stack top
-        uint64_t heapNext;        // Simple bump allocator for user heap
+        uint64_t heapNext;        // High-water mark of the user-heap address space
         uint32_t readdirCursor;   // Next SYS_READDIR scratch slot
         char args[4096];          // Command-line arguments (set by parent via Spawn)
         char environment[EnvironmentBytes]; // NUL-separated NAME=VALUE entries
@@ -273,8 +273,9 @@ namespace Sched {
 
     // Per-process allocated page count (tracked by Heap syscalls, separate from Process struct)
     inline uint64_t g_allocatedPages[MaxProcesses] = {};
-    // One bit per page in the bounded userspace heap. Unlike heapNext, this
-    // makes virtual ranges reusable after unmap and failed reservations.
+    // One bit per page in the bounded userspace heap. This is the authoritative
+    // allocation state; unlike heapNext, it makes virtual ranges reusable after
+    // unmap and failed reservations.
     inline uint64_t g_userHeapPageMap[MaxProcesses][UserHeapBitmapWords] = {};
 
 }

programs/include/Api/Syscall.hpp

@@ -706,7 +706,7 @@ namespace montauk::abi {
         uint8_t  state;        // 0=Free, 1=Ready, 2=Running, 3=Blocked, 4=Terminated
         uint8_t  _pad[3];
         char     name[64];
-        uint64_t heapUsed;     // heapNext - UserHeapBase (bytes)
+        uint64_t heapUsed;     // Distance from UserHeapBase to high-water mark
         uint64_t cpuTimeMs;    // accumulated scheduler runtime
     };
 

template/sysroot/include/Api/Syscall.hpp

@@ -701,7 +701,7 @@ namespace montauk::abi {
         uint8_t  state;        // 0=Free, 1=Ready, 2=Running, 3=Blocked, 4=Terminated
         uint8_t  _pad[3];
         char     name[64];
-        uint64_t heapUsed;     // heapNext - UserHeapBase (bytes)
+        uint64_t heapUsed;     // Distance from UserHeapBase to high-water mark
         uint64_t cpuTimeMs;    // accumulated scheduler runtime
     };