Kernel visual atlas

From the privilege gate to a signed causal epoch: 31 views of the historical x86-32 kernel.

These figures preserve the source snapshot documented below. SlOS now targets native x86-64 and AArch64 with ELF64/LP64 user programs and default native SMP; see current platform qualification. Historical address layouts, ELF32 gates and cooperative AP offload are not native implementation diagrams.

Diagram index
Scope, source baseline and visual key

x86-32 kernel and local Hew consumer; architectural snapshot, not a performance measurement. Source references are private-checkout study paths, not public source links. Kernel a3d7653ade20b8de9529e446201d2fda32ae2a1c; the local Hew runtime comparison uses consumer c1c901f8c9c26fc2e4f864e6b799f9a834f8fa41.

Blue denotes user execution; rust denotes a boundary or rejection; ochre denotes persistent storage; olive denotes causal evidence. Uncolored nodes are ordinary kernel mechanisms. Labels carry the same meaning without color. Arrows name data movement, control transitions or causes; dashed vertical lines in sequence diagrams are participant lifelines.

Flows omit error cases only where stated. Region and block layouts are schematic, not measured area. Lamport values are illustrative. At this snapshot, user execution stays on the BSP and AP offload is opt-in and kernel-task-only. Hew's cooperative process runtime is separate from SlOS kernel actors.

Subsystem chapters · Concept trails · Operating manual · Local Hew runtime

Machine and privilege

Kernel structure

Full-size SVG

Ring 3 · private address spaces

  • User shell / C programs
  • Local Hew executables Restricted freestanding runtime
INT 0x80 Syscall dispatch + user-buffer checks

Ring 0 · shared kernel trust domain

  • Tasks + paging
  • Streams + files + TCP
  • Kernel actors + mesh

↓ task, I/O and message events

Causal DAG

↓ bounded archival

SlFS + causal journal

↓ device operations + sector I/O

PIC / PIT · PCI · VirtIO block + network

Private user processes enter a shared kernel; instrumented operations feed the causal record.

Text equivalent and source references
  • Ring 3 contains separate user processes, including local Hew programs. INT 0x80 crosses into ring 0.
  • Tasks, I/O and kernel actors share kernel privilege. Task, I/O and message events enter the causal DAG; archival writes use SlFS and block I/O.

Layered architecture. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/main.c · kernel_main
  • kernel/core/syscall.c · syscall_handler
  • kernel/graph/causal.c · causal_emit

Download SVG · Editable DOT

Boot to the first runnable shell

Full-size SVG
Boot to the first runnable shell Multiboot entry reaches kernel_main, then descriptor tables, interrupts, memory, graph state, tasking and filesystems initialize in dependency order. SlFS restore is conditional on block-device availability. Network and graph services initialize before SMP discovery and the idle/shell task handoff. cluster_machine 1 · Machine initialization cluster_storage 2 · Storage and network cluster_handoff 3 · Services and handoff entry->core core->memory memory->causal causal->tasks tasks->fs fs->next_storage disk->restore yes disk->timer no · diskless restore->timer timer->next_services services->smp smp->run run->yield entry Multiboot loader arch/x86/boot.asm core kernel_main: console → GDT → IDT → PIC memory PMM → paging → heap causal Causal ring → replay → timelines tasks PCI → TSS → keyboard → syscalls → tasking fs RAM filesystem next_storage Continue at 2 disk Block device available? restore Mount SlFS restore snapshot timer 100 Hz timer → network stack next_services Continue at 3 services Actors → identity → mesh → federation → graph services smp Configured x86 SMP: discovery / AP startup run Create idle + shell start remote services yield Boot yields → scheduler → shell
Boot to the first runnable shell Multiboot entry reaches kernel_main, then descriptor tables, interrupts, memory, graph state, tasking and filesystems initialize in dependency order. SlFS restore is conditional on block-device availability. Network and graph services initialize before SMP discovery and the idle/shell task handoff. entry->core core->memory memory->causal causal->tasks tasks->fs fs->disk disk->restore yes disk->timer no · diskless restore->timer timer->services services->smp smp->run run->yield entry Multiboot loader arch/x86/boot.asm core kernel_main: console → GDT → IDT → PIC memory PMM → paging → heap causal Causal ring → replay → timelines tasks PCI → TSS → keyboard → syscalls → tasking fs RAM filesystem disk Block device available? restore Mount SlFS → restore snapshot timer 100 Hz timer → network services Actors → identity → mesh → federation → graph services smp Configured x86 SMP discovery / AP startup run Create idle + shell start remote services yield Boot yields → scheduler → shell

The x86 boot path establishes memory and tasking before publishing system tasks.

Text equivalent and source references
  • Multiboot entry reaches kernel_main, then descriptor tables, interrupts, memory, graph state, tasking and filesystems initialize in dependency order.
  • SlFS restore is conditional on block-device availability. Network and graph services initialize before SMP discovery and the idle/shell task handoff.

Initialization flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • arch/x86/boot.asm · _start
  • kernel/core/main.c · kernel_main

Download SVG · Editable DOT

Two gates for a user buffer

Full-size SVG
Two gates for a user buffer A syscall buffer must pass the non-null, overflow and user-range checks, then the current task page-table permission walk. A failed check returns an error. Direct ring-3 access to supervisor-only or unmapped pages faults in hardware independently of those software checks. call->range range->walk yes range->reject no walk->use yes walk->reject no call Ring-3 syscall with address + length range Non-null, no wrap, inside user virtual range? walk Current page tables: present + user + writable if needed? use Kernel follows validated buffer reject Return syscall error hardware Direct ring-3 access to supervisor or unmapped pages → CPU page fault
Two gates for a user buffer A syscall buffer must pass the non-null, overflow and user-range checks, then the current task page-table permission walk. A failed check returns an error. Direct ring-3 access to supervisor-only or unmapped pages faults in hardware independently of those software checks. call->range range->walk yes range->reject no walk->use yes walk->reject no call Ring-3 syscall with address + length range Non-null, no wrap, inside user virtual range? walk Current page tables: present + user + writable if needed? use Kernel follows validated buffer reject Return syscall error hardware Direct ring-3 access to supervisor or unmapped pages → CPU page fault

Software buffer validation complements, rather than replaces, hardware page isolation.

Text equivalent and source references
  • A syscall buffer must pass the non-null, overflow and user-range checks, then the current task page-table permission walk.
  • A failed check returns an error. Direct ring-3 access to supervisor-only or unmapped pages faults in hardware independently of those software checks.

Decision flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/memory.h · is_user_ptr
  • kernel/core/memory.c · vmm_user_range_ok
  • kernel/core/syscall.c · syscall_handler

Download SVG · Editable DOT

Interrupts are not one path

Full-size SVG
Interrupts are not one path CPU exceptions use isr_handler; PIC IRQs are remapped to vectors 32–47; the ring-3 syscall entry uses INT 0x80. irq_handler acknowledges the controller before calling a device handler. The BSP timer increments ticks, wakes sleepers and schedules when the quantum expires; AP entries skip shared tick work. source->exception source->irq source->syscall exception->fault irq->eoi syscall->dispatch eoi->handler handler->tick IRQ0 source x86 interrupt / exception exception CPU exception vectors 0…31 irq PIC IRQ vectors 32…47 syscall INT 0x80 user-callable gate fault isr_handler fault policy / diagnostics eoi irq_handler send EOI before invoking handler handler Registered device handler tick Timer on BSP increment ticks → wake sleepers quantum exhausted → schedule dispatch syscall_handler validate + dispatch note Early EOI prevents a context switch from leaving the PIC in service. AP timer entry returns before shared BSP tick work.
Interrupts are not one path CPU exceptions use isr_handler; PIC IRQs are remapped to vectors 32–47; the ring-3 syscall entry uses INT 0x80. irq_handler acknowledges the controller before calling a device handler. The BSP timer increments ticks, wakes sleepers and schedules when the quantum expires; AP entries skip shared tick work. Early EOI prevents a switch from leaving the PIC in service. AP timer entry returns before shared BSP tick work. source->exception source:e->irq:e source:e->syscall:e irq->eoi eoi->handler handler->tick syscall->dispatch source x86 interrupt / exception exception CPU exceptions · 0…31 isr_handler fault policy / diagnostics irq PIC IRQ · 32…47 eoi irq_handler: send EOI before device handler handler Registered device handler tick IRQ0 on BSP increment ticks → wake sleepers quantum exhausted → schedule syscall INT 0x80 user-callable gate dispatch syscall_handler validate + dispatch

Exceptions, device IRQs and user syscalls share entry machinery but have different dispatch rules.

Text equivalent and source references
  • CPU exceptions use isr_handler; PIC IRQs are remapped to vectors 32–47; the ring-3 syscall entry uses INT 0x80.
  • irq_handler acknowledges the controller before calling a device handler. The BSP timer increments ticks, wakes sleepers and schedules when the quantum expires; AP entries skip shared tick work.

