| name | oscortex-architecture |
| description | Canonical OSCortex OS architecture — kernel vs Flutter userspace, process isolation, shell vs apps, runtime install model. Use when designing features, refactoring boot/app launch, writing docs, or any question about how OSCortex should work (not legacy hacks).
|
OSCortex Architecture
Read first: docs/arch.txt · docs/hardware.txt
Out of scope: landing/ — never modify unless explicitly requested.
One-sentence model
Kernel owns hardware and policy. Flutter owns everything above the kernel — window management, shell, and applications — with one hard rule: each runnable unit that can crash is its own process.
Layers
USER APPS (Flutter) — one process per app, own engine instance, own surface(s)
SYSTEM SHELL / WM (Flutter) — one system process; launcher, desktop, chrome, gen UI
INIT / SUPERVISOR — PID 1; boot, spawn/stop/restart, reap zombies; NOT the widget tree
KERNEL — scheduler, memory, IPC, drivers, compositor, focus, syscalls
Non-negotiable rules
- Process isolation — user apps never share an address space with the shell or each other.
- Failure containment — one app crash must not take down shell, init, or other apps.
- One render path — every pixel via Flutter engine → surface → kernel compositor. No parallel shells or demo/fallback render paths left in tree.
- Runtime install — apps ship as built AOT bundles (
.osx); installed on a running OS via syscalls. Not “add to apps/, rebuild ISO, reflash.”
- System apps — shell and core system UI are uninstallable; still separate processes, not merged into PID 1.
- Pivot = delete — when architecture or approach changes, remove the old path entirely. No dual boot stacks, no “legacy for now.”
App lifecycle (product)
| Step | Where |
|---|
| Dev build | Flutter project → AOT artifact (pack tool → .osx) |
| Install | app_install syscall → persistent storage |
| Launch | spawn new app host process (embedder + engine + that app's AOT) |
| Uninstall | app_uninstall (reject for system apps) |
| List | app_list / platform channel for shell store UI |
Kernel vs Flutter boundary
| Kernel | Flutter userspace |
|---|
| Compositor, surface table, z-order | Widgets, layout, window chrome (Dart) |
| Focus, hit-testing, input routing | Pointer/key handling inside engine |
surface_create / present / flip | present_callback → pixels |
| Process spawn, mmap, capabilities | App logic, platform channels |
| Drivers, compositor blit, input HW | Never maps MMIO / PCI from userspace |
Hardware detail: docs/hardware.txt · skill oscortex-hardware
Hardware (summary)
- One render path: Flutter →
gpu_submit_strided → compositor → framebuffer (CPU blit today).
gpu_submit ≠ GPU vendor driver — pixel copy into surfaces; real GPU is a future compositor backend.- Each device class (audio, touchpad, storage, …) needs its own kernel driver; APIs are shared via syscalls.
- Multi-arch: port CPU in
kernel/src/arch/; drivers per platform; CDP WASM portable across ISAs.
Canonical paths
| Path | Role |
|---|
kernel/ | Kernel — compositor, WM events, syscalls, process model |
tools/flutter-embedder/ | Flutter host binary (oscortex-host) |
tools/flutter-engine/engine_patch.py | Only engine patch entry point |
apps/oscortex_app/ | System shell source (not an app manager holding all apps) |
scripts/build-iso.sh | ISO build — ships kernel, init, engine, shell; not user app catalog |
docs/arch.txt | Canonical architecture document |
docs/hardware.txt | Drivers, display, device classes, CDP |
.cursor/skills/oscortex-hardware/SKILL.md | Agent guide for driver/hardware work |
.cursor/skills/oscortex-ci-cd/SKILL.md | Branching, PRs, CI, release to main |
When implementing
- Align new code with target architecture in
docs/arch.txt, not temporary bring-up shortcuts.
- Do not add isolate-in-PID-1 launches for user apps.
- Do not add kernel boot demos, grid splashes, synthetic cursors, or compositor placeholders.
- Extend existing modules; do not duplicate embedder/patch/syscall logic in new files.
