refactor: Simplify comments and remove redundant descriptions in constants files

12 files changed, 15 insertions, 301 deletions

diff --git a/mirai/common/constants/interrupts.zig b/mirai/common/constants/interrupts.zig
index 64872ee..6628cee 100644
--- a/mirai/common/constants/interrupts.zig
+++ b/mirai/common/constants/interrupts.zig
@@ -1,118 +1,39 @@
-//! Interrupt Constants - Exception and IRQ vectors
+//! Interrupt vectors
 
-// ============================================================================
-// Exception Vectors
-// ============================================================================
-
-/// Divide by zero exception
 pub const EXCEPTION_DIVIDE_ERROR: u8 = 0;
-
-/// Debug exception
 pub const EXCEPTION_DEBUG: u8 = 1;
-
-/// Non-maskable interrupt
 pub const EXCEPTION_NMI: u8 = 2;
-
-/// Breakpoint exception
 pub const EXCEPTION_BREAKPOINT: u8 = 3;
-
-/// Overflow exception
 pub const EXCEPTION_OVERFLOW: u8 = 4;
-
-/// Bound range exceeded
 pub const EXCEPTION_BOUND_RANGE: u8 = 5;
-
-/// Invalid opcode
 pub const EXCEPTION_INVALID_OPCODE: u8 = 6;
-
-/// Device not available
 pub const EXCEPTION_DEVICE_NOT_AVAILABLE: u8 = 7;
-
-/// Double fault
 pub const EXCEPTION_DOUBLE_FAULT: u8 = 8;
-
-/// Invalid TSS
 pub const EXCEPTION_INVALID_TSS: u8 = 10;
-
-/// Segment not present
 pub const EXCEPTION_SEGMENT_NOT_PRESENT: u8 = 11;
-
-/// Stack-segment fault
 pub const EXCEPTION_STACK_FAULT: u8 = 12;
-
-/// General protection fault
 pub const EXCEPTION_GENERAL_PROTECTION: u8 = 13;
-
-/// Page fault
 pub const EXCEPTION_PAGE_FAULT: u8 = 14;
-
-/// x87 FPU error
 pub const EXCEPTION_FPU_ERROR: u8 = 16;
-
-/// Alignment check
 pub const EXCEPTION_ALIGNMENT_CHECK: u8 = 17;
-
-/// Machine check
 pub const EXCEPTION_MACHINE_CHECK: u8 = 18;
-
-/// SIMD floating-point exception
 pub const EXCEPTION_SIMD_EXCEPTION: u8 = 19;
 
-// ============================================================================
-// Hardware IRQ Vectors
-// ============================================================================
-
-/// Timer interrupt vector (IRQ 0)
 pub const IRQ_TIMER: u8 = 32;
-
-/// Keyboard interrupt vector (IRQ 1)
 pub const IRQ_KEYBOARD: u8 = 33;
-
-/// Cascade (IRQ 2) - used internally by PICs
 pub const IRQ_CASCADE: u8 = 34;
-
-/// COM2/COM4 serial port (IRQ 3)
 pub const IRQ_COM2: u8 = 35;
-
-/// COM1/COM3 serial port (IRQ 4)
 pub const IRQ_COM1: u8 = 36;
-
-/// LPT2 parallel port (IRQ 5)
 pub const IRQ_LPT2: u8 = 37;
-
-/// Floppy disk controller (IRQ 6)
 pub const IRQ_FLOPPY: u8 = 38;
-
-/// LPT1 parallel port (IRQ 7)
 pub const IRQ_LPT1: u8 = 39;
-
-/// Real-time clock (IRQ 8)
 pub const IRQ_RTC: u8 = 40;
-
-/// ACPI (IRQ 9)
 pub const IRQ_ACPI: u8 = 41;
-
-/// Available (IRQ 10)
 pub const IRQ_AVAILABLE_10: u8 = 42;
-
-/// Available (IRQ 11)
 pub const IRQ_AVAILABLE_11: u8 = 43;
-
-/// PS/2 Mouse (IRQ 12)
 pub const IRQ_MOUSE: u8 = 44;
-
-/// FPU/Coprocessor (IRQ 13)
 pub const IRQ_FPU: u8 = 45;
-
-/// Primary ATA (IRQ 14)
 pub const IRQ_PRIMARY_ATA: u8 = 46;
-
-/// Secondary ATA (IRQ 15)
 pub const IRQ_SECONDARY_ATA: u8 = 47;
 
-// ============================================================================
-// Software Interrupt Vectors
-// ============================================================================
-
-/// Invocation interrupt vector
 pub const INTERRUPT_INVOCATION: u8 = 0x80;
