Architecture
fishbowl is built in four layers. Each layer depends only on the one below it.
Code layers
Section titled “Code layers”Kernel — The only privileged code. Manages the process table, routes I/O through the virtual filesystem, handles file descriptors, signals, and pipes. Knows nothing about fileserver implementations.
Runtime — The shell interpreter, init system, package manager, and WASM execution host. Builds on the kernel’s syscall surface. Provides the Unix() builder API for composing systems.
Bins — The standard library of executable commands: coreutils, text tools, file tools, process tools, system tools. Each bin is a pure function (proc: ProcContext) => Promise<ExitCode>.
Build lifecycle
Section titled “Build lifecycle”.build() — Freezes extensions into an immutable Image. The image is a snapshot; no further changes are possible after this point.
.boot(runtime) — Starts the init system on top of the image, adding a writable overlay layer. Returns a live Instance you can interact with. Each .boot() call produces an independent instance.
Packages — JS bundles and WASM binaries evaluated into a running image by the package manager. Packages operate at the runtime layer and extend it dynamically.
Components
Section titled “Components”Kernel layer
Section titled “Kernel layer”| Component | What it does |
|---|---|
| Kernel | Process table, spawn, signals, pipes, fd routing |
| Fileservers | VFS protocol, memoryFS, overlayFS, srvFS, namespaces |
| Streams | Async readable/writable stream primitives |
| Pipes | Kernel-managed pipe pairs, refcounting |
| Inodes | INode model, mode, uid, exec bit |
| Errors | Error taxonomy, POSIX errno mapping |
| Logging | KernelLog ring buffer, dmesg, TRACE env var |
Runtime layer
Section titled “Runtime layer”| Component | What it does |
|---|---|
| Shell | POSIX interpreter, parser, builtins, expansion |
| Runtime | Platform abstraction, boot, PlatformCapabilities |
| Container | Process-level isolation, layered image model |
| Init | Dependency graph, supervisor, restart policies |
| Packages | Registry, semver resolver, JS + WASM evaluator |
| Adapters | Host adapters: Node.js, browser, test |
Bins layer
Section titled “Bins layer”| Component | What it does |
|---|---|
| Bins | Standard library of executable commands |
Build & distribution
Section titled “Build & distribution”| Component | What it does |
|---|---|
| Bootstrap | Boot sequence, image construction |
| Developer API | Public API surface, Extension model |