NAME
wombat - design notes
DESCRIPTION
This document contains notes on designing wombat.
A personal computing environment
My goal is to have a target for writing programs that compose. Let's explore that a little.
Over the past few years, I've come to appreciate writing software as html quine. Those are portable and self-contained, allowing me to have one version and share it across multiple computers. A web browser is the only requirement to run them.
The problem with html quines is that they don't compose nicely. The browser is, thankfully, sandboxed. It can't reach into the file system without extensions, and we probably don't want it to do so regardless.
So for two quines to communicate, quine A should export a file manually and quine B should import it, manually. Or some server should communicate with both. We lose the portable & self-contained aspects.

And because they don't compose nicely, to create a new quine, QC, that uses aspects of QA and QB, we need assemble it from scratch, creating a fork of the parts we're bringing in as we go.

Wombat is designed to solve that. It's a computing environment in a quine where programs can compose. Saving the quine saves the whole runtime in a file, and opening that file restores it.

I've been thinking about what properties I value for this environment. In addition to the portable and self-contained ones we discussed, these two helped me guide my choices:
- Simple mechanics so that I still remember them in 10 years. And If I forget them, I should be able to pick them up fast.
- Minimum policy out of the box, I want to be able to tune each environment, from behavior to how it looks
Design choices
I chose javascript as the target environment. This makes it straightforward for the quine to run on a browser or any other javascript host.
The system's representation is plain text.
The system is made for a single, root user at a time. There is no user-based permission model. Saving the quine acts as a snapshot. Reloading it restores the last working state.
I need an abstraction for shared state. Plan9 sees everything as a file. I initially went with that as well, then realized that it was too restrictive for a much simpler system. Under the file abstraction, directories cannot be written to. Paths need to be walked. Plan9 built upon a legacy where files existed, the rigidity is a benefit there. On wombat I chose a model closer to the web: everything is a resource, a resource has a path and responds to requests.
With no file system and constrained parent/children hierarchy I needed a way to keep resources discoverable. I chose to introduce links via the same format as nex.
I chose to make resources reactive. A process's job then is to declare its resources and subscribe to changes.
To keep the mechanics simple, I needed a way to make every single resource operation, including reactive subscription, go through the same system call boundary. That's when I introduced req.
Every resource has a path, but having to remember how to build paths for every resource we interact with can get complex very fast. I chose to add bindings through namespace in a similar way to Plan9. While full path must start with a /, a binding doesn't. Relative bindings then take the role of a file descriptor: a short name for a resource.
Since every resource is a file, req transports text only. I chose to define a protocol that specifies the three base verbs and response shape. That way, processes and state don't need to be on the same physical machine.