Dispatch tree. Source paths refer to the atlas baseline; the kernel checkout is private.

  • arch/x86/interrupt.asm · ISR / IRQ stubs
  • kernel/core/interrupt.c · irq_handler, timer_handler
  • kernel/core/x86.c · idt_init

Download SVG · Editable DOT

What each trust boundary establishes

Full-size SVG
What each trust boundary establishes User mappings and the syscall gate separate user processes from kernel privilege. Kernel components themselves share ring 0. Mesh encryption authenticates channel traffic under exchanged keys. A self-derived SPIFFE-shaped identity and advertised signing key are not external workload certification. Signed roots establish cryptographic consistency with a selected key, not the truth of peer claims. Capability checks only enforce operations at actual check sites. user->syscall syscall->kernel kernel->channel message traffic channel->peer message traffic peer->root root->scope user Ring-3 process private user mappings syscall Hardware privilege gate page walk + scoped operation checks kernel Shared ring-0 kernel actors / drivers / filesystem / graph channel Inter-machine encrypted mesh key exchange + authenticated ciphertext peer Peer node self-derived spiffe://slos.local identity root Advertised signing key + signed epoch root scope Verify cryptographic consistency within selected local trust context note No external CA / workload attestation is implied by a SPIFFE-shaped URI. Kernel components share privilege; encryption does not make peer claims true. Capability checks apply where invoked, not a universal isolation guarantee.
What each trust boundary establishes User mappings and the syscall gate separate user processes from kernel privilege. Kernel components themselves share ring 0. Mesh encryption authenticates channel traffic under exchanged keys. A self-derived SPIFFE-shaped identity and advertised signing key are not external workload certification. Signed roots establish cryptographic consistency with a selected key, not the truth of peer claims. Capability checks only enforce operations at actual check sites. user->syscall syscall->kernel kernel->channel message traffic channel->peer message traffic peer->root root->scope user Ring-3 process private user mappings syscall Hardware privilege gate page walk + scoped operation checks kernel Shared ring-0 kernel actors / drivers / filesystem / graph channel Inter-machine encrypted mesh key exchange + authenticated ciphertext peer Peer node self-derived spiffe://slos.local identity root Advertised signing key + signed epoch root scope Verify cryptographic consistency within selected local trust context note No external CA / workload attestation is implied by a SPIFFE-shaped URI. Kernel components share privilege; encryption does not make peer claims true. Capability checks apply where invoked, not a universal isolation guarantee.

Page isolation, encrypted transport and signed evidence establish different, limited claims.

Text equivalent and source references
  • User mappings and the syscall gate separate user processes from kernel privilege. Kernel components themselves share ring 0.
  • Mesh encryption authenticates channel traffic under exchanged keys. A self-derived SPIFFE-shaped identity and advertised signing key are not external workload certification.
  • Signed roots establish cryptographic consistency with a selected key, not the truth of peer claims. Capability checks only enforce operations at actual check sites.

Trust-flow map. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/memory.h · user pointer validation
  • include/cap.h · cap_require
  • kernel/graph/mesh.c · compute_spiffe_id, handle_handshake
  • kernel/graph/federation.c · signing-key / epoch-root handling

Download SVG · Editable DOT

Back to diagram index

Memory

Physical frame ownership

Full-size SVG
Physical frame ownership PMM determines available frames from Multiboot information, marks usable regions free and reserves occupied kernel, bitmap and heap frames. Allocation finds a free bit, marks it used and returns a 4 KiB frame; freeing clears ownership and makes the frame reusable. Exhaustion returns failure. map->bitmap bitmap->reserve reserve->cursor cursor->found found->alloc yes found->fail no alloc->free owner releases free->cursor frame reusable map Multiboot available-memory map bitmap PMM bitmap 1 bit per 4 KiB frame reserve Reserve kernel + bitmap + heap frames cursor Allocation: scan from next-free cursor found Free bit found? alloc Set bit → increment used count return physical frame fail Return allocation failure free Free frame: clear bit adjust used count + scan cursor
Physical frame ownership PMM determines available frames from Multiboot information, marks usable regions free and reserves occupied kernel, bitmap and heap frames. Allocation finds a free bit, marks it used and returns a 4 KiB frame; freeing clears ownership and makes the frame reusable. Exhaustion returns failure. map->bitmap bitmap->reserve reserve->cursor cursor->found found->alloc yes found:e->fail:e no alloc->free free:e->cursor:e frame reusable map Multiboot available-memory map bitmap Bitmap ownership 1 bit per 4 KiB frame reserve Reserve kernel, bitmap and heap frames cursor Scan from next-free cursor found Free bit found? alloc Set bit; increment used count return physical frame free Owner frees frame: clear bit; adjust count + cursor fail Return allocation failure

The bitmap tracks ownership; the next-free cursor is only a search hint.

Text equivalent and source references
  • PMM determines available frames from Multiboot information, marks usable regions free and reserves occupied kernel, bitmap and heap frames.
  • Allocation finds a free bit, marks it used and returns a 4 KiB frame; freeing clears ownership and makes the frame reusable. Exhaustion returns failure.

Allocation flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/memory.c · pmm_init, pmm_alloc_frame, pmm_free_frame, heap_init
  • include/memory.h · PAGE_SIZE

Download SVG · Editable DOT

Same virtual regions, different ownership

Full-size SVG

Task A · page directory A

Private user stack
User + writable
Private heap / ELF
User pages
Low 128 MiB identity map
Supervisor only

Task B · page directory B

Private user stack
Different frames
Private heap / ELF
Different frames
Low 128 MiB identity map
Same kernel frames

Scheduler: change CR3 when page directories differ. Shared virtual regions do not imply shared user frames.

Each user task has private user frames and the same supervisor-only kernel identity map.

Text equivalent and source references
  • Task A and task B have different page directories and private ELF, stack and heap frames.
  • Both directories retain the low 128 MiB supervisor-only identity map. A context switch loads CR3 only when the selected directories differ. Rows show regions, not address-scale measurements.

Aligned comparison. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/memory.c · vmm_init, vmm_create_user_dir
  • kernel/core/task.c · task_create_user, schedule

Download SVG · Editable DOT

A 32-bit virtual address becomes a physical byte

Full-size SVG
31…22directory10 bits
21…12table10 bits
11…0offset12 bits
  1. CR3 → page directory1024 entries · bits 31…22 select PDE
  2. PDE → page table1024 entries · bits 21…12 select PTE
  3. PTE → physical frame4 KiB · frame base + permission flags
  4. Frame base + offset → physical byteBits 11…0 remain unchanged

The 10 / 10 / 12 split selects a directory entry, a table entry and a byte within a 4 KiB frame.

Text equivalent and source references
  • Bits 31–22 index one of 1024 page-directory entries; bits 21–12 index one of 1024 page-table entries.
  • The selected PTE identifies a frame and permissions. Its frame base combines with the unchanged low 12 bits to form the physical byte address. This is the x86-32 path.

Bit-field and dataflow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/memory.h · PAGE_DIR_ENTRIES, PAGE_TABLE_ENTRIES, PAGE_FRAME_MASK
  • kernel/core/memory.c · vmm_map_page, vmm_user_range_ok

Download SVG · Editable DOT

Split and coalesce without moving allocations

Full-size SVG
  1. Before allocationAddress order →
    Allocated AFree BAllocated C
  2. kmallocFirst fit · align + guards · split if useful
    ANew allocationB remainderC
  3. kfreeValidate guards · merge adjacent free blocks
    ACoalesced BC

Schematic sizes · no live allocation moves. Interrupt-atomic mutation; SMP adds heap locking.

First fit consumes a suitable free block; freeing merges adjacent free neighbors.

Text equivalent and source references
  • kmalloc aligns the request, includes guard space and scans for the first suitable block. A useful remainder stays free.
  • kfree validates the block and guards, then coalesces adjacent free neighbors without relocating live allocations. Block widths are schematic, not measured sizes.

Before / during / after. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/memory.c · heap_init, kmalloc, kfree, heap_merge_next

Download SVG · Editable DOT

Back to diagram index

Execution

Priority queues and the optional AP lane

