The Heap is Just a Document: How Stof Actually Works

Every document on your computer is just a pile of bytes. A photo, a spreadsheet, a JSON file — underneath, it's all the same kind of stuff: bytes sitting next to other bytes.

Now here's the idea behind Stof: what if a few of those bytes were instructions? Small pieces that say "add one to that number over there" or "combine those two words into a name"? Not code stored somewhere else that reads the document — instructions that live inside the document itself, right next to the data they're allowed to change.

That's a Stof document. Data and the instructions for changing that data, in the same pile of bytes.

You've already used this

If that sounds strange, it isn't, really. You've been using a version of this idea for years: a spreadsheet.

Put a formula in cell B2, and it can read and change other cells in that same sheet. It can't reach into a different spreadsheet on your computer. It can't touch your files. It only knows about the sheet it lives in, and it only affects the sheet it lives in.

Nobody finds that surprising. It's just how spreadsheets work. Stof takes that same idea — instructions that live inside 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, as-is. Nothing to convert. But Stof lets you add instructions right alongside the data:

data.stofPlayground ↗

{
  "name": {
      "first": "Bob",
      "last": "Jones"
  }

  "full_name": ():str => { self.name.first + " " + self.name.last }
}

#[main]
fn main() { pln(self.full_name()); }

Output

That full_name function isn't stored somewhere else and pointed at this data. It's part of the document, the same way the spreadsheet formula is part of the sheet. Call it, and it reads and changes bytes that live right next to it.

It's a real runtime

To be clear, Stof is a real runtime, the same category of thing as JavaScript engine or a Python interpreter. Something has to actually read those instructions and carry them out, and that's what the Stof engine does.

Here's the part that's different. When JavaScript or Python run a program, they keep a working memory (called a heap) where all the data your program is using actually lives while it runs. That memory is private to that one running program. It exists only while the program is running, on that one machine. The moment the program ends, or you want to hand that data to something else, the memory is gone. What you're left with is a snapshot: a JSON file, a database row, something you'd have to hand to a separate program that already knows what to do with it.

Stof's runtime doesn't work that way. Its "memory" is the document itself. There's no separate, private place where the real data lives while the document just sits there as a copy. The document is the memory the runtime is using, whether it's sitting on your disk, mid-calculation, or arriving somewhere else entirely.

You can send it anywhere

Because the memory is just a document, you can do normal document things with it. Save it, email it, or send it to another server.

And when it arrives, it's not inert. It's not a snapshot waiting for the other side to already have the right code installed to make sense of it. It's the same bytes it was on your machine, instructions included, so it can pick up right where it left off, or validate itself, or run whatever function it needs to run.

Why it stays safe

Remember the spreadsheet formula that can only touch its own sheet? Same rule here. A function inside a Stof document can only read and change data inside that same document. It can't reach into your other files, your database, or another document sitting next to it.

This isn't a safety feature someone added on top. It's just what happens naturally when the instructions and the data they affect are the same pile of bytes — there's nothing outside that pile for the instructions to reach (unless explicitely attached to the runtime by the host).

A small example

Say you have a pricing rule for a customer: a credit limit, and a function that checks whether a new charge is allowed.

example.stofPlayground ↗

credit_limit: 500
used: 320

fn can_charge(amount: float) -> bool {
  (self.used + amount) <= self.credit_limit
}

#[main]
fn example() {
  assert(self.can_charge(100));
  assert_not(self.can_charge(200));
  pln('success');
}

Output

That document can be created on one server, sent across the network, and land on a completely different machine. Nobody has to set anything up ahead of time on the receiving end. The moment it arrives, can_charge works exactly like it did before it was sent, checking only the numbers that live in that same document.

Why is this useful?

Documents grow and change over time and as they change hands. Stof documents are no different.

The document that defines an API, validation logic, or bindings can start completely independent from the document that holds working data. They can then be partially combined or split as needed.

Stof works seamlessly with other formats, like JSON, YAML, TOML, images, PDFs, etc., so distributed data and the APIs that are meaningful to it can be unified by Stof, operated on, and then exported to the working format of your choice in one pass.

useful.stofPlayground ↗

// a place in the doc for working data
working: {}

// get data from someplace else - can also be parsed in by host
async fn get_data() {
  const stof = '{ "credit_limit": 500, "used": 320 }';
  parse(stof, self.working);
}

fn can_charge(amount: float) -> bool {
  (self.working.used + amount) <= self.working.credit_limit
}

#[main]
fn example() {
  await self.get_data();

  if (self.can_charge(100)) {
      self.working.used += 100;
  }
  assert_not(self.can_charge(100));

  // ready to be grabbed and worked with by the host
  pln(stringify('yaml', self.working));
}

Output

The short version

Other runtimes run code that happens to use some data. A Stof document carries its own instructions, and running it is just reading and writing to the document itself.

That's the whole idea. Everything else — the graph structure underneath, the sandboxing, the way it can be embedded in Rust, WebAssembly, or a browser — is built on top of that one shift: the memory a program uses isn't private anymore. It's just a document.