diff --git a/mirai/common/constants/invocations.zig b/mirai/common/constants/invocations.zig
index dce1ef7..7a44406 100644
--- a/mirai/common/constants/invocations.zig
+++ b/mirai/common/constants/invocations.zig
@@ -1,4 +1,4 @@
-//! Invocation numbers and constants
+//! Invocation numbers
 
 pub const EXIT: u64 = 0x01;
 pub const ATTACH: u64 = 0x02;
@@ -15,8 +15,5 @@ pub const SETLOCATION: u64 = 0x0C;
 pub const POSTMAN: u64 = 0x0D;
 pub const WIPE: u64 = 0x0E;
 
-/// Error return value for invocations (-1 as unsigned)
 pub const ERROR: u64 = @as(u64, @bitCast(@as(i64, -1)));
-
-/// No data available (used by getkeychar)
 pub const NO_DATA: u64 = @as(u64, @bitCast(@as(i64, -2)));
diff --git a/mirai/common/constants/kata.zig b/mirai/common/constants/kata.zig
index ed89aa0..7f60b01 100644
--- a/mirai/common/constants/kata.zig
+++ b/mirai/common/constants/kata.zig
@@ -1,64 +1,23 @@
-//! Kata Constants - Kata execution and scheduling related constants
+//! Kata constants
 
 const memory = @import("memory.zig");
 
-// ============================================================================
-// Kata Stack Configuration
-// ============================================================================
-
-/// Kata stack top address (grows downward)
 pub const KATA_STACK_TOP: u64 = 0x00007FFFFFF00000;
-
-/// Number of pages allocated for kata stack
-pub const KATA_STACK_PAGES: u64 = 64; // 256KB
-
-/// Total kata stack size in bytes
+pub const KATA_STACK_PAGES: u64 = 64;
 pub const KATA_STACK_SIZE: u64 = KATA_STACK_PAGES * memory.PAGE_SIZE;
-
-/// Mirai (kernel) stack size per kata (one page)
 pub const MIRAI_STACK_SIZE: u64 = memory.PAGE_SIZE;
 
-// ============================================================================
-// Sensei (Scheduler) Timing Constants
-// ============================================================================
-
-/// Timer tick frequency (nanoseconds per tick)
-pub const TIMER_TICK_NS: u64 = 1_000_000; // 1ms
-
-/// Sensei time slice (in timer ticks)
-pub const SENSEI_TIME_SLICE: u64 = 10; // 10ms
-
-// ============================================================================
-// Kata State Values
-// ============================================================================
+pub const TIMER_TICK_NS: u64 = 1_000_000;
+pub const SENSEI_TIME_SLICE: u64 = 10;
 
-/// Kata is ready to run
 pub const STATE_READY: u8 = 0;
-
-/// Kata is currently running
 pub const STATE_RUNNING: u8 = 1;
-
-/// Kata is blocked waiting for I/O
 pub const STATE_BLOCKED: u8 = 2;
-
-/// Kata is waiting for another kata
 pub const STATE_WAITING: u8 = 3;
-
-/// Kata has dissolved (exited)
 pub const STATE_DISSOLVED: u8 = 4;
 
-// ============================================================================
-// Postman (Letter) Constants
-// ============================================================================
-
-/// No letter in inbox
 pub const LETTER_NONE: u8 = 0;
-
-/// Navigate (change location) letter
 pub const LETTER_NAVIGATE: u8 = 1;
 
-/// Postman mode: send letter to parent
 pub const POSTMAN_SEND: u64 = 0;
-
-/// Postman mode: read letter from inbox
 pub const POSTMAN_READ: u64 = 1;
diff --git a/mirai/common/constants/memory.zig b/mirai/common/constants/memory.zig
index 1625a4f..78afb46 100644
--- a/mirai/common/constants/memory.zig
+++ b/mirai/common/constants/memory.zig
@@ -1,38 +1,16 @@
-//! Memory Constants - Page sizes, address space layout, and page table definitions
+//! Memory constants
 
-// ============================================================================
-// Page and Memory Block Sizes
-// ============================================================================
-
-/// Standard page size (4KB on x86-64)
 pub const PAGE_SIZE: u64 = 4096;
-
-/// Page offset mask (bits 0-11)
 pub const PAGE_OFFSET_MASK: u64 = 0xFFF;
-
-/// Page frame mask (clears offset bits)
 pub const PAGE_FRAME_MASK: u64 = ~PAGE_OFFSET_MASK;
 