Full-size SVG
Priority queues and the optional AP lane The BSP chooses among eight priority queues, with starvation and causal-activity adjustments. Runnable tasks return to ready queues after yield or preemption. Only READY, non-user, explicitly offloadable kernel tasks are candidates for the configured SMP offload lane. This does not migrate user tasks to APs. queues->select select->bsp select->eligible SMP + offload enabled bsp->queues yield / quantum expires eligible->ap eligible task + idle AP queues Shared ready queues priority 0 · highest eligible task → next priorities 1…6 per-priority linked lists priority 7 · idle idle / lowest priority select BSP selection priority + periodic starvation boost + periodic causal-activity boost bsp CPU 0 · BSP user tasks + ordinary kernel tasks eligible Opt-in offload eligibility READY + kernel-only + ap_offloadable ap Idle AP · cooperative kernel-task lane no user-task migration
Priority queues and the optional AP lane The BSP chooses among eight priority queues, with starvation and causal-activity adjustments. Runnable tasks return to ready queues after yield or preemption. Only READY, non-user, explicitly offloadable kernel tasks are candidates for the configured SMP offload lane. This does not migrate user tasks to APs. queues->select select->eligible SMP + offload enabled select:e->bsp:e default eligible->ap eligible + idle AP bsp:w->queues yield / quantum expires queues Shared ready queues 0: highest; 7: idle 1…6: per-priority lists select BSP selection priority + starvation boost + causal-activity boost eligible Opt-in SMP offload: READY + kernel-only + ap_offloadable ap Idle AP cooperative lane no user-task migration bsp CPU 0 · BSP user + ordinary kernel tasks

Default user execution stays on the BSP; opt-in AP offload is restricted to eligible kernel tasks.

Text equivalent and source references
  • The BSP chooses among eight priority queues, with starvation and causal-activity adjustments. Runnable tasks return to ready queues after yield or preemption.
  • Only READY, non-user, explicitly offloadable kernel tasks are candidates for the configured SMP offload lane. This does not migrate user tasks to APs.

Queue / routing map. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/task.c · schedule, maybe_offload_to_idle_aps, ready_counts_offloadable
  • include/task.h · task_set_ap_offloadable
  • docs/SHOWCASE.md · SMP limits

Download SVG · Editable DOT

What changes during an x86 context switch

Full-size SVG
What changes during an x86 context switch The scheduler selects next, updates its state, quantum and the ring-0 TSS stack, then changes page directories if needed. Assembly saves flags and callee-saved registers on the outgoing stack, stores its ESP, loads the incoming ESP, restores registers and returns on that stack. The incoming path releases the scheduler guard. cluster_selection 1 · Select task cluster_address 2 · Address space cluster_stack 3 · Stack exchange and return choose->state state->tss tss->next_address cr3->switchdir yes cr3->next_stack no switchdir->next_stack save->exchange exchange->restore restore->unlock choose schedule(): choose next hold scheduler guard state next → RUNNING set current + quantum tss Update TSS ring-0 stack next_address Continue at 2 cr3 Page directories differ? switchdir Load next CR3 next_stack Continue at 3 save context_switch: push flags, EBP, EBX, ESI, EDI exchange Save ESP → prev->esp load ESP ← next->esp restore Pop EDI, ESI, EBX, EBP, flags; ret on incoming stack unlock Incoming task releases guard restores own interrupt state
What changes during an x86 context switch The scheduler selects next, updates its state, quantum and the ring-0 TSS stack, then changes page directories if needed. Assembly saves flags and callee-saved registers on the outgoing stack, stores its ESP, loads the incoming ESP, restores registers and returns on that stack. The incoming path releases the scheduler guard. choose->state state->tss tss->cr3 cr3->switchdir yes cr3->save no switchdir->save save->exchange exchange->restore restore->unlock choose schedule(): choose next hold scheduler guard state next → RUNNING set current + quantum tss Update TSS ring-0 stack cr3 Page directories differ? switchdir Load next CR3 save Push flags; EBP, EBX, ESI, EDI onto old stack exchange Save old ESP → prev->esp load ESP ← next->esp restore Pop EDI, ESI, EBX, EBP, flags; ret on new stack unlock Incoming task releases guard restores own interrupt state

Task metadata, TSS and CR3 change before the assembly stack exchange.

Text equivalent and source references
  • The scheduler selects next, updates its state, quantum and the ring-0 TSS stack, then changes page directories if needed.
  • Assembly saves flags and callee-saved registers on the outgoing stack, stores its ESP, loads the incoming ESP, restores registers and returns on that stack. The incoming path releases the scheduler guard.

Low-level control flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/task.c · schedule
  • arch/x86/context.asm · context_switch

Download SVG · Editable DOT

Task state and resource lifetime

Full-size SVG
Task state and resource lifetime READY dispatches to RUNNING; yield or preemption returns it to READY. Sleep, wait and I/O can block; a wake source makes it ready again. Stop signals produce STOPPED and SIGCONT restores readiness. Exit produces a waitable ZOMBIE when there is a live parent, otherwise DEAD; wait or orphan cleanup makes zombies dead. Reaping frees resources and the slot. ready->running dispatch ready->stopped SIGSTOP / SIGTSTP running->ready yield / preempt running->blocked sleep / wait / I/O running->stopped stop signal running->zombie exit; live parent can wait running->dead exit without waitable parent blocked->ready deadline / wake source stopped->ready SIGCONT zombie->dead parent wait() / orphan cleanup dead->reaped ready READY running RUNNING blocked BLOCKED stopped STOPPED zombie ZOMBIE dead DEAD reaped Reap resources → reusable slot
Task state and resource lifetime READY dispatches to RUNNING; yield or preemption returns it to READY. Sleep, wait and I/O can block; a wake source makes it ready again. Stop signals produce STOPPED and SIGCONT restores readiness. Exit produces a waitable ZOMBIE when there is a live parent, otherwise DEAD; wait or orphan cleanup makes zombies dead. Reaping frees resources and the slot. ready->running dispatch ready->stopped SIGSTOP / SIGTSTP running->ready yield / preempt running->blocked sleep / wait / I/O running->stopped stop signal running->zombie exit; live parent can wait running->dead exit without waitable parent blocked->ready deadline / wake source stopped->ready SIGCONT zombie->dead parent wait() / orphan cleanup dead->reaped ready READY running RUNNING blocked BLOCKED stopped STOPPED zombie ZOMBIE dead DEAD reaped Reap resources → reusable slot

Exiting is not the same as reclaiming: waitable children remain zombies until collected.

Text equivalent and source references
  • READY dispatches to RUNNING; yield or preemption returns it to READY. Sleep, wait and I/O can block; a wake source makes it ready again.
  • Stop signals produce STOPPED and SIGCONT restores readiness. Exit produces a waitable ZOMBIE when there is a live parent, otherwise DEAD; wait or orphan cleanup makes zombies dead. Reaping frees resources and the slot.

State machine. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/task.h · task_state_t
  • kernel/core/task.c · task_finish, task_wait, task_reap, task_kill

Download SVG · Editable DOT

One syscall round trip

Full-size SVG
One syscall round trip The user executes INT 0x80. The x86 entry stub saves registers and calls the kernel syscall handler. The handler validates buffers and dispatches the selected operation, writes the result into EAX and returns through the stub. IRET resumes ring-3 code; blocking operations may schedule other tasks before returning. u->u1 g->g1 k->k1 u1->u2 u1->g1 1  INT 0x80 u2->u3 u3->u4 u4->u5 g1->g2 g2->g3 g2->k2 2  saved registers g3->g4 g4->g5 g5->u5 5  IRET · ring 3 k1->k2 k2->k3 3  validate buffers; run selected operation k3->k4 k4->g4 4  result in EAX k4->k5 u User program g x86 gate / stub k Kernel handler u1 u2 u3 u4 u5 g1 g2 g3 g4 g5 k1 k2 k3 k4 k5
One syscall round trip The user executes INT 0x80. The x86 entry stub saves registers and calls the kernel syscall handler. The handler validates buffers and dispatches the selected operation, writes the result into EAX and returns through the stub. IRET resumes ring-3 code; blocking operations may schedule other tasks before returning. u->u1 g->g1 k->k1 u1->u2 u1->g1 1 INT 0x80 u2->u3 u3->u4 u4->u5 g1->g2 g2->g3 g2->k2 2 saved registers g3->g4 g4->g5 g5->u5 5 IRET · ring 3 k1->k2 k2->k3 3 validate buffers; run selected operation k3->k4 k4->g4 4 result in EAX k4->k5 u User program g x86 gate / stub k Kernel handler u1 u2 u3 u4 u5 g1 g2 g3 g4 g5 k1 k2 k3 k4 k5

Time runs downward; the saved register frame carries arguments and the result across the gate.

Text equivalent and source references
  • The user executes INT 0x80. The x86 entry stub saves registers and calls the kernel syscall handler.
  • The handler validates buffers and dispatches the selected operation, writes the result into EAX and returns through the stub. IRET resumes ring-3 code; blocking operations may schedule other tasks before returning.

Sequence diagram. Source paths refer to the atlas baseline; the kernel checkout is private.

  • arch/x86/interrupt.asm · isr128, isr_common_stub
  • kernel/core/syscall.c · syscall_handler
  • include/syscall.h · syscall ABI

