terminus.kernel

51 unique Foundation build inputs on bare metal — x86_64 and ARM64, TCP remote access, HTTP, display, USB, NVMe

Architecture

┌─────────────────────────────────────────┐
│            Terminus Manager             │
│  - Hardware callback ownership          │
│  - Kernel instance lifecycle            │
│  - Per-version process map + restart    │
│  - Hot-swap: old drains, new activates  │
└──────┬──────────────────┬───────────────┘
       │                  │
  ┌────▼─────┐      ┌────▼─────┐
  │ Kernel v1 │      │ Kernel v2 │
  │ (draining) │      │ (active)  │
  └───────────┘      └──────────┘

The shipped Foundation inventory is 27,458 lines across 62 compiled modules: 23,124 lines in 51 unique linked x86/ARM64 kernel inputs, a 3-line initrd runtime fixture, 4,056 lines in seven self-hosting compiler modules, and 275 lines in three stdlib modules. The unlinked 194-line scheduler_arm64_tmp.f scratch file is excluded.

Kernel Modules

Module	Purpose	Status
`serial.f`	UART COM1 driver	working
`gdt.f`	Global Descriptor Table	working
`pmm.f`	Physical memory manager (bitmap)	working
`heap.f`	Kernel heap (free-list)	working
`idt.f`	Interrupt Descriptor Table	working
`handlers.f`	ISR dispatch, PIC, timer/keyboard/mouse	working
`timer.f`	PIT at 100 Hz	working
`tss.f`	Task State Segment	working
`scheduler.f`	64-slot round robin, 64 KiB process stacks	cooperative boot + preemptive services
`preempt.f`	Timer-ISR context switch and exit handoff	working
`tfs.f`	Validated mount, checked lookup, and transactional file updates	five faults + persistence proven
`virtio_blk.f`	Block device (VirtIO + ramdisk fallback)	working
`virtio_pci.f`	VirtIO block PCI driver	persistent
`manager.f`	64-slot process registry, hot-swap/restart, owned-image lifecycle	restart + exact release proven
`manager_hw.f`	Capability-checked block/net/display/input/USB/NVMe broker	runtime + no-bypass proven
`shell.f`	Interactive shell (30 commands)	text + length-framed binary transfer runtime-proven
`fcc.f`	In-kernel Foundation compiler	independent concurrent images proven
`capability.f` / `security.f`	Exact rights, delegation/revoke/lifecycle, TFS/initrd/Manager/device policy	QEMU enforcement proven
`namespace.f`	Per-process bindings, longest-boundary-prefix resolution, clone/remove/transfer lifecycle	runtime enforced
`vfs.f`	Guarded namespace traversal plus filtered/synthesized direct-child snapshots	paths + listing overlays proven
`virtio_net.f`	VirtIO network card driver	working
`net_ip.f`	ARP + IPv4 + network polling	working
`net_tcp.f`	TCP state machine	working
`net_shell.f`	Remote shell over TCP :7777	proven
`http.f`	HTTP server on port 8080	working
`fb.f` / `fb_font.f`	Framebuffer and bitmap font	working
`gui*.f`	Bounded full-scene compositor, widgets, system monitor	stacking + allocation unwind QEMU-proven
`tui*.f`	Text UI framework and system monitor	live state + refresh/quit QEMU-proven
`mouse.f`	PS/2 mouse driver	working
`vmm.f`	Page table manipulation for MMIO	working
`xhci.f`	USB 3.0 host controller	Manager scan proven; descriptors/HID pending
`nvme.f`	NVMe controller driver	Manager read + disposable write/restore proven

Boot Sequence

Power On → BIOS/UEFI → Limine bootloader → start.s → kmain()
  → serial → GDT → PMM → heap → IDT → interrupts → timer
  → TSS → scheduler → Manager/capability/namespace self-tests
  → TFS/initrd + Manager/device policy installation
  → initrd → Manager hardware registration → TFS integrity/fault proof
  → network/devices/display → 64 KiB-stack timer preemption → serial shell
  → net shell + HTTP only when TCP initialized

Shell Commands

The serial shell is always available. When VirtIO-net initializes, Terminus also starts a TCP shell on port 7777 and an HTTP server on port 8080, forwarded by QEMU to host port 8889.

terminus> help
  ls, cat, write, append, replace, rm, mkdir
  exec, spawn, calc, run
	  recv, send; recvbin <file> <decimal 0..4096>, sendbin <file>
	  guioom <1..9|site> (serial-only allocation-unwind proof)
	  deploy, drain, kernels, restart, ps, mem, status, uptime
  nvmetest DISPOSABLE (QEMU proof fixture only; temporary LBA 127 overwrite)
  clear, halt

cd kernel && make test-shell-runtime boots a fresh headless, no-network ISO and emits 12 exact PASS lines; the final target passed three independent fresh boots (36/36 markers) plus one post-forced-build 12/12 run. The original eleven JIT, initrd, text/binary transfer, literal/overlap, managed-return, sysmon, and warmed-memory checks remain. The twelfth fixture keeps two gated FCC entries live on distinct PMM pages, restarts one at the same entry, executes an intervening compile, then releases them independently. The measured restart returns the old 16-page scheduler stack and one heap context (PMM +16, live allocations -1, live bytes lower), followed by one PMM page for each image exit. Its exact marker is PASS independent FCC images survived concurrent spawn, intervening compile, restart, and exact lifecycle release.