-// ============================================================================
-// Memory Address Space Layout
-// ============================================================================
-
-/// Higher-half Mirai (kernel) space start (canonical address boundary)
 pub const HIGHER_HALF_START: u64 = 0xFFFF800000000000;
-
-/// Mirai physical start address (loaded at 1MB)
 pub const MIRAI_PHYSICAL_START: u64 = 0x100000;
-
-/// Mirai physical end address
 pub const MIRAI_PHYSICAL_END: u64 = 0x500000;
-
-/// Virtual address where Mirai is mapped
 pub const MIRAI_VIRTUAL_START: u64 = HIGHER_HALF_START + MIRAI_PHYSICAL_START;
 
-/// External linker symbol marking the end of the Mirai binary
 extern const _kernel_end: u8;
 
-/// Dynamically calculate the physical address where Mirai binary ends
 pub fn MIRAI_END() u64 {
     const link_addr = @intFromPtr(&_kernel_end);
     if (link_addr >= HIGHER_HALF_START) {
@@ -42,122 +20,63 @@ pub fn MIRAI_END() u64 {
     }
 }
 
-// ============================================================================
-// Kata (Userspace) Address Space Layout
-// ============================================================================
-
-/// Kata virtual address start (first valid page after null page)
 pub const KATA_SPACE_START: u64 = 0x1000;
-
-/// Kata virtual address maximum (canonical address boundary)
 pub const KATA_SPACE_END: u64 = 0x0000800000000000;
 
-// ============================================================================
-// Page Table Entry Flags
-// ============================================================================
-
-/// Page is present in memory
 pub const PTE_PRESENT: u64 = 1 << 0;
-
-/// Page is writable
 pub const PTE_WRITABLE: u64 = 1 << 1;
-
-/// Page is accessible from kata mode
 pub const PTE_USER: u64 = 1 << 2;
-
-/// Page has write-through caching
 pub const PTE_WRITE_THROUGH: u64 = 1 << 3;
-
-/// Page caching is disabled
 pub const PTE_CACHE_DISABLE: u64 = 1 << 4;
-
-/// Page has been accessed
 pub const PTE_ACCESSED: u64 = 1 << 5;
-
-/// Page has been written to
 pub const PTE_DIRTY: u64 = 1 << 6;
-
-/// Page is a huge page (2MB or 1GB)
 pub const PTE_HUGE_PAGE: u64 = 1 << 7;
-
-/// Page is global (not flushed on CR3 reload)
 pub const PTE_GLOBAL: u64 = 1 << 8;
-
-/// Execute disable bit
 pub const PTE_NO_EXECUTE: u64 = 1 << 63;
 
-// ============================================================================
-// Page Table Structure
-// ============================================================================
-
-/// Number of entries in each page table level
 pub const PAGE_TABLE_ENTRIES: usize = 512;
-
-/// Shift for PML4 index (bits 39-47)
 pub const PML4_SHIFT: u6 = 39;
-
-/// Shift for PDPT index (bits 30-38)
 pub const PDPT_SHIFT: u6 = 30;
-
-/// Shift for PD index (bits 21-29)
 pub const PD_SHIFT: u6 = 21;
-
-/// Shift for PT index (bits 12-20)
 pub const PT_SHIFT: u6 = 12;
-
-/// Mask for table indices (9 bits = 512 entries)
 pub const TABLE_INDEX_MASK: u64 = 0x1FF;
 
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-/// Align address down to page boundary
 pub inline fn align_down(addr: u64) u64 {
     return addr & PAGE_FRAME_MASK;
 }
 
-/// Align address up to page boundary
 pub inline fn align_up(addr: u64) u64 {
     return (addr + PAGE_SIZE - 1) & PAGE_FRAME_MASK;
 }
 
-/// Calculate number of pages needed for given size
 pub inline fn pages_for_size(size: u64) u64 {
     return (size + PAGE_SIZE - 1) / PAGE_SIZE;
 }
 
-/// Check if address is page-aligned
 pub inline fn is_page_aligned(addr: u64) bool {
     return (addr & PAGE_OFFSET_MASK) == 0;
 }
 
-/// Extract PML4 index from virtual address
 pub inline fn pml4_index(vaddr: u64) u64 {
     return (vaddr >> PML4_SHIFT) & TABLE_INDEX_MASK;
 }
 
-/// Extract PDPT index from virtual address
 pub inline fn pdpt_index(vaddr: u64) u64 {
     return (vaddr >> PDPT_SHIFT) & TABLE_INDEX_MASK;
 }
 
-/// Extract PD index from virtual address
 pub inline fn pd_index(vaddr: u64) u64 {
     return (vaddr >> PD_SHIFT) & TABLE_INDEX_MASK;
 }
 
-/// Extract PT index from virtual address
 pub inline fn pt_index(vaddr: u64) u64 {
     return (vaddr >> PT_SHIFT) & TABLE_INDEX_MASK;
 }
 
-/// Get physical address from higher-half virtual address
 pub inline fn virt_to_phys(vaddr: u64) u64 {
     return vaddr - HIGHER_HALF_START;
 }
 
-/// Get higher-half virtual address from physical address
 pub inline fn phys_to_virt(paddr: u64) u64 {
     return paddr + HIGHER_HALF_START;
 }
diff --git a/mirai/common/constants/msr.zig b/mirai/common/constants/msr.zig
index 4a6eea2..89a8367 100644
--- a/mirai/common/constants/msr.zig
+++ b/mirai/common/constants/msr.zig
@@ -1,6 +1,5 @@
 //! Model Specific Register addresses and values
 
-// MSR addresses
 pub const IA32_EFER: u32 = 0xC0000080;
 pub const IA32_STAR: u32 = 0xC0000081;
 pub const IA32_LSTAR: u32 = 0xC0000082;
@@ -10,15 +9,12 @@ pub const IA32_FS_BASE: u32 = 0xC0000100;
 pub const IA32_GS_BASE: u32 = 0xC0000101;
 pub const IA32_KERNEL_GS_BASE: u32 = 0xC0000102;
 
-// EFER bits
 pub const EFER_SCE: u64 = 1 << 0;
 pub const EFER_LME: u64 = 1 << 8;
 pub const EFER_LMA: u64 = 1 << 10;
 pub const EFER_NXE: u64 = 1 << 11;
 
-// STAR register bit positions
 pub const STAR_KERNEL_CS_SHIFT: u6 = 32;
 pub const STAR_USER_BASE_SHIFT: u6 = 48;
 
-// FMASK: mask IF (interrupt flag) during syscall
 pub const FMASK_IF: u64 = 0x200;
diff --git a/mirai/common/errors/fs.zig b/mirai/common/errors/fs.zig
index 74799ce..efa9b58 100644
--- a/mirai/common/errors/fs.zig
+++ b/mirai/common/errors/fs.zig
@@ -1,27 +1,15 @@
-//! Filesystem Errors - AFS and storage related errors
+//! Filesystem errors
 
-/// Errors related to filesystem operations
 pub const FsError = error{
-    /// Unit or stack not found
     NotFound,
-    /// Location is invalid
     InvalidLocation,
-    /// Not a stack
     NotAStack,
-    /// Not a unit
     NotAUnit,
-    /// Stack is not empty
     StackNotEmpty,
-    /// Unit already exists
     AlreadyExists,
-    /// Filesystem is full
     NoSpace,
-    /// Filesystem is read-only
     ReadOnly,
-    /// Disk I/O error
     DiskError,
-    /// Filesystem corruption detected
     Corrupted,
-    /// Cannot create unit
     CannotCreate,
 };
diff --git a/mirai/common/errors/io.zig b/mirai/common/errors/io.zig
index bf2f6b2..c7afdaf 100644
--- a/mirai/common/errors/io.zig
+++ b/mirai/common/errors/io.zig
@@ -1,27 +1,15 @@
-//! I/O Errors - Input/output related errors
+//! I/O errors
 
-/// Errors related to I/O operations
 pub const IoError = error{
-    /// Invalid attachment
     InvalidAttachment,
-    /// No more attachments available
     TooManyAttachments,
-    /// View operation failed
     ViewFailed,
-    /// Mark operation failed
     MarkFailed,
-    /// Invalid device
     InvalidDevice,
-    /// Cannot view from device
     CannotView,
-    /// Cannot mark to device
     CannotMark,
-    /// Bad pointer
     BadPointer,
-    /// Buffer too small
     BufferTooSmall,
-    /// Unknown device
     UnknownDevice,
-    /// Letter send failed
     SendFailed,
 };
diff --git a/mirai/common/errors/kata.zig b/mirai/common/errors/kata.zig
index 2218bfb..e997d43 100644
--- a/mirai/common/errors/kata.zig
+++ b/mirai/common/errors/kata.zig
@@ -1,15 +1,9 @@
-//! Kata Errors - Kata-related errors
+//! Kata errors
 
-/// Errors related to kata management
 pub const KataError = error{
-    /// No free kata slots available
     TooManyKatas,
-    /// Kata ID not found
     KataNotFound,
-    /// Invalid kata state for operation
     InvalidState,
-    /// Kata is not a child of current kata
     NotChild,
-    /// Cannot wait for self
     WaitingSelf,
 };
diff --git a/mirai/common/errors/memory.zig b/mirai/common/errors/memory.zig
index d1e4503..58d77b8 100644
--- a/mirai/common/errors/memory.zig
+++ b/mirai/common/errors/memory.zig
@@ -1,17 +1,10 @@
-//! Memory Errors - Memory management related errors
+//! Memory errors
 
-/// Errors related to memory management
 pub const MemoryError = error{
-    /// Out of physical memory
     OutOfMemory,
-    /// Invalid address
     InvalidAddress,
-    /// Page not present
     PageNotPresent,
-    /// Allocation failed
     AllocationFailed,
-    /// Address not aligned
     NotAligned,
-    /// Permission denied
     PermissionDenied,
 };
diff --git a/mirai/common/limits/fs.zig b/mirai/common/limits/fs.zig
index ed79bc2..be03975 100644
--- a/mirai/common/limits/fs.zig
+++ b/mirai/common/limits/fs.zig
@@ -1,18 +1,5 @@
-//! Filesystem Limits - Unit and location related limits
+//! Filesystem limits
 
-// ============================================================================
-// Location Limits
-// ============================================================================
-
-/// Maximum location length for units and stacks
 pub const MAX_LOCATION_LENGTH: usize = 255;
-
-/// Maximum identity length
 pub const MAX_IDENTITY_LENGTH: usize = 255;
-
-// ============================================================================
-// Unit Size Limits
-// ============================================================================
-
-/// Maximum unit size that can be loaded into memory (1MB)
 pub const MAX_UNIT_SIZE: u64 = 1024 * 1024;
diff --git a/mirai/common/limits/io.zig b/mirai/common/limits/io.zig
index 3f44522..dfc2e73 100644
--- a/mirai/common/limits/io.zig
+++ b/mirai/common/limits/io.zig
@@ -1,17 +1,6 @@
-//! I/O Limits - Input/output related limits
+//! I/O limits
 
-// ============================================================================
-// Buffer Limits
-// ============================================================================
-
-/// Maximum size for a single mark operation (1MB)
 pub const MAX_MARK_SIZE: u64 = 1024 * 1024;
-
-/// Maximum size for a single view operation (1MB)
 pub const MAX_VIEW_SIZE: u64 = 1024 * 1024;
-
-/// Mirai buffer size for copying kata data
 pub const MIRAI_COPY_BUFFER_SIZE: usize = 256;
-
-/// Maximum string length for invocation string parameters
 pub const MAX_STRING_LENGTH: usize = 4096;
diff --git a/mirai/common/limits/memory.zig b/mirai/common/limits/memory.zig
index fe98bd0..dba20e6 100644
--- a/mirai/common/limits/memory.zig
+++ b/mirai/common/limits/memory.zig
@@ -1,44 +1,27 @@
-//! Memory Limits - Address space limits and validation helpers
+//! Memory limits
 
 const memory_const = @import("../constants/memory.zig");
 
-// ============================================================================
-// Address Space Limits
-// ============================================================================
-
-/// Kata space maximum (below higher-half)
 pub const KATA_SPACE_MAX: u64 = memory_const.KATA_SPACE_END;
-
-/// First valid kata space page (page 0 is always invalid for null pointer detection)
 pub const KATA_SPACE_MIN: u64 = memory_const.KATA_SPACE_START;
-
-/// Higher-half Mirai space start
 pub const MIRAI_SPACE_START: u64 = memory_const.HIGHER_HALF_START;
 
-// ============================================================================
-// Validation Helpers
-// ============================================================================
-
-/// Check if a pointer is in valid kata space range
 pub inline fn is_valid_kata_pointer(ptr: u64) bool {
     return ptr >= KATA_SPACE_MIN and ptr < KATA_SPACE_MAX;
 }
 
-/// Check if a virtual address is in kata space
 pub inline fn is_kata_address(addr: u64) bool {
     return addr < KATA_SPACE_MAX;
 }
 
-/// Check if a virtual address is in Mirai space
 pub inline fn is_mirai_address(addr: u64) bool {
     return addr >= MIRAI_SPACE_START;
 }
 
-/// Check if a memory range is entirely within kata space
 pub inline fn is_kata_range(start: u64, size: u64) bool {
     if (start >= KATA_SPACE_MAX) return false;
     if (size == 0) return true;
     const end = start +% size;
-    if (end < start) return false; // Overflow occurred
+    if (end < start) return false;
     return end <= KATA_SPACE_MAX;
 }