Download SVG · Editable DOT

Publish a user task only after loading succeeds

Full-size SVG
Publish a user task only after loading succeeds Resolve and validate static ELF32 bytes, create a blocked user task, then allocate private PT_LOAD pages, copy file contents and zero the remaining segment memory. Set up argc/argv and validated launch I/O before making the task ready. The user trampoline enters ring 3; failed loading rolls back owned pages and the partial task. resolve->validate validate->child child->map map->args map->cleanup invalid range / allocation fails args->stdio stdio->ready stdio->cleanup assignment fails ready->enter resolve Resolve registered / installed ELF read static ELF32 bytes validate Validate ELF header + segment bounds child Create user task as BLOCKED private directory + stack pages map For each PT_LOAD: allocate user frames → copy file bytes zero remaining memory args Build argc / argv on user stack stdio Validate / assign launch I/O handles ready Publish task READY enter Scheduler → user trampoline IRET to entry point in ring 3 cleanup Load failure: roll back pages finish partial task
Publish a user task only after loading succeeds Resolve and validate static ELF32 bytes, create a blocked user task, then allocate private PT_LOAD pages, copy file contents and zero the remaining segment memory. Set up argc/argv and validated launch I/O before making the task ready. The user trampoline enters ring 3; failed loading rolls back owned pages and the partial task. resolve->validate validate->child child->map map->args map->cleanup invalid range / allocation fails args->stdio stdio->ready stdio->cleanup assignment fails ready->enter resolve Resolve registered / installed ELF read static ELF32 bytes validate Validate ELF header + segment bounds child Create user task as BLOCKED private directory + stack pages map For each PT_LOAD: allocate user frames → copy file bytes zero remaining memory args Build argc / argv on user stack stdio Validate / assign launch I/O handles ready Publish task READY enter Scheduler → user trampoline IRET to entry point in ring 3 cleanup Load failure: roll back pages finish partial task

A new user task starts blocked while its private image, arguments and I/O are prepared.

Text equivalent and source references
  • Resolve and validate static ELF32 bytes, create a blocked user task, then allocate private PT_LOAD pages, copy file contents and zero the remaining segment memory.
  • Set up argc/argv and validated launch I/O before making the task ready. The user trampoline enters ring 3; failed loading rolls back owned pages and the partial task.

Launch / failure flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/elf.c · elf_load_args_io, elf_setup_args
  • kernel/core/task.c · task_create_user, task_entry_trampoline_user, task_rollback_user_pages

Download SVG · Editable DOT

Back to diagram index

Streams and process I/O

Readiness is a property of the stream now

Full-size SVG
Writers
4096-byte ringhead + byte count
Readers
Level-triggered readiness from current stream state
EndpointConditionResult
ReadBytes presentREAD
ReadNo writersREAD + HUP; drain then EOF
WriteReaders + free spaceWRITE
WriteNo readersHUP + ERROR; broken pipe
EitherEmpty / full, peer still presentOperation may WOULD_BLOCK

EOF and broken pipe derive from endpoint reference counts, not a special byte in the stream.

Text equivalent and source references
  • A read endpoint is ready when bytes exist or no writers remain. After buffered bytes drain, no writers means EOF; readiness also reports HUP.
  • A write endpoint is ready when readers exist and the 4096-byte ring has space. No readers yields HUP plus ERROR and writes report broken pipe. Empty/full streams with a peer present may return WOULD_BLOCK.

State / result matrix. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/user_io.c · stream_t, readiness, user_io_read, user_io_write

Download SVG · Editable DOT

Register, scan and block without losing a wakeup

Full-size SVG
Register, scan and block without losing a wakeup Acquire scheduler guard then stream lock, register wait items and scan current stream, timer, child and TCP levels. Ready items, poll mode or deadline expiry return a count; a relevant signal interrupts. Otherwise mark blocked under the guard, release before scheduling, then reacquire and rescan after a publisher wakes the task. Local console input is deliberately excluded from nonblocking readiness. register->scan scan->ready ready->signal no ready->result yes signal->block no signal->interrupted yes block->publish stream / TCP / tick / child event publish->wake wake->scan resume + reacquire register Acquire scheduler guard → stream lock register items + deadline scan Scan stream / timer / child / TCP levels ready Ready / poll / deadline reached? signal Unmasked signal other than SIGCHLD? block Mark task BLOCKED under same guard release locks → schedule publish Publisher changes state scan waiters under matching guard wake Ready / expired → unblock task result Copy revents → clear registration release locks → return ready count interrupted Clear registration return INTERRUPTED
Register, scan and block without losing a wakeup Acquire scheduler guard then stream lock, register wait items and scan current stream, timer, child and TCP levels. Ready items, poll mode or deadline expiry return a count; a relevant signal interrupts. Otherwise mark blocked under the guard, release before scheduling, then reacquire and rescan after a publisher wakes the task. Local console input is deliberately excluded from nonblocking readiness. register->scan scan->ready ready->signal no ready:e->result:e yes signal->block no signal:e->interrupted:e yes block->publish stream / TCP / tick / child event publish->wake wake:e->scan:e resume + reacquire register Scheduler guard → stream lock register items + deadline scan Scan stream / timer / child / TCP ready Ready / poll / deadline? signal Unmasked signal other than SIGCHLD? block Mark BLOCKED under same guard release locks → schedule publish Publisher changes state scan waiters under matching guard wake Ready / expired → unblock result Copy revents; clear registration release locks; return ready count interrupted Clear registration return INTERRUPTED

Wait registration and the blocked transition use the same guard as publishers.

Text equivalent and source references
  • Acquire scheduler guard then stream lock, register wait items and scan current stream, timer, child and TCP levels.
  • Ready items, poll mode or deadline expiry return a count; a relevant signal interrupts. Otherwise mark blocked under the guard, release before scheduling, then reacquire and rescan after a publisher wakes the task. Local console input is deliberately excluded from nonblocking readiness.

Concurrency flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/user_io.c · io_acquire, user_wait_many, readiness, wake_waiters
  • kernel/net/tcp.c · tcp_user_ready

Download SVG · Editable DOT

Launch I/O references outlive individual handles

Full-size SVG
Launch I/O references outlive individual handles Creating a stream starts one reader and one writer reference. Assigning child stdio increments the selected endpoint references. Each close or task cleanup drops its own references. The last writer causes drain-then-EOF, the last reader causes broken pipe, and zero references on both sides clear the stream slot. cluster_launch 1 · Launch cluster_use 2 · Use and close cluster_final 3 · Final references create->assign assign->parent parent->next_use child->exit exit->next_refs peer->reuse create Parent creates stream read ref = 1 · write ref = 1 assign Assign child stdio: add endpoint references parent Parent closes unused ends its references drop next_use Continue at 2 child Child reads / writes via stdio shared reference accounting exit Child close / task exit: cleanup ordinary + stdio refs next_refs Continue at 3 peer Last writer → drain then EOF Last reader → broken pipe reuse Both counts zero: clear slot for reuse
Launch I/O references outlive individual handles Creating a stream starts one reader and one writer reference. Assigning child stdio increments the selected endpoint references. Each close or task cleanup drops its own references. The last writer causes drain-then-EOF, the last reader causes broken pipe, and zero references on both sides clear the stream slot. create->assign assign->parent parent->child child->exit exit->peer peer->reuse create Parent creates stream read ref = 1 · write ref = 1 assign Assign child stdio: add endpoint references parent Parent closes unused endpoints its references drop child Child reads / writes via stdio shared reference accounting exit Child close / task exit: cleanup ordinary + stdio refs peer Last writer → drain then EOF Last reader → broken pipe reuse Both counts zero: clear slot for reuse

Closing the parent copy does not close the child copy; exit cleanup releases both ordinary and stdio handles.

Text equivalent and source references
  • Creating a stream starts one reader and one writer reference. Assigning child stdio increments the selected endpoint references.
  • Each close or task cleanup drops its own references. The last writer causes drain-then-EOF, the last reader causes broken pipe, and zero references on both sides clear the stream slot.

Ownership lifecycle. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/core/user_io.c · user_stream_create, user_io_assign, drop, user_io_cleanup
  • kernel/core/task.c · task_finish

Download SVG · Editable DOT

Back to diagram index

Filesystem

Read overlay and persistent write routing

