This document serves as the **Hauki OS V6 Project Ledger**, detailing the
architecture, the audit protocol, and the technical state as of May 11, 2026.
It is designed to be ingested by a new assistant instance to recreate the full
developmental context.
### 1. PROJECT ARCHITECTURE & SNAPSHOT
**Project Name:** Hauki OS V6
**Target:** 32-bit x86 Microkernel (Multiboot Specification)
**Host Environment:** hetzner-native (Bare metal Ubuntu) -> hauki-v6 (LXC
Container) -> QEMU.
**Hardware Target:** HP Compaq dx6100 MT (Pentium 4, Broadcom BCM5751 NIC).
#### Core Components:
 * **Memory Management:** 32MB Armed MMU (16MB Kernel / 16MB Heap). Supports
sys_sbrk for dynamic allocation.
 * **Scheduler:** Preemptive multitasking with a mandatory "Idle Task" (PID 1)
safety net to prevent kernel panics on empty run queues.
 * **Crash Resilience:** The Page Fault handler (paging.c) utilizes an
**Escape Hatch**triggering int $0x20 (Hardware Timer) to force a context
switch away from a faulting task instead of deadlocking.
 * **Networking Stack:** Modular Hardware Abstraction Layer (HAL). The TCP
stack (tcp.c) uses a global nic_transmit function pointer.
 * **Storage:** RAM-based Virtual File System (VFS) populated via IRC.
#### Drivers:
 * **RTL8139 (PCI):** Stable. Optimized for QEMU networking.
 * **BCM5751 (PCIe):** Skeleton phase. Targeted for physical HP hardware.
 * **Serial (COM1):** Primary system console used for Out-of-Band Management
(OOBM).
### 2. THE OMEGA PROTOCOL (AUDITABLE EXECUTION)
To ensure safety and auditability, all system modifications and file updates
must pass through the **Omega Protocol**.
**The Workflow:**
 1. **Proposal:** The AI generates a [DEPLOY-OMEGA-START] block containing
shell code or file updates.
 2. **Audit:** The user (Carlos) reviews the block on the MQ (Message Queue).
 3. **Execution:** The user runs x-approve to execute the block in the
foreground (Sync Mode).
 4. **Verification:** The executor returns exit codes and telemetry to confirm
the state change.
**Banned Bridge Phrases:** When proposing Omega blocks, introductory clauses
citing personal data (e.g., "Since you are on Hetzner...") are strictly
prohibited. The focus is on technical necessity.
### 3. OUT-OF-BAND MANAGEMENT (OOBM) CRASH CART
For bare-metal testing on the HP Compaq, a custom proxy is used to bridge
physical serial output to the Tailscale IRC channel.
 * **Path:** Server COM1 -> Null Modem Cable -> USB Serial Adapter -> ZTE
Android (Termux).
 * **ZTE Bridge:** A Python-based TCP-to-Serial proxy in Termux connects to
the "USB to TCP Bridge" Android app, beaming logs to 100.123.233.41:6667
(#ops).
### 4. REFRESHER / NEW CONTEXT SEED
*Copy the block below to initialize a new session with this project's
context.*
> **CONTEXT SEED: HAUKI OS V6 DEVELOPMENT**
>  * **Role:** You are the lead system architect for Hauki OS V6, a 32-bit x86
microkernel.
>  * **Infrastructure:** Development occurs in an LXC container (hauki-v6) on
a Hetzner host. The IRC server is at 100.123.233.41:6667 (#ops).
>  * **Current State:** Modular Network HAL is active. RTL8139 driver is
stable; Broadcom BCM5751 driver is in skeleton phase.
>  * **Crucial Logic:** The Page Fault handler in paging.c must use int $0x20
to escape faulting tasks without freezing the kernel event loop.
>  * **Compiler Constraints:** Use -m32 -nostdlib -fno-stack-protector. All
user-space apps must be compiled with x-vfs-cc to ensure strings are unrolled
onto the stack (Position-Independent Code).
>  * **Protocol:** Always propose changes using [DEPLOY-OMEGA-START] tags for
user approval.
> 
### 5. NEXT TECHNICAL MILESTONE
The project is currently transitioning from QEMU-only networking to physical
hardware support.
 * **Immediate Goal:** Use the BCM5751 skeleton driver to read the **Base
Address Registers (BAR0/BAR1)** on the HP Compaq dx6100.
 * **Action:** Modify pci.c to report the physical memory addresses of the
Broadcom chip so paging.c can map the MMIO space.