The Heap Is Just a Document: How Stof Actually Works
Every document on your computer is a pile of bytes. A photo, a spreadsheet, a JSON file: underneath, it's all bytes sitting next to other bytes.
Here's the idea behind Stof. What if some of those bytes were instructions? Small pieces that say "add one to that number over there" or "join those two words into a name." Not code stored somewhere else that reads the document, but instructions inside the document, right next to the data they're allowed to change.
That's a Stof document: data, and the instructions for changing it, in the same pile of bytes. JSON that runs.
You've already used this
If that sounds strange, it isn't. You've used a version of it for years: a spreadsheet.
Put a formula in cell B2, and it can read and change other cells in the same sheet. It can't reach into another spreadsheet on your computer, and it can't touch your files. It only knows about the sheet it lives in.
Nobody finds that surprising. Stof takes the same idea, instructions that live in the data and only affect the data around them, and applies it to documents in general, not just grids of numbers.
Same idea, bigger format
Here's a plain JSON object:
{
"name": {
"first": "Bob",
"last": "Jones"
}
}
Any JSON document is already a valid Stof document. Nothing to convert. But Stof lets you add instructions right next to the data:
{
"name": {
"first": "Bob",
"last": "Jones"
},
"full_name": (): str => self.name.first + ' ' + self.name.last
}
#[main]
fn main() { pln(self.full_name()); }full_name isn't stored somewhere else and pointed at this data. It's part of the document, the way a formula is part of the sheet.
It's a real runtime
Stof is a runtime, the same kind of thing as a JavaScript engine or a Python interpreter. Something has to read those instructions and carry them out, and that's what the Stof runtime does.
Here's what's different. When JavaScript or Python run a program, they keep working memory (the heap) where the program's data lives while it runs. That memory belongs to that one running program, on that one machine. When the program ends, or you want to hand its data to something else, the memory is gone. What's left is a snapshot: a JSON file or a database row that some other program has to already understand.
Stof doesn't work that way. Its memory is the document. There's no private place where the real data lives while the document sits there as a copy. The document is the memory the runtime uses, whether it's on your disk, in the middle of a calculation, or arriving somewhere else.
You can send it anywhere
Because the memory is a document, you can do document things with it: save it, send it to another server, store it in a database.
And when it arrives, it isn't inert. It's not a snapshot waiting for the other side to have the right code installed. It's the same document it was on your machine, instructions included, so it can pick up where it left off, check itself, or run whatever it needs to.
Why it stays safe
Remember that a formula can only touch its own sheet? Same rule here. A function in a Stof document can only read and change that document. It can't reach your files, your database, or another document next to it, unless the app running it hands it a way to. Every call also has a time limit and a memory limit, so a function that runs away fails on its own.
That isn't a feature added on top. It's what happens when the instructions and the data they change are the same pile of bytes: there's nothing outside it for the instructions to reach. Security and the Sandbox has the details.
A small example
Say a customer has a credit limit, and a function that checks whether a new charge is allowed:
credit_limit: 500
used: 320
fn can_charge(amount: float) -> bool {
self.used + amount <= self.credit_limit
}
#[main]
fn main() {
pln(self.can_charge(100));
pln(self.can_charge(200));
}That document can be created on one server, sent across the network, and land on another machine. Nobody sets anything up on the receiving end. When it arrives, can_charge works exactly as it did before, checking only the numbers in its own document.
Why it's useful
Documents grow and change as they move around, and Stof documents are no different. The part that defines an API or the validation rules can start separate from the part that holds working data, and the two can be combined or split as needed.
Stof also works with other formats (JSON, YAML, TOML, form data, and more), so data from many places, and the logic that makes sense of it, can come together in one document, get worked on, and go back out in whatever format you need:
// a place in the document for working data
working: {}
// data from somewhere else (your app can also parse it in)
fn load() {
parse('{ "credit_limit": 500, "used": 320 }', self.working, 'json');
}
fn can_charge(amount: float) -> bool {
self.working.used + amount <= self.working.credit_limit
}
#[main]
fn main() {
self.load();
if (self.can_charge(100)) self.working.used += 100;
pln(self.can_charge(100));
// ready for your app, in the format it wants
pln(stringify('yaml', self.working));
}The short version
Other runtimes run code that happens to use some data. A Stof document carries its own instructions, and running it is reading and writing the document itself.
That's the whole idea. Everything else (the graph underneath, the sandbox, running the same in Rust, Python, or a browser) is built on that one shift: a program's memory isn't private anymore. It's a document.
For the details of the graph, see How Stof Works and The Document Graph.