Full-size SVG
Read overlay and persistent write routing Read-open checks the RAM overlay before SlFS. Creates in /tmp route to RAM; ordinary writes and creates outside /tmp route to SlFS. Appending a visible RAM file to the persistent route preserves its prefix before promotion. A successful persistent write-open removes the RAM shadow; an unresolved backing file is an error, not a silent durable-to-RAM fallback. open->write write->ram no · read or /tmp write->block yes ram->ramopen yes / RAM create ram->block miss block->promote persistent write block->fail unresolved promote->remove open sys_open(normalized absolute path) write Write / create outside /tmp? ram RAM overlay node exists? ramopen Open RAM file /tmp creates route here block Resolve / create SlFS inode promote Append to visible RAM file? copy prefix before promotion remove Successful persistent write-open removes shadowing RAM file fail No backing file / creation fails return error note Reads are RAM-first, then SlFS. Ordinary persistent writes do not silently fall back to RAM.
Read overlay and persistent write routing Read-open checks the RAM overlay before SlFS. Creates in /tmp route to RAM; ordinary writes and creates outside /tmp route to SlFS. Appending a visible RAM file to the persistent route preserves its prefix before promotion. A successful persistent write-open removes the RAM shadow; an unresolved backing file is an error, not a silent durable-to-RAM fallback. Reads: RAM first, then SlFS. Persistent writes never silently fall back to RAM. open->write write->ram no write:e->block:e yes ram->ramopen yes / RAM create ram:e->block:e miss block->promote block:e->fail:e not found promote->remove open Open normalized absolute path write Write / create outside /tmp? ram RAM overlay node exists? ramopen Open RAM file /tmp creates route here block Resolve / create SlFS inode promote Persistent append to RAM file: preserve prefix before promotion remove Successful persistent write-open: remove shadowing RAM file fail Unresolved file / failed creation: return error

RAM-first reads and path-directed writes are different policies.

Text equivalent and source references
  • Read-open checks the RAM overlay before SlFS. Creates in /tmp route to RAM; ordinary writes and creates outside /tmp route to SlFS.
  • Appending a visible RAM file to the persistent route preserves its prefix before promotion. A successful persistent write-open removes the RAM shadow; an unresolved backing file is an error, not a silent durable-to-RAM fallback.

Decision flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/fs_route.h · slos_route_for_write
  • kernel/core/syscall.c · SYS_OPEN

Download SVG · Editable DOT

SlFS regions and one inode

Full-size SVG

SlFS v1 · sector order ↓

Superblock
Magic, region offsets, size, replacement intent
Allocation bitmap
Sector ownership
Inode table
256 inodes · 512 bytes each
Data region
File bytes + indirect pointer sectors

One inode · one sector

Identity
Type, name, parent inode, flags
Content
Size, 12 direct pointers, single + double indirect
Time
Creation + modification ticks

The inode table addresses one-sector inodes; their pointers address the data region. Region sizes are schematic, not to scale.

A one-sector inode names its parent and points to file data; region offsets come from the superblock.

Text equivalent and source references
  • The superblock identifies the allocation bitmap, inode table and data region, and holds the optional replacement intent in its padding.
  • There are 256 one-sector inodes. Each stores identity, parent, type, flags, timestamps, size and direct/indirect block pointers. Sectors are 512 bytes; the drawing is not a disk-capacity scale.

Nested record layout. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/blockfs.h · slfs_super, slfs_inode
  • kernel/fs/blockfs.c · blockfs_init

Download SVG · Editable DOT

Three levels of file block addressing

Full-size SVG
Three levels of file block addressing Twelve direct pointers address 12 data sectors. One single-indirect sector holds 128 data-sector pointers. A double-indirect root points to up to 128 pointer sectors, each with 128 data pointers. The theoretical data maximum is 16,524 sectors, or 8,460,288 bytes, excluding pointer overhead. 512 bytes per sector · theoretical maximum file data: 8,460,288 bytes Pointer sectors add overhead; available disk space may limit files first. inode->direct inode->single inode->doubleroot direct->ddata single->sdata doubleroot->leaf leaf->bdata inode Inode direct 12 direct pointers file blocks 0…11 single 1 pointer sector 128 entries doubleroot 1 root pointer sector 128 entries leaf Up to 128 leaf sectors 128 entries each ddata 12 data sectors 6 KiB sdata 128 data sectors 64 KiB bdata 16,384 data sectors 8 MiB
Three levels of file block addressing Twelve direct pointers address 12 data sectors. One single-indirect sector holds 128 data-sector pointers. A double-indirect root points to up to 128 pointer sectors, each with 128 data pointers. The theoretical data maximum is 16,524 sectors, or 8,460,288 bytes, excluding pointer overhead. 512 bytes per sector. Maximum data: 8,460,288 bytes. Pointer sectors add overhead; available disk space may limit files first. inode->direct inode:e->single:e inode:e->root:e root->leaf leaf->data inode Inode direct 12 direct pointers → 12 data sectors · 6 KiB file blocks 0…11 single 1 pointer sector · 128 entries → 128 data sectors · 64 KiB root 1 root pointer sector 128 entries leaf Up to 128 leaf sectors 128 entries each data 16,384 data sectors · 8 MiB

Direct, single-indirect and double-indirect pointers cover successively larger file ranges.

Text equivalent and source references
  • Twelve direct pointers address 12 data sectors. One single-indirect sector holds 128 data-sector pointers.
  • A double-indirect root points to up to 128 pointer sectors, each with 128 data pointers. The theoretical data maximum is 16,524 sectors, or 8,460,288 bytes, excluding pointer overhead.

Pointer topology. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/blockfs.h · SLFS_DIRECT_BLOCKS, SLFS_MAX_FILE_SIZE
  • kernel/fs/blockfs.c · blockfs_read_file_locked

Download SVG · Editable DOT

Replacement intent and mount-time recovery

Full-size SVG
Replacement intent and mount-time recovery Persist an OLD intent with the saved inode pointers, stage a separate new block tree, install the replacement inode, then persist NEW before releasing old blocks and clearing intent. On mount, OLD restores saved pointers; NEW keeps the installed inode. Recovery rebuilds the allocation bitmap and clears intent. This is not protection against torn sectors or a device that violates the ordering model. start->old old->build build->install install->new new->reclaim recovery->rollback phase OLD recovery->keep phase NEW rollback->bitmap keep->bitmap start Replace regular-file content old Persist OLD intent save previous inode block pointers build Allocate + write new block tree install Install replacement inode new Persist NEW intent reclaim Release obsolete blocks clear intent recovery Mount sees replacement intent rollback OLD → restore saved inode keep NEW → keep installed inode bitmap Rebuild allocation bitmap then clear recovered intent note Ordered-I/O recovery, not torn-sector protection or a general transactional filesystem.
Replacement intent and mount-time recovery Persist an OLD intent with the saved inode pointers, stage a separate new block tree, install the replacement inode, then persist NEW before releasing old blocks and clearing intent. On mount, OLD restores saved pointers; NEW keeps the installed inode. Recovery rebuilds the allocation bitmap and clears intent. This is not protection against torn sectors or a device that violates the ordering model. Ordered-I/O recovery only. No torn-sector protection or general transaction guarantee. start->old old->build build->install install->new new->reclaim recovery->bitmap start Replace regular-file content old Persist OLD intent: save old inode block pointers build Allocate + write new block tree install Install replacement inode new Persist NEW intent reclaim Release old blocks; clear intent recovery Mount recovery sees intent OLD: restore saved inode NEW: keep installed inode bitmap Rebuild allocation bitmap clear recovered intent

OLD and NEW distinguish which inode version recovery keeps under the ordered-I/O model.

Text equivalent and source references
  • Persist an OLD intent with the saved inode pointers, stage a separate new block tree, install the replacement inode, then persist NEW before releasing old blocks and clearing intent.
  • On mount, OLD restores saved pointers; NEW keeps the installed inode. Recovery rebuilds the allocation bitmap and clears intent. This is not protection against torn sectors or a device that violates the ordering model.

Transaction / recovery flow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/blockfs.h · slfs_intent
  • kernel/fs/blockfs.c · blockfs_write_file_locked, blockfs_init

Download SVG · Editable DOT

Back to diagram index

Causal history and evidence

Causal edges are stronger than clock order

Full-size SVG
Causal edges are stronger than clock order A shell command causes an actor send and independent local work. The send causes a receive, which causes an application effect. Arrows encode parent relations; illustrative Lamport values increase along them. Events on separate branches need not causally depend on one another. Events retain up to four parents alongside wall-tick and TSC time. Illustrative clocks · arrows point cause → effect No edge between branches is implied by clock order. Up to 4 parents per event; wall ticks and TSC are separate clocks. command->send parent command->other parent send->recv message cause recv->effect parent command shell command L = 40 send actor send L = 41 other other local work L = 42 recv actor receive L = 43 effect application effect L = 44
Causal edges are stronger than clock order A shell command causes an actor send and independent local work. The send causes a receive, which causes an application effect. Arrows encode parent relations; illustrative Lamport values increase along them. Events on separate branches need not causally depend on one another. Events retain up to four parents alongside wall-tick and TSC time. Illustrative clocks · arrows point cause → effect No edge between branches is implied by clock order. Up to 4 parents per event; wall ticks and TSC are separate clocks. command->send parent command->other parent send->recv message cause recv->effect parent command shell command L = 40 send actor send L = 41 other other local work L = 42 recv actor receive L = 43 effect application effect L = 44