Each FCC result owns one page: 4080 bytes hold upward-growing instructions and downward-growing literals, while a trusted 16-byte trailer records magic and exact entry. Synchronous callers release after return; serial spawn hands ownership to the Manager's scheduler-aligned 64-slot map. Restart transfers the release callback transactionally and final exit clears the row before checked release. Those ownership APIs are trusted and absent from the FCC symbol table. The first concurrency boot historically caught 48 83 EC 80 sign-extending its frame and moving RSP into the adjacent image; the imm32 form 48 81 EC 80 00 00 00 passed after a forced rebuild. Pages remain RWX ring-0 memory without W^X; trailer validation is not isolation; the cap is 4080 bytes; release assumes PMM physical base zero; signed disp8 locals allow 16 safe u64 locals versus 32 declared; and more than 64 break statements in one loop can overrun the fixed patch table. A future TCP CAP_EXEC path needs external-termination cleanup for a transient synchronous image. Existing serial-protocol and physical-input limits remain.

make test-gui-mouse builds the real ISO and boots fresh no-NIC BIOS x86_64 QEMU, observed at 1280x800, with Unix serial, VNC, QMP-injected PS/2 input, and framebuffer dumps. Each no-retry boot launches the GUI twice. Ten exact PASS markers prove IRQ12 movement; exact exposed-desktop restoration under a moved cursor; 36 no-retry focus cycles plus overlap clicks with attributed, pixel-exact stacking; title-bar close repaint and compact-state reopen; exact Refresh state selected=2 cursor=3 text=abXcd; UART Tab moving focus to Quit; text-field cursor placement/insertion; list highlighting from row 0 to row 2; two Quit returns; and warmed-memory restoration. It passed 10/10 in three independent real-QEMU boots with no retries (30/30 markers). Each launch also requires exactly one [gui] compositor self-test PASS compact-z focus-hit-close-reopen marker. Internally, the compositor keeps contiguous ranks in a bounded eight-window z order and rebuilds the full scene bottom-to-top when cursor, focus, close, or reopen changes invalidate it. The serial-only guioom matrix injects a tagged null at each of nine stable GUI/TUI/widget/application allocation sites; exact request/fire/PASS and expected component-error attribution, shell return without event-loop entry, and equality with the warmed PMM free-page plus heap live-allocation/byte baseline are required after every site. Wrong or unconsumed tags, extra errors, and event-loop false positives fail the proof. The added marker is exactly PASS all 9 tagged GUI allocation failures unwound to the warm memory baseline. This is deterministic injection in the current single GUI call chain, not physical exhaustion or a proof about future concurrent GUI callers. The proof covers short text and four visible unscrolled rows, not UEFI, physical hardware, long-text clipping, or list scrolling; it has no dedicated black-box trigger that dirties only a fully hidden lower window while the clean upper window remains in place.

make test-manager passed 11/11 after the Manager map was aligned to the scheduler's 64 slots. It boots disposable VirtIO and NVMe images, proves the NVMe confirmation gate plus write/read/restore and whole-image equality, exercises xHCI broker operations, deploys v99, restarts HTTP and the TCP shell from draining v2, and requires real protocol responses plus zero broker errors. Its network proof correlates a fresh SYN and ESTABLISHED on one child socket, preserves a request across a partial application read, returns multi-segment HTTP after peer half-close, and requires stable PMM/live-heap state. make test-manager-static rejects active direct driver calls; make test-network-static checks guarded IP/TCP nesting and fail-closed VirtIO queue invariants.

HTTP and the TCP shell share one token-guarded IP/TCP/VirtIO stack. TCP uses a checked fixed buffer pool and bounded handshake/close states; VirtIO validates RX/TX completions and resets on malformed queue state or timeout. This remains a plaintext QEMU development stack without retransmission timers, congestion control, DHCP, DNS, TLS, or user authentication.

make test-security first runs a static guard against raw TFS path calls outside trusted layers; its QEMU harness then emits 11 PASS markers. The runtime proof covers capability semantics, isolated initrd/device denials, five targeted TFS fault injections, and live namespace enforcement. With TFS-directory LOOKUP|READ and wildcard TFS-file READ, the TCP shell's request-attributed ls must return exactly exec.f (9 bytes) and one synthesized visible alias (8 bytes) before and after restart; physical guard.txt and the shadowed 5-byte visible decoy remain absent. Repeated listings preserve PMM/live-heap state. make test-tfs-persistence separately proves file bytes and deletion across three boots. make test-precedence scans all 52 top-level kernel Foundation files, including the excluded unlinked scratch file; that count is scan scope, while the shipped kernel has 51 unique linked build inputs.

VFS snapshots retain only physical children whose visible spelling resolves back to that child, overlay effective direct-child bindings, synthesize existing metadata-readable aliases, and deduplicate visible names with bindings shadowing physical entries. The TCP namespace is still a demonstration rooted at /, not a least-privilege allowlist. Namespace traversal covers TFS, not initrd; deeper bindings do not implicitly create absent ancestor entries; complete VFS paths are limited to 511 bytes. Current processes still execute in ring 0 and share the kernel address space; ring 3, per-process address spaces, and complete syscall isolation remain pending.

For AI Agents

Concise LLM view: llms.txt

Technical architecture: concept.md