.drone.yml

@@ -25,6 +25,30 @@ steps:
       - chmod +x /drone/src/toolchain/*.sh
       - /drone/src/toolchain/compile.sh
       
+  - name: deploy-docs
+    image: alpine:latest
+    depends_on:
+      - compile
+    when:
+      branch:
+        - master
+        - develop
+        - feature/mkdocs
+    volumes:
+      - name: docs-htdocs
+        path: /htdocs
+    commands:
+      - apk add --no-cache rsync
+      - |
+        if [ "${DRONE_BRANCH}" = "master" ]; then
+          DEST="/htdocs/master"
+        else
+          DEST="/htdocs/develop"
+        fi
+      - mkdir -p "$DEST"
+      - rsync -a --delete site/ "$DEST/"
+      - echo "Documentation deployed to ${DRONE_BRANCH}"
+
   - name: upload-iso-artifact
     image: alpine/git
     depends_on:
@@ -64,3 +88,9 @@ steps:
       webhook_token:
         from_secret: discord_webhook_secret
       message: "**Asuro Build**\n\n{{#success build.status}}✅ Build successful!\n\n{{else}}❌ Build failed!\n\n{{/success}}Repository: `{{repo.namespace}}/{{repo.name}}`\nBranch: `{{commit.branch}}`\nCommit: `{{commit.sha}}`\nAuthor: `{{commit.author}} <{{commit.email}}>`\n\nGitea Diff: [Link](<{{commit.link}}>)\nDrone Build: [Link](<{{build.link}}>)\n\nMessage: {{commit.message}}"
+
+volumes:
+  - name: docs-htdocs
+    host:
+      path: /mnt/user/htdocs/asuro_docs
+

.gitignore

@@ -16,6 +16,7 @@ dockerout.txt
 AGENTS.md
 lessons_learnt.md
 *.log
-/doc/*.md
 wasuro
 src/core/core.version.pas
+site/*
+!site/.gitkeep

Dockerfile

@@ -5,9 +5,12 @@ VOLUME ["/code"]
 ENV DEBIAN_FRONTEND=noninteractive
 RUN dpkg --add-architecture i386
 RUN apt-get update && apt-get install -y \
-	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin gcc gcc-multilib && \
+	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin gcc gcc-multilib \
+	python3 python3-pip && \
 	apt-get clean my room
 
+RUN pip3 install --no-cache-dir --break-system-packages "mkdocs>=1.6,<2" mkdocs-material
+
 SHELL ["/bin/bash", "-c"]
 ARG FPC_VERSION=3.2.2
 RUN curl -sL https://sourceforge.net/projects/freepascal/files/Linux/$FPC_VERSION/fpc-$FPC_VERSION.i386-linux.tar/download | tar -xf - && \

doc/compat/lmemorymanager.md

@@ -0,0 +1,94 @@
+# lmemorymanager
+
+Compatibility shim that re-exports the `memory.heap` API under the legacy unit name.
+
+## Overview
+
+The Wasuro WASM VM project references the old unit name `lmemorymanager` for heap memory operations. Because the Wasuro source tree cannot be modified, this shim unit re-exports every public symbol from `memory.heap` so that `uses lmemorymanager` continues to compile without changes. All functions are thin inline wrappers that delegate directly to their `memory.heap` counterparts.
+
+## Dependencies
+
+- `memory.heap` -- the canonical heap allocator implementation in the Asuro kernel.
+
+## Constants
+
+### ALLOC_UNIT
+Re-exported from `memory.heap.ALLOC_UNIT`. The base allocation unit size used by the heap allocator.
+
+### DATA_OFFSET
+Re-exported from `memory.heap.DATA_OFFSET`. Byte offset from a heap block header to the start of user data.
+
+### PAGE_SIZE_LMM
+Re-exported from `memory.heap.PAGE_SIZE_LMM`. Page size used by the lightweight memory manager.
+
+### TOTAL_UNITS
+Re-exported from `memory.heap.TOTAL_UNITS`. Total number of allocation units per heap page.
+
+### BITMAP_DWORDS
+Re-exported from `memory.heap.BITMAP_DWORDS`. Number of 32-bit words in the per-page allocation bitmap.
+
+### SIZE_PREFIX
+Re-exported from `memory.heap.SIZE_PREFIX`. Size of the prefix stored before each allocation to record its length.
+
+### LARGE_ALLOC_MAGIC
+Re-exported from `memory.heap.LARGE_ALLOC_MAGIC`. Magic value used to identify large (multi-page) allocations.
+
+## Types
+
+### PHeapPageHeader / THeapPageHeader
+Re-exported from `memory.heap`. Pointer and record types describing the header structure at the beginning of each heap page.
+
+## Functions and Procedures
+
+### init
+```pascal
+procedure init;
+```
+Initializes the heap memory manager by delegating to `memory.heap.init`.
+
+### kalloc
+```pascal
+function kalloc(size: uint32): void;
+```
+Allocates `size` bytes from the kernel heap and returns a pointer to the allocated memory.
+
+### klalloc
+```pascal
+function klalloc(size: uint32): void;
+```
+Performs a large kernel allocation of `size` bytes and returns a pointer to the allocated memory.
+
+### klfree
+```pascal
+procedure klfree(address: uint32);
+```
+Frees a large allocation previously obtained via `klalloc`.
+
+### kpalloc
+```pascal
+function kpalloc(address: uint32): void;
+```
+Allocates a heap page at the specified address and returns a pointer to it.
+
+### kfree
+```pascal
+procedure kfree(area: void);
+```
+Frees a standard allocation previously obtained via `kalloc`.
+
+### lmm_total_free
+```pascal
+function lmm_total_free: uint32;
+```
+Returns the total number of free bytes available across all heap pages.
+
+### lmm_page_count
+```pascal
+function lmm_page_count: uint32;
+```
+Returns the current number of heap pages managed by the allocator.
+
+## Notes
+
+- Every function and procedure in the implementation section is marked `inline`, so the compiler eliminates the wrapper overhead entirely.
+- This unit exists solely for backward compatibility with the Wasuro WASM VM build. New kernel code should use `memory.heap` directly.

doc/compat/types.md

@@ -0,0 +1,16 @@
+# types
+
+Empty compatibility shim that satisfies `uses types` references from the Wasuro WASM VM project.
+
+## Overview
+
+Some units in the Wasuro WASM VM source tree include `uses types` to pull in shared type definitions from the Asuro kernel. In the kernel proper, those types may be declared elsewhere or may no longer be needed in the WASM context. This stub unit provides an empty `types` compilation unit so that `uses types` resolves without error during the Wasuro build.
+
+## Dependencies
+
+None.
+
+## Notes
+
+- The unit declares no constants, types, variables, or routines. Its only purpose is to exist as a valid compilation unit.
+- If Wasuro code is ever updated to remove the `uses types` dependency, this shim can be deleted.

doc/index.md

@@ -0,0 +1,32 @@
+# Asuro OS
+
+Asuro is a 32-bit x86 operating system kernel written in Free Pascal and x86 assembly.
+
+## Documentation Structure
+
+- **Kernel Entry** -- The `asuro.pas` main unit and boot sequence.
+- **Architecture (x86)** -- CPU initialization, descriptor tables, interrupt handling, fault handlers, memory management, and process scheduling for the i386 target.
+- **Boot** -- Splash screen and early boot visuals.
+- **Core** -- Foundational libraries including data structures, encoding algorithms, string handling, graphics primitives, and the kernel panic subsystem.
+- **Memory** -- Heap allocator (`kalloc`/`kfree`) and page-level allocation.
+- **Processes** -- Process lifecycle, round-robin scheduling, and inter-process messaging.
+- **I/O** -- Standard I/O (shell command dispatch) and the system log fan-out.
+- **Debug** -- Execution tracer with ring-buffer call stack recording.
+- **Drivers** -- Hardware abstraction covering PCI/USB buses, HID devices, networking (E1000, TCP/IP stack), storage (IDE, AHCI, VFS, file systems), video (VESA, LVGL, double-buffering), serial I/O, and timers.
+- **Services** -- Background daemons for graphics rendering and USB hotplug.
+- **Applications** -- Userland commands and utilities: terminal, text editor, disk tools, network tools, and a WebAssembly runtime.
+- **Compatibility** -- Shim layers for legacy code.
+- **LVGL Headers** -- Configuration and patches for the LVGL v9.2.2 GUI library.
+- **Planning** -- Design documents and architectural notes for subsystems under development.
+- **Toolchain** -- Build pipeline documentation covering compilation, linking, and ISO generation.
+
+## Building
+
+The kernel is built inside Docker using a containerized FreePascal 3.2.2 toolchain:
+
+```bash
+docker compose build builder
+docker compose run builder
+```
+
+The documentation site will be available at `http://docs.asuro.xyz`.

doc/lvglh/hack_14.md

@@ -0,0 +1,53 @@
+# hack_14.c
+
+LVGL bitmap font source for the Hack Regular typeface at 14 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Hack Regular TrueType font (`Hack-Regular.ttf`) for use with LVGL. It provides a complete monospaced programmer font covering the full Basic Multilingual Plane (Unicode range 0x0000--0xFFFF). The font is intended for use in terminal emulators, code editors, or any UI element within Asuro that benefits from a fixed-width typeface.
+
+The file was generated by the LVGL font converter tool and is approximately 12,900 lines (~548 KB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### HACK_14
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Hack Regular |
+| Size | 14 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 19 px |
+| Baseline | 5 px from bottom |
+| Underline position | -2 |
+| Underline thickness | 1 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t hack_14;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&hack_14` when assigning fonts to labels, text areas, or other text-bearing widgets.
+
+## Generation Command
+
+```
+--bpp 4 --size 14 --no-compress --stride 1 --align 1 \
+--font Hack-Regular.ttf --range 0-65535 --format lvgl -o hack_14.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range makes this a large file. If binary size is a concern, the range could be narrowed to only the code points actually used.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/lvglh/lv_conf.md

@@ -0,0 +1,133 @@
+# lv_conf.h
+
+LVGL v9.2.2 configuration header tailored for the Asuro bare-metal kernel environment.
+
+## Overview
+
+This file configures the LVGL graphics library for use inside the Asuro kernel, where no standard C library, operating system, or GPU hardware is available. It selects a 32-bit XRGB8888 color depth to match the VESA framebuffer, routes all stdlib functionality through LVGL's built-in implementations, enables only the software renderer, and disables every hardware backend, filesystem driver, and image decoder. The result is a minimal but functional GUI stack that runs entirely in kernel space.
+
+## Configuration Options / Defines
+
+### Color Settings
+
+#### LV_COLOR_DEPTH
+Value: `32`. Matches the VESA XRGB8888 framebuffer used by Asuro.
+
+### Standard Library Wrappers
+
+#### LV_USE_STDLIB_MALLOC / LV_USE_STDLIB_STRING / LV_USE_STDLIB_SPRINTF
+Value: `LV_STDLIB_BUILTIN`. All three are set to use LVGL's own built-in implementations since no libc is available in the bare-metal environment.
+
+### Memory Pool
+
+#### LV_MEM_SIZE
+Value: `256 * 1024U` (256 KB). Size of LVGL's internal memory pool for widget allocations and draw buffers.
+
+#### LV_MEM_POOL_EXPAND_SIZE
+Value: `0`. Pool expansion is disabled; the 256 KB allocation is fixed.
+
+#### LV_MEM_ADR
+Value: `0`. LVGL allocates the pool itself rather than using a fixed address.
+
+### HAL Settings
+
+#### LV_DEF_REFR_PERIOD
+Value: `33` (milliseconds). Targets approximately 30 frames per second.
+
+#### LV_DPI_DEF
+Value: `96`. Standard screen DPI assumption.
+
+### Operating System
+
+#### LV_USE_OS
+Value: `LV_OS_NONE`. No OS abstraction layer; LVGL runs in a bare-metal cooperative model.
+
+### Rendering Configuration
+
+#### LV_USE_DRAW_SW
+Value: `1`. The software renderer is the sole rendering backend.
+
+Only the color formats actually used are enabled within the software renderer:
+
+| Define | Value | Description |
+|--------|-------|-------------|
+| `LV_DRAW_SW_SUPPORT_XRGB8888` | 1 | Primary framebuffer format |
+| `LV_DRAW_SW_SUPPORT_ARGB8888` | 1 | Alpha-blended surfaces |
+| `LV_DRAW_SW_SUPPORT_RGB888` | 1 | 24-bit fallback |
+| `LV_DRAW_SW_SUPPORT_RGB565` | 0 | Disabled |
+| All other formats | 0 | Disabled |
+
+#### LV_DRAW_SW_COMPLEX
+Value: `1`. Enables complex draw operations (shadows, rounded corners). Shadow cache is disabled (`LV_DRAW_SW_SHADOW_CACHE_SIZE = 0`); circle cache is set to 4 entries.
+
+#### LV_DRAW_LAYER_SIMPLE_BUF_SIZE
+Value: `24 * 1024` (24 KB). Buffer for simple layer rendering.
+
+#### GPU Backends
+All GPU-accelerated backends are disabled: VGLite, PXP, Dave2D, SDL, VG-Lite.
+
+### Logging
+
+#### LV_USE_LOG
+Value: `1`. Logging is enabled at `LV_LOG_LEVEL_WARN`. Printf-based logging, timestamps, and file/line info are all disabled to reduce overhead. All trace categories (memory, timer, indev, display refresh, events, object creation, layout, animation, cache) are disabled.
+
+### Assertions
+
+#### LV_USE_ASSERT_NULL / LV_USE_ASSERT_MALLOC
+Value: `1`. Null-pointer and malloc-failure assertions are active.
+
+#### LV_ASSERT_HANDLER
+Value: `{}` (no-op). The assert handler intentionally does nothing to avoid hanging the kernel on a failed assertion.
+
+### Fonts
+
+#### LV_FONT_MONTSERRAT_14
+Value: `1`. The only built-in Montserrat size enabled.
+
+#### LV_FONT_DEFAULT
+Value: `&lv_font_montserrat_14`. All other Montserrat sizes (8--48), compressed variants, and alternative font families (DejaVu, SimSun, UNSCII) are disabled.
+
+### Text Settings
+
+#### LV_TXT_ENC
+Value: `LV_TXT_ENC_UTF8`. UTF-8 text encoding. BiDi and Arabic/Persian character support are disabled.
+
+### Widgets
+
+Enabled widgets: AnimImg, Arc, Bar, Button, ButtonMatrix, Checkbox, Dropdown, Image, Keyboard, Label, Line, List, MsgBox, Roller, Slider, Spinner, Switch, TextArea, Table, TabView, Win.
+
+Disabled widgets: Calendar, Canvas, Chart, ImageButton, LED, Lottie, Menu, Scale, Span, SpinBox, TileView.
+
+### Themes
+
+#### LV_USE_THEME_DEFAULT
+Value: `1`. Dark mode enabled (`LV_THEME_DEFAULT_DARK = 1`) with 80 ms transition time.
+
+#### LV_USE_THEME_SIMPLE
+Value: `1`.
+
+#### LV_USE_THEME_MONO
+Value: `0`.
+
+### Layouts
+
+Both Flex and Grid layout engines are enabled.
+
+### Third-Party Libraries
+
+All filesystem drivers are disabled (stdio, POSIX, Win32, FatFS, MemFS, LittleFS). All image decoders are disabled (PNG, BMP, JPEG, GIF, RLE). FreeType, TinyTTF, Rlottie, vector graphics, LZ4, and FFmpeg are all disabled.
+
+### Device Drivers
+
+All platform-specific device drivers are disabled (SDL, X11, Wayland, Linux FBDEV, Linux DRM, NuttX, various SPI display controllers, Windows, OpenGLES, QNX). Display and input are handled by Asuro's own HAL layer.
+
+### Examples and Demos
+
+All built-in examples and demo applications are disabled.
+
+## Notes
+
+- The configuration is designed for minimal footprint. Features are enabled only when required by the Asuro desktop shell.
+- Since no libc is linked, all string, memory, and formatting operations fall through to LVGL's internal implementations.
+- The assert handler is a deliberate no-op to prevent the kernel from halting on non-critical UI assertion failures.
+- The 256 KB memory pool is fixed and cannot expand at runtime. UI complexity must stay within this budget.

doc/lvglh/lv_font_fa_solid_16.md

@@ -0,0 +1,55 @@
+# lv_font_fa_solid_16.c
+
+LVGL bitmap font source for Font Awesome 7 Free Solid at 16 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Font Awesome 7 Free Solid TrueType font (`Font Awesome 7 Free-Solid-900.ttf`) for use with LVGL. It provides a library of solid-style vector icons rendered as bitmaps, suitable for toolbar buttons, status indicators, navigation elements, and general iconography in the Asuro GUI.
+
+The file was generated by the LVGL font converter tool and is approximately 35,800 lines (~1.6 MB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### LV_FONT_FA_SOLID_16
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Font Awesome 7 Free Solid 900 |
+| Size | 16 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 20 px |
+| Baseline | 4 px from bottom |
+| Underline position | 0 |
+| Underline thickness | 0 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t lv_font_fa_solid_16;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&lv_font_fa_solid_16` when assigning icon fonts to labels or buttons. Font Awesome icons are addressed by their Unicode code points (e.g., `LV_SYMBOL_*` constants or raw `\uXXXX` escape sequences).
+
+## Generation Command
+
+```
+--bpp 4 --size 16 --no-compress --stride 1 --align 1 \
+--font "Font Awesome 7 Free-Solid-900.ttf" --range 0-65535 --format lvgl \
+-o lv_font_fa_solid_16.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range includes all Font Awesome solid icons. Since most code points in this range are blank (Font Awesome only defines glyphs for its icon set), the actual rendered glyph count is much smaller than the range suggests, but the descriptor tables still consume significant space.
+- The file is the largest in the `lvglh/` directory at approximately 1.6 MB. If binary size becomes a constraint, the Unicode range should be narrowed to only the icon code points actually used by the Asuro shell.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/planning/tracer.md

@@ -0,0 +1,95 @@
+# Tracer Refactor Design
+
+## Goal
+Refactor tracer.pas to eliminate all copy operations and use an O(1) ring buffer of PChar pointers. Maximize efficiency, minimize overhead, and guard against interrupt-driven corruption.
+
+## Agreed Design Decisions
+
+### 1. No String Copies — Store PChar Directly
+- **Decision**: Trust callers. Store the `PChar` pointer directly in the ring buffer — no `StringCopy`, no `kalloc`, no `kfree`.
+- **Contract**: `push_trace` MUST only be called with pointers to static/persistent data (e.g. string literals). Passing a heap-allocated or stack-allocated PChar that may later be freed is undefined behavior.
+- **Rationale**: All current callers pass string literals baked into the binary. This eliminates all heap allocation from the hot path.
+
+### 2. Ring Buffer (O(1) push)
+- **Structure**: `Traces: Array[0..MAX_TRACE-1] of PChar` (static, 40 slots).
+- **Index**: Single `head: uint32` variable.
+- **head semantics**: `head` always points to the **most recently written** slot.
+- **Push operation**:
+  ```pascal
+  head := (head + 1) mod MAX_TRACE;
+  Traces[head] := t_name;
+  ```
+- **Read operations**:
+  - `get_last_trace` → `Traces[head]`
+  - `get_trace_N(idx)` → `Traces[(head - idx + MAX_TRACE) mod MAX_TRACE]`
+    - idx=0 is the most recent trace, idx=39 is the oldest.
+- **No shifting loop**. Current O(n) shift of 40 entries on every push is eliminated.
+
+### 3. Initialization
+- All 40 slots set to `nil`.
+- `head` initialized to `MAX_TRACE - 1` (39).
+- `push_trace('kmain')` is called, which advances `head` to 0 and writes `'kmain'` to `Traces[0]`.
+- After init: head = 0, Traces[0] = 'kmain', all other slots = nil.
+
+### 4. Interrupt Safety — Locked Boolean (Skip on Contention)
+- **Mechanism**: A `Locked: Boolean` reentrancy guard around `push_trace` only.
+- **Behavior**: If `push_trace` is already executing (e.g., main code is mid-push) and an ISR calls `push_trace`, the ISR sees `Locked = true` and **silently drops** its trace.
+- **Readers are NOT locked**: `get_last_trace` and `get_trace_N` always proceed without checking `Locked`. Since `head` is advanced AFTER the pointer is written, readers always see a consistent state.
+- **Race window analysis**: There is a tiny window between checking `if not Locked` and setting `Locked := true` where an interrupt could cause both main code and ISR to enter the critical section. With the ring buffer design, the worst case is one trace being overwritten in the same slot — acceptable for a debug tracing tool.
+
+### 5. pop_trace — No-Op Stub
+- `pop_trace` remains in the interface as an empty procedure (no-op).
+- This preserves ABI compatibility with all existing callers (`vmemorymanager`, `vterminal`, `kernel`, etc.) without requiring changes across the codebase.
+- Traces are never removed from the ring buffer.
+
+### 6. get_trace_count — Always Returns MAX_TRACE (40)
+- No tracking of actual push count.
+- Callers already handle `nil` entries from unfilled slots.
+- This keeps the implementation simpler (one less variable to maintain atomically).
+
+### 7. TRACER_ENABLE Compile-Time Guard — Kept
+- All function bodies remain wrapped in `if TRACER_ENABLE then`.
+- When `TRACER_ENABLE = false`, the compiler dead-code eliminates all tracer logic for zero runtime cost.
+- `t_ready` provides orthogonal runtime enable/disable.
+
+### 8. Dead Code Removal
+The following unused code will be removed:
+- `PTracerEntry` / `TTracerEntry` record types (linked list — never used)
+- `head` / `tail` : `PTracerEntry` variables (shadow the new `head: uint32`)
+- `c_lock: Boolean` (declared, never set to true, unreachable guard)
+- Old `Locked: Boolean` replaced by new `Locked: Boolean` with same semantics but cleaner usage
+
+### 9. Uses Clause Cleanup
+- Remove `lmemorymanager` (no more kalloc/kfree).
+- Remove `serial` (not used).
+- Keep `util`, `strings`, `stdio` (used by terminal command).
+
+## Resulting push_trace (Pseudocode)
+```pascal
+procedure push_trace(t_name: PChar);
+begin
+  if TRACER_ENABLE then begin
+    if t_ready then begin
+      if not Locked then begin
+        Locked := true;
+        head := (head + 1) mod MAX_TRACE;
+        Traces[head] := t_name;
+        Locked := false;
+      end;
+    end;
+  end;
+end;
+```
+
+## Performance Summary
+| Operation     | Before             | After         |
+|---------------|--------------------|---------------|
+| push_trace    | O(n) shift + alloc | O(1) 2 stores |
+| pop_trace     | No-op              | No-op         |
+| get_last_trace| O(1)               | O(1)          |
+| get_trace_N   | O(1)               | O(1)          |
+| Memory alloc  | kalloc per push    | Zero          |
+| Memory free   | kfree on overflow  | Zero          |
+
+## Files Changed
+- `src/tracer.pas` — Full rewrite of internals, interface unchanged.

doc/planning/vfs.md

@@ -574,7 +574,7 @@ All functions that return `TError` use the shared error codes defined in `driver
 | `eFileNotLoaded` | Read on handle whose data hasn't loaded |
 | `eReadOnly` | Write on read-only handle |
 
-See [driver.storage.types.pas](../src/driver/storage/driver.storage.types.pas) for the full `TError` enumeration.
+See [driver.storage.types.pas](../src/driver/storage/driver.storage.types.md) for the full `TError` enumeration.
 
 ---