Two branches can have ordered Lamport values without an edge between them.

Text equivalent and source references
  • A shell command causes an actor send and independent local work. The send causes a receive, which causes an application effect.
  • Arrows encode parent relations; illustrative Lamport values increase along them. Events on separate branches need not causally depend on one another. Events retain up to four parents alongside wall-tick and TSC time.

Directed acyclic graph. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/causal.h · causal_time_t, causal_event_t
  • kernel/graph/causal.c · causal_emit
  • kernel/graph/actor.c · actor_send, actor_recv

Download SVG · Editable DOT

Hot, archived and snapshot records

Full-size SVG
Hot, archived and snapshot records Instrumented operations enter the 16,384-event hot ring. cjournal spills compact records into bounded SlFS segments, with up to 512 events per file and 32 segment slots. Queries look up resident events or read archived records through the segment index. The separate journal.bin snapshot holds up to 512 restart records. Neither retention tier is unbounded, and emitting an event is not itself a durable disk commit. emit->ring ring->spill ring->snapshot explicit / periodic snapshot spill->segments read->hot resident ID hot->ring resident ID hot->archive aged-out ID archive->segments index narrows disk read emit Instrumented kernel operation ring Hot causal ring 16,384 events · bounded retention spill cjournal spill up to 512 records per segment segments SlFS segment files + index up to 32 segment slots read Query / trace / parents / effects hot Hot lookup archive Archived read-through compact record; payload bytes not retained snapshot Separate causal_persist snapshot up to 512 records · journal.bin note Both tiers are bounded. Retention can remove old ancestry. A successful emit alone is not a durable disk commit.
Hot, archived and snapshot records Instrumented operations enter the 16,384-event hot ring. cjournal spills compact records into bounded SlFS segments, with up to 512 events per file and 32 segment slots. Queries look up resident events or read archived records through the segment index. The separate journal.bin snapshot holds up to 512 restart records. Neither retention tier is unbounded, and emitting an event is not itself a durable disk commit. Bounded tiers: old ancestry can be removed. Emit success alone is not a durable disk commit. emit->ring ring->spill ring:e->snapshot:e explicit / periodic spill->segments read->hot hot:e->ring:e resident ID hot->archive aged-out ID archive:w->segments:w index → disk read emit Instrumented kernel operation ring Hot causal ring 16,384 events · bounded retention spill cjournal spill ≤512 records per segment segments SlFS segment files + index ≤32 segment slots snapshot Separate causal_persist snapshot ≤512 records · journal.bin read Query / trace / parents / effects hot Hot lookup archive Archived read-through compact record, not payload bytes

The hot ring, segment journal and restart snapshot have separate retention and lookup roles.

Text equivalent and source references
  • Instrumented operations enter the 16,384-event hot ring. cjournal spills compact records into bounded SlFS segments, with up to 512 events per file and 32 segment slots.
  • Queries look up resident events or read archived records through the segment index. The separate journal.bin snapshot holds up to 512 restart records. Neither retention tier is unbounded, and emitting an event is not itself a durable disk commit.

Storage / query dataflow. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/causal.h · CAUSAL_MAX_EVENTS
  • include/cjournal.h · segment limits
  • kernel/graph/cjournal.c · cjournal_query_by_id
  • include/causal_persist.h · PERSIST_MAX, PERSIST_PATH

Download SVG · Editable DOT

From segment bytes to an optional signed root

Full-size SVG
From segment bytes to an optional signed root A segment contains its header, compact events and a footer with sizes, checksum, prior checksum and flags. Compact events retain a payload digest rather than full payload bytes. Versioned BLAKE2s hashes feed a Merkle epoch root; explicit signing adds an Ed25519 signature. Segment writing precedes hash/root sidecars, with removal on sidecar failure. A signature is not automatic or a claim of overall correctness. segment:events->hashes canonical event summaries hashes->root Merkle construction root->signature explicit signing segment Segment file · ordered record layout header event count + ID / clock range compact events metadata + parents + payload digest / schema commit footer sizes, checksum, prior segment checksum, flags hashes Hash sidecar versioned BLAKE2s event hashes root Epoch-root sidecar Merkle root signature Optional Ed25519 signature signed root, not blanket correctness write Write segment → hash/root sidecars sidecar failure removes incomplete segment
From segment bytes to an optional signed root A segment contains its header, compact events and a footer with sizes, checksum, prior checksum and flags. Compact events retain a payload digest rather than full payload bytes. Versioned BLAKE2s hashes feed a Merkle epoch root; explicit signing adds an Ed25519 signature. Segment writing precedes hash/root sidecars, with removal on sidecar failure. A signature is not automatic or a claim of overall correctness. segment->hashes canonical event summaries hashes->root Merkle construction root->signature explicit signing segment Segment file Header: count, ranges Events: parents, schema, payload digest Footer: sizes, checksum, prior checksum, flags hashes Hash sidecar versioned BLAKE2s event hashes root Epoch-root sidecar Merkle root signature Optional Ed25519 signature signed root, not blanket correctness write Write segment → hash/root sidecars sidecar failure removes incomplete segment

Checksums, canonical event hashes, Merkle roots and signatures protect different layers.

Text equivalent and source references
  • A segment contains its header, compact events and a footer with sizes, checksum, prior checksum and flags. Compact events retain a payload digest rather than full payload bytes.
  • Versioned BLAKE2s hashes feed a Merkle epoch root; explicit signing adds an Ed25519 signature. Segment writing precedes hash/root sidecars, with removal on sidecar failure. A signature is not automatic or a claim of overall correctness.

Record / dependency map. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/graph/cjournal.c · write_segment, write_segment_hashes, cjournal_sign_segment
  • include/cjournal.h · cjournal_event_t
  • kernel/graph/causal.c · causal_event_hash_with_payload_hash

Download SVG · Editable DOT

Inclusion proofs and behavioral predicates

Full-size SVG
Inclusion proofs and behavioral predicates Recompute a versioned event-summary hash, verify its Merkle path and verify the root signature against the selected node key. This establishes inclusion in that signed epoch. The prove predicates independently scan available events and report PROVED, VIOLATED or INSUFFICIENT_DATA. Neither mechanism establishes complete history, program correctness or externally certified identity; missing evidence limits the claim. event->leaf event->predicate leaf->path path->sign sign->inclusion predicate->result event Archived event summary leaf Recompute versioned event hash path Merkle inclusion path → epoch root sign Verify Ed25519 root signature against selected node public key inclusion Claim: this summary belongs to this signed segment epoch predicate Separate prove predicates scan available event evidence result Predicate outcomes PROVED · within checked evidence VIOLATED · counterexample found INSUFFICIENT_DATA · cannot conclude note Inclusion ≠ completeness ≠ program correctness ≠ externally certified identity. Missing / retained-away evidence limits every claim.
Inclusion proofs and behavioral predicates Recompute a versioned event-summary hash, verify its Merkle path and verify the root signature against the selected node key. This establishes inclusion in that signed epoch. The prove predicates independently scan available events and report PROVED, VIOLATED or INSUFFICIENT_DATA. Neither mechanism establishes complete history, program correctness or externally certified identity; missing evidence limits the claim. Inclusion is not completeness, program correctness, or certified identity. Missing / retained-away evidence limits claims. event->leaf event:e->predicate:e leaf->path path->sign sign->claim predicate->result event Archived event summary leaf Versioned event hash path Merkle inclusion path → epoch root sign Verify Ed25519 root signature against selected node key claim Claim: summary belongs to this signed epoch predicate Separate prove predicates: scan available events result PROVED: checked evidence VIOLATED: counterexample INSUFFICIENT_DATA: cannot conclude

Being included in a signed epoch is not the same claim as satisfying a behavioral predicate.

Text equivalent and source references
  • Recompute a versioned event-summary hash, verify its Merkle path and verify the root signature against the selected node key. This establishes inclusion in that signed epoch.
  • The prove predicates independently scan available events and report PROVED, VIOLATED or INSUFFICIENT_DATA. Neither mechanism establishes complete history, program correctness or externally certified identity; missing evidence limits the claim.

Claim / evidence dependency. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/graph/cjournal.c · epoch proof and signature verification
  • include/prove.h · proof_result_t
  • kernel/graph/prove.c · predicate evaluators

Download SVG · Editable DOT

Back to diagram index

Network and actors

A received frame becomes socket data

Full-size SVG
A received frame becomes socket data VirtIO-net supplies frames. Ethernet dispatches ARP or IPv4; IPv4 dispatches ICMP, UDP or TCP. UDP supports DHCP, DNS and mesh discovery. TCP state and fixed buffers feed user PID-owned sockets or kernel mesh transport. Transmit constructs the headers in reverse order. The TCP table has 32 connection slots. virtio->ethernet received frame ethernet->arp ARP ethernet->ipv4 IPv4 ipv4->icmp protocol 1 ipv4->udp protocol 17 ipv4->tcp protocol 6 tcp->user socket data / readiness tcp->mesh encrypted peer channel virtio VirtIO-net receive queue ethernet Ethernet frame dispatch arp ARP neighbor lookup / reply ipv4 IPv4 protocol dispatch icmp ICMP udp UDP DHCP / DNS / mesh discovery tcp TCP state + receive / transmit buffers user PID-owned socket operations syscall_net → user program mesh Kernel mesh / federation note Receive path shown · transmit adds the same headers in reverse order. 32 TCP connection slots; fixed buffers, not an unbounded host socket stack.
A received frame becomes socket data VirtIO-net supplies frames. Ethernet dispatches ARP or IPv4; IPv4 dispatches ICMP, UDP or TCP. UDP supports DHCP, DNS and mesh discovery. TCP state and fixed buffers feed user PID-owned sockets or kernel mesh transport. Transmit constructs the headers in reverse order. The TCP table has 32 connection slots. Receive path; transmit reverses headers. 32 fixed TCP connection slots. virtio->ethernet ethernet->arp ARP ethernet:e->ipv4:e IPv4 ipv4->icmp 1 ipv4:e->udp:e 17 ipv4:e->tcp:e 6 tcp->user data / readiness tcp:e->mesh:e peer channel virtio VirtIO-net receive queue ethernet Ethernet frame dispatch arp ARP: neighbor lookup / reply ipv4 IPv4 protocol dispatch icmp ICMP · protocol 1 udp UDP · protocol 17 DHCP / DNS / mesh discovery tcp TCP · protocol 6 state + RX / TX buffers user PID-owned user sockets syscall_net → user program mesh Kernel mesh / federation

VirtIO and Ethernet feed protocol-specific paths, not one universal packet handler.

Text equivalent and source references
  • VirtIO-net supplies frames. Ethernet dispatches ARP or IPv4; IPv4 dispatches ICMP, UDP or TCP.
  • UDP supports DHCP, DNS and mesh discovery. TCP state and fixed buffers feed user PID-owned sockets or kernel mesh transport. Transmit constructs the headers in reverse order. The TCP table has 32 connection slots.

Protocol dispatch tree. Source paths refer to the atlas baseline; the kernel checkout is private.

  • kernel/drivers/virtio_net.c · receive path
  • kernel/net/net.c · Ethernet / IPv4 dispatch
  • kernel/net/tcp.c · tcp_handle_packet
  • kernel/core/syscall_net.c · socket dispatch
  • include/tcp.h · TCP_MAX_CONNS

Download SVG · Editable DOT

Orderly TCP connection lifetime

Full-size SVG
Orderly TCP connection lifetime An active open reaches SYN_SENT and accepts SYN+ACK; a listener creates a SYN_RECEIVED child and accepts ACK. Both reach ESTABLISHED. Local close passes FIN_WAIT_1 and FIN_WAIT_2, while peer-first close passes CLOSE_WAIT and LAST_ACK. Simultaneous close may use CLOSING; TIME_WAIT expires after 200 ticks. Resets, retries and cleanup are omitted; FIN_WAIT_2 also has a bounded timeout. Main orderly paths · resets, retries, and error cleanup omitted. FIN_WAIT_2 also has a bounded timeout in this implementation. closed->listen listen closed->synsent connect / send SYN listen->synrecv SYN / child connection synsent->established SYN+ACK / send ACK synrecv->established ACK established->fin1 local close / FIN established->closewait peer FIN / ACK fin1->fin2 ACK of FIN fin1->closing FIN without FIN ACK fin1->timewait FIN + ACK fin2->timewait peer FIN / ACK closing->timewait ACK closewait->lastack local close / FIN lastack->closed ACK timewait->closed timer · 200 ticks closed CLOSED listen LISTEN synsent SYN_SENT synrecv SYN_RECEIVED established ESTABLISHED fin1 FIN_WAIT_1 fin2 FIN_WAIT_2 closing CLOSING closewait CLOSE_WAIT lastack LAST_ACK timewait TIME_WAIT
Orderly TCP connection lifetime An active open reaches SYN_SENT and accepts SYN+ACK; a listener creates a SYN_RECEIVED child and accepts ACK. Both reach ESTABLISHED. Local close passes FIN_WAIT_1 and FIN_WAIT_2, while peer-first close passes CLOSE_WAIT and LAST_ACK. Simultaneous close may use CLOSING; TIME_WAIT expires after 200 ticks. Resets, retries and cleanup are omitted; FIN_WAIT_2 also has a bounded timeout. Main orderly paths · resets, retries, and error cleanup omitted. FIN_WAIT_2 also has a bounded timeout in this implementation. closed->listen listen closed->synsent connect / send SYN listen->synrecv SYN / child connection synsent->established SYN+ACK / send ACK synrecv->established ACK established->fin1 local close / FIN established->closewait peer FIN / ACK fin1->fin2 ACK of FIN fin1->closing FIN without FIN ACK fin1->timewait FIN + ACK fin2->timewait peer FIN / ACK closing->timewait ACK closewait->lastack local close / FIN lastack->closed ACK timewait->closed timer · 200 ticks closed CLOSED listen LISTEN synsent SYN_SENT synrecv SYN_RECEIVED established ESTABLISHED fin1 FIN_WAIT_1 fin2 FIN_WAIT_2 closing CLOSING closewait CLOSE_WAIT lastack LAST_ACK timewait TIME_WAIT

Active and passive open converge on ESTABLISHED; each close direction has a different path.

Text equivalent and source references
  • An active open reaches SYN_SENT and accepts SYN+ACK; a listener creates a SYN_RECEIVED child and accepts ACK. Both reach ESTABLISHED.
  • Local close passes FIN_WAIT_1 and FIN_WAIT_2, while peer-first close passes CLOSE_WAIT and LAST_ACK. Simultaneous close may use CLOSING; TIME_WAIT expires after 200 ticks. Resets, retries and cleanup are omitted; FIN_WAIT_2 also has a bounded timeout.

State machine. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/tcp.h · connection state enum
  • kernel/net/tcp.c · tcp_handle_packet, tcp_close, tcp_retransmit_check

Download SVG · Editable DOT

A kernel actor is a bounded mailbox

Full-size SVG
A kernel actor is a bounded mailbox actor_send or a named route chooses a target using local-first or round-robin policy. Local delivery enqueues a message if capacity exists; actor_recv removes it and links its cause. The kernel has 64 actor slots, 64 messages per mailbox and a 256-byte message payload maximum. Unknown/full destinations fail; remote proxies use federation. These are not the local Hew runtime mailboxes. send->route route->local local->box yes · capacity available local->remote remote proxy local->reject unknown / full box->recv application receives send actor_send / actor_send_by_name route Actor ID / named route local-first or round-robin local Local destination? box Kernel actor mailbox head · read 64 message slots tail · write message: type + sender + ≤256 payload bytes + causal ID recv actor_recv remove message + emit receive cause remote Remote proxy → federation reject Missing / full mailbox → delivery failure note 64 actor slots · these mailboxes are kernel objects, not the cooperative Hew runtime's actor mailboxes.
A kernel actor is a bounded mailbox actor_send or a named route chooses a target using local-first or round-robin policy. Local delivery enqueues a message if capacity exists; actor_recv removes it and links its cause. The kernel has 64 actor slots, 64 messages per mailbox and a 256-byte message payload maximum. Unknown/full destinations fail; remote proxies use federation. These are not the local Hew runtime mailboxes. 64 kernel actor slots. Separate from cooperative Hew mailboxes. send->route route->local local->box yes · capacity local:e->remote:e remote local:e->fail:e unknown / full box->recv send actor_send / actor_send_by_name route Named route / actor ID local-first or round-robin local Local destination? box Kernel actor mailbox 64 slots · ≤256 payload bytes head/read → tail/write type + sender + causal ID recv actor_recv remove message; emit receive cause remote Remote proxy → federation fail Missing / full → delivery failure

Named routes choose a local mailbox or a remote proxy; neither is an unbounded queue.

Text equivalent and source references
  • actor_send or a named route chooses a target using local-first or round-robin policy. Local delivery enqueues a message if capacity exists; actor_recv removes it and links its cause.
  • The kernel has 64 actor slots, 64 messages per mailbox and a 256-byte message payload maximum. Unknown/full destinations fail; remote proxies use federation. These are not the local Hew runtime mailboxes.

Routing / ring-buffer map. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/actor.h · actor_t, actor_msg_t, actor_route_t
  • kernel/graph/actor.c · actor_send, actor_send_by_name, actor_recv

Download SVG · Editable DOT

Three different meanings of actor execution

Full-size SVG
Three different meanings of actor execution The local restricted Hew runtime runs cooperative turns and mailboxes in one ring-3 process worker. Its freestanding adapter requests generic kernel operations through INT 0x80. SlOS independently preempts that OS task on the BSP and supplies I/O wait/wake. The kernel actor registry is a separate ring-0 object system; no automatic mapping of Hew actors to kernel actors or mesh peers is implied. cluster_user ONE RING-3 HEW PROCESS cluster_kernel RING 0 turns->adapter process, stream, timer, network operations adapter->gate gate->task task->io block / wake turns Local restricted Hew runtime cooperative actor turns + mailboxes adapter Freestanding C runtime / SDK adapter gate INT 0x80 task Preemptively scheduled OS task user execution remains on BSP io wait-many + streams + TCP actors Separate kernel actor registry actor_t + bounded mailboxes note Hew actor turn ≠ kernel task ≠ kernel actor. The local runtime is not Hew's normal Rust libhew_rt or an upstream SlOS target.
Three different meanings of actor execution The local restricted Hew runtime runs cooperative turns and mailboxes in one ring-3 process worker. Its freestanding adapter requests generic kernel operations through INT 0x80. SlOS independently preempts that OS task on the BSP and supplies I/O wait/wake. The kernel actor registry is a separate ring-0 object system; no automatic mapping of Hew actors to kernel actors or mesh peers is implied. cluster_user ONE RING-3 HEW PROCESS cluster_kernel RING 0 turns->adapter process, stream, timer, network operations adapter->gate gate->task task->io block / wake turns Local restricted Hew runtime cooperative actor turns + mailboxes adapter Freestanding C runtime / SDK adapter gate INT 0x80 task Preemptively scheduled OS task user execution remains on BSP io wait-many + streams + TCP actors Separate kernel actor registry actor_t + bounded mailboxes note Hew actor turn ≠ kernel task ≠ kernel actor. The local runtime is not Hew's normal Rust libhew_rt or an upstream SlOS target.

A cooperative Hew actor turn runs inside an OS process; it is not a kernel actor or an AP worker.

Text equivalent and source references
  • The local restricted Hew runtime runs cooperative turns and mailboxes in one ring-3 process worker. Its freestanding adapter requests generic kernel operations through INT 0x80.
  • SlOS independently preempts that OS task on the BSP and supplies I/O wait/wake. The kernel actor registry is a separate ring-0 object system; no automatic mapping of Hew actors to kernel actors or mesh peers is implied.

Execution-boundary comparison. Source paths refer to the atlas baseline; the kernel checkout is private.

  • consumer: runtime/hew_slos_actor.c · cooperative actor scheduler
  • consumer: runtime/current.c · coroutine safepoints
  • kernel/core/task.c · schedule
  • include/actor.h · actor_t

Download SVG · Editable DOT

Remote delivery keeps a local causal anchor

Full-size SVG
Remote delivery keeps a local causal anchor Node A sends target actor, payload, sender node/actor, remote causal ID, Lamport clock and summary hash through the encrypted mesh. Node B decrypts and dispatches, merges the remote clock and anchors the remote cause, then attempts local mailbox enqueue. A later receive links local delivery ancestry. Unknown/full destinations fail; bounded retries and retained proofs are not exactly-once delivery. a->a1 t->t1 b->b1 a1->a2 a1->t1 1  actor message + cause a2->a3 a3->a4 a4->a5 t1->t2 t2->t3 t2->b2 2  decrypt + dispatch t3->t4 t4->t5 b1->b2 b2->b3 3  merge remote clock; anchor remote cause b3->b4 4  enqueue local mailbox or record delivery failure b4->b5 5  local receive event links delivery ancestry a Node A · federation t Encrypted mesh b Node B · federation a1 a2 a3 a4 a5 t1 t2 t3 t4 t5 b1 b2 b3 b4 b5 note Origin: node + actor + causal ID Lamport clock + summary hash Bounded retry ≠ exactly-once delivery
Remote delivery keeps a local causal anchor Node A sends target actor, payload, sender node/actor, remote causal ID, Lamport clock and summary hash through the encrypted mesh. Node B decrypts and dispatches, merges the remote clock and anchors the remote cause, then attempts local mailbox enqueue. A later receive links local delivery ancestry. Unknown/full destinations fail; bounded retries and retained proofs are not exactly-once delivery. a->a1 t->t1 b->b1 a1->a2 a1->t1 1 actor message + cause a2->a3 a3->a4 a4->a5 t1->t2 t2->t3 t2->b2 2 decrypt + dispatch t3->t4 t4->t5 b1->b2 b2->b3 3 merge remote clock; anchor remote cause b3->b4 4 enqueue local mailbox or record delivery failure b4->b5 5 local receive event links delivery ancestry a Node A · federation t Encrypted mesh b Node B · federation a1 a2 a3 a4 a5 t1 t2 t3 t4 t5 b1 b2 b3 b4 b5 note Origin: node + actor + causal ID Lamport clock + summary hash Bounded retry ≠ exactly-once delivery

A transported message carries enough origin context to connect remote ancestry to local delivery.

Text equivalent and source references
  • Node A sends target actor, payload, sender node/actor, remote causal ID, Lamport clock and summary hash through the encrypted mesh.
  • Node B decrypts and dispatches, merges the remote clock and anchors the remote cause, then attempts local mailbox enqueue. A later receive links local delivery ancestry. Unknown/full destinations fail; bounded retries and retained proofs are not exactly-once delivery.

Sequence diagram. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/federation.h · federation_msg_t, retry limits
  • kernel/graph/federation.c · federation receive loop
  • kernel/graph/actor.c · actor_send_remote, actor_recv

Download SVG · Editable DOT

Discover, connect, age and reconnect

Full-size SVG
Discover, connect, age and reconnect UDP announcements on 5100 discover up to eight peers. TCP on 5101 performs the simplified Noise_XX-like handshake before encrypted traffic. At 100 Hz, connected peers become stale beyond 6000 ticks and disconnected beyond 12000; refresh can restore a stale peer, and a disconnected peer retries with backoff. Transport failures can disconnect immediately. Local peers use SPSC channels, not TCP/Noise. discovered->connecting connection attempt connecting->handshake exchange keys connected->stale last seen > 6000 ticks connected->disconnected transport failure stale->connected announcement refresh stale->disconnected last seen > 12000 ticks disconnected->connecting bounded-backoff reconnect announce->discovered announcement handshake->connected success discovered DISCOVERED connecting CONNECTING connected CONNECTED stale STALE disconnected DISCONNECTED announce UDP discovery · port 5100 up to 8 peers handshake TCP handshake · port 5101 simplified Noise_XX-like exchange note 100 Hz tick basis · announce ~5 s, heartbeat ~3 s Local inter-core peers use SPSC channels, not TCP / Noise.
Discover, connect, age and reconnect UDP announcements on 5100 discover up to eight peers. TCP on 5101 performs the simplified Noise_XX-like handshake before encrypted traffic. At 100 Hz, connected peers become stale beyond 6000 ticks and disconnected beyond 12000; refresh can restore a stale peer, and a disconnected peer retries with backoff. Transport failures can disconnect immediately. Local peers use SPSC channels, not TCP/Noise. 100 Hz; announce ~5 s; heartbeat ~3 s. Local peers: SPSC, not TCP / Noise. announce->discovered announcement discovered->connecting connect attempt connecting->handshake exchange keys handshake->connected success connected->stale age > 6000 ticks connected:e->disconnected:e transport failure stale:e->connected:e refresh stale->disconnected age > 12000 ticks disconnected:e->connecting:e backoff retry announce UDP discovery · 5100 up to 8 peers discovered DISCOVERED connecting CONNECTING handshake TCP handshake · 5101 simplified Noise_XX-like exchange connected CONNECTED stale STALE disconnected DISCONNECTED

TCP peers age from last-seen time; local inter-core peers bypass network stale checks.

Text equivalent and source references
  • UDP announcements on 5100 discover up to eight peers. TCP on 5101 performs the simplified Noise_XX-like handshake before encrypted traffic.
  • At 100 Hz, connected peers become stale beyond 6000 ticks and disconnected beyond 12000; refresh can restore a stale peer, and a disconnected peer retries with backoff. Transport failures can disconnect immediately. Local peers use SPSC channels, not TCP/Noise.

Peer state machine. Source paths refer to the atlas baseline; the kernel checkout is private.

  • include/mesh.h · limits, peer states, transports
  • kernel/graph/mesh.c · mesh_tick, mesh_connect_peer, handle_handshake

Download SVG · Editable DOT

Back to diagram index