← Docs

Theory of operation

How bode actually works: what a bode is, what crosses a wire, what gets recomputed and when, and the three vocabularies that let something other than a mouse drive the whole thing.

The spec ↗Every field and every verb, generated from the code that implements them.

1A bode is a graph, and the graph is the program

A bode is blocks and the wires between them. Each block is a pure function: compute takes what arrived on its input ports and the params you set, and returns values on its output ports. It reads no clock, touches no storage and keeps nothing between calls.

That purity is not an aesthetic preference, it is what everything else here is built on. Because a block's output depends on nothing but its inputs and params, the evaluator can know in advance what a change cannot possibly affect - which is the next section.

Anything a block genuinely needs from the outside world arrives as a parameter it did not fetch. A clock's current time is handed in; it is not read inside compute.

2It is a DAG, and a loop is not a strange bode - it is an unevaluable one

Values flow one way. The evaluator walks the graph once, resolving each block after the blocks that feed it, so a cycle has no answer: not a wrong answer, no answer. That makes refusing one a correctness requirement rather than a guard rail.

A loop can be proposed three ways, so it is refused in three places with one rule. Dragging a wire asks isValidConnection, which refuses the edge before it exists rather than erroring after. Opening a file and applying an op both go through checkWire, which is the same function - written once precisely so a file and a caller cannot be told different things about the same graph.

Independent branches are resolved in parallel. Each block awaits only its own dependencies, so a slow QR render never blocks a sibling.

3Nothing recomputes unless it has to

The obvious way to cache a block's result is to hash its inputs. That is also the wrong way: it means hashing a 2MB JSON payload on every keystroke, which is the exact cost you were trying to avoid.

Because compute is pure, a block's output is fully determined by three small things: which block it is, its params, and the fingerprints of whatever feeds it. So hash those instead and never touch the payload at all.

fp(block) = hash(blockId | params | [inPort:fp(upstream):outPort, ...])

That is a Merkle tree over the graph. Editing a param at the top of a chain invalidates everything below it and nothing above. The cache is keyed by fingerprint rather than by block id, so it survives undo, redo, and deleting a block and adding it back.

Position is deliberately excluded, so dragging a block recomputes nothing. There is a second hash over the whole document that *does* include position, because "has this changed since I saved?" is a different question from "does this need recomputing?" - and laying a canvas out is real work that a save must not silently drop. Two hashes, two questions; neither is reused for the other.

4Wires are typed, and lossy is allowed

There are 9 port types. A wire between two of them is graded, not simply permitted or forbidden: exact passes the value through untouched, safe converts without losing anything, lossy and risky convert and may complain at run time, and invalid is refused while you are still dragging.

The grading is the point. A tool that only allows conversions it can guarantee is a tool that makes you insert adapter blocks all day; one that allows everything silently loses your data. Letting a lossy wire connect and say so is the honest middle, and it is why the table below has four shades rather than a boolean.

from ⟍ totextmarkdownjsonrowsbytesimageaudiovideoany
text=~?·~···~
markdown!=?·~···~
json~~=?····~
rows~~==····~
bytes!!··=···~
image····~=··~
audio····~·=·~
video····~··=~
any~~~~~~~~=
=exact~safe!lossy?risky·invalid

One consequence worth knowing because it has bitten: rows → json is exact, which means a rows port must carry a real array. Nothing parses in the wire, so a block emitting a JSON *string* onto a rows port produces something the next block cannot read.

5A type says what may connect; it does not say what should

The table above answers "is this wire allowed". It is nearly useless for answering "which wire did you mean", because text carries half the catalogue. An ID Inspector emits kind ("ULID"), created (a timestamp) and info (a breakdown); the first two are both text, and nothing about their type tells you which one belongs in a clock.

So a port may also declare what it carries, independently of how it travels: moment, length, zone. A moment is a point in time, a length is a span, and conflating them is the mistake the whole time family is built to avoid. 28 ports declare one.

It ranks a connection and never refuses one. Refusing is the coercion table's job, and it alone - pasting a timestamp into a plain text box is legal and stays legal. This only decides what to offer.

Which matters when you add a block onto another, because then nobody has said which ports to join. Both ends are scored together: ports that share a name find each other first, then ports that carry the same thing, then the source block's own declared main output, then how cleanly the types convert. Declaration order breaks the tie, which is all there used to be.

Scoring pairs rather than ends is the part that took a bug to learn. Choosing the output and the input separately is two defensible guesses that have never been introduced, and it is how a table of time zones ended up in a field expecting one time.

6A half-fed block is waiting, not broken

An empty block is not an error. An unwired JSON Query used to run compute on undefined and report "Unexpected end of JSON input", which blames you for a wire you simply have not drawn yet.

So a block is in one of three states. Ready, when every required input has a value. Waiting, when some do and some do not - compute does not run, and the card says what it is waiting for, by block name rather than by block id. Standalone, when nothing is wired and the block has its own way to get input: a QR Code's form, a Markdown editor, Superscript's palette.

That last distinction is why Case with nothing wired is correctly ok while JSON Query is waiting. One can feed itself from its params; the other has no way to.

Underneath all of it is one rule: absent, never empty. A param that has been cleared is removed, not stored as an empty string, because an empty string arrives downstream as something to parse. The same rule applies to a bode's name and to a block's note.

7The session is not the document

Everything in a bode file is the document. Nothing in it is a session. A photo you picked, a microphone you chose, a running timer, a clock's current tick - these are values a block owns only while it is open, and they are stripped on the way out. So the same bode opened twice is the same bode.

Stripping them is also the right meaning, not just the cheap option. A bode that strips EXIF or makes a QR code wants the file of whoever opens it, not a copy of the author's. A shared bode arrives asking for yours.

Which leads to a rule for anything driving bode from outside: some params are a capability request, not a value. A caller that cannot see a screen can never honestly produce an image's data - it comes from a device or a file picker. So an op that sets one on a block declaring needs: ['file'] or needs: ['permission'] is refused. Name it, never carry it.

The line is drawn at those two needs and not at every session value, because the distinction is real. A file or a device is something a caller cannot reach. An HTTP block's auth header and a clock's tick are also session-owned, but a caller *can* honestly supply them - a script reading a token out of its environment is the use case, not the abuse of one.

8Three vocabularies, because they make three different promises

A bode you can only drive with a mouse is a bode an agent, a paste, a test or a command line cannot drive at all. So everything the app can do is also a verb - and the verbs come in three kinds, not because three reads nicely but because each kind can promise something the others cannot.

OpsCommandsQueries
Changesthe documentthe sessionnothing
Undoablethe batch is one entryundo and redo ARE entriesn/a
All-or-nothingyesimpossiblen/a
Previewableghostablenothing to ghostn/a
Travels in a bodeyesnono

16 ops edit the document. They are a pure (Graph, Op[]) => Graph with no store and no React in scope, which is what lets the canvas, a paste, a model and a test share one path instead of each growing its own.

27 commands act on the session: what is selected, where the camera is, which bode is open, what a setting says. Each carries a cost - safe changes nothing you could want back, writes is recoverable, destructive cannot be undone.

14 queries read. An agent cannot operate what it cannot observe, and this is the half that was reachable only from inside the app for most of the project's life.

The dangerous verbs are deliberately *in* the language. Erasing every bode this browser holds is a named, costed verb rather than an omission, because a verb that is absent cannot be discovered - a caller that needs one goes hunting for a back door instead of reading a refusal.

9A batch is one edit, in two phases

Nine store calls would be nine history snapshots and nine debounce resets. So a batch is applied as one edit: one history entry, one autosave, one evaluation, whatever the op count. No transaction mechanism was needed for this - the commit that records an undo step was already the boundary; the work was to stop calling it per edit.

run(verbs) ──→ split ──→ ops:      validate all, apply as ONE batch (pure)
                         └─ commands: execute in order, after the ops landed

Ops run before commands regardless of the order you wrote them, because selecting three blocks names blocks the ops are about to create - and "build this, then show it to me" is the commonest batch there is.

Ops are all-or-nothing; commands cannot be. If any op is refused, nothing is applied - a batch is a proposal, and half a proposal is a bode nobody asked for. Commands are different in kind: you cannot un-fit a viewport, and by the time a later one is refused the earlier ones have already happened. So a refused command stops the rest and reports how far it got.

Two consequences fall out. Stepping through history cannot happen inside a batch that writes history - the batch is itself one entry, so undoing within it means undoing the thing being built. And a preview can only ghost the ops half, because a command has nothing to ghost.

Every refusal carries a path - ops[2].blockId - and every refusal is reported, not just the first. Fixing a hand-written batch one round-trip at a time is the thing the problems list exists to avoid.

10Where blocks go

Generated blocks cannot land in a pile, so placement is a primitive rather than a flourish. It does two jobs with the same arithmetic: find a free spot for one new block, and rank a whole graph into columns by depth.

Depth is how far a block sits from a source - one past the deepest thing feeding it. Parallel branches share a depth, which is what puts them in one column with the wire lengths even. This is deliberately not the same ordering the phone uses: a single column has to linearise, and breaks ties by position; a canvas wants the branches side by side.

Within a column, order comes from where things already are. That is what makes Tidy feel like straightening rather than reshuffling - you keep the arrangement you made, it just lines up.

A block wired to nothing gets its own row above the chain. Depth alone would put it in the source column, pushing the first block of the chain down while everything downstream stayed level, so the chain visibly bent around a block that was not part of it. Every template has one of these: the note explaining what you are looking at.

Layout runs without a browser - a template is built at module load - so it works from the manifest's size hints rather than measured ones. The canvas passes real measurements when it has them. Neither is the authority, which is why the size function is handed in rather than imported.

11A caller that reads has a problem a person does not

Evaluation is debounced so that typing never waits on the graph. A person never notices. A caller that applies ops and immediately asks what came out does nothing else - and would read the results from before its own edit.

So the results query can wait for the pending evaluation, and resolves at once when there is none. It also reports a sequence number, so a caller that did not wait can still tell whether what it is holding has moved. This is the difference between a usable API and a race nobody can see, and it only became visible once something could read.

What comes back is per-block: its status, what came out, what went in, the type each input arrived as, and the wire whose conversion failed if one did. "It has not run" and "it ran and produced nothing" are different answers, and only one of them means you should go and wire something.

12The boundary is enumerated, not intended

A vocabulary is worth nothing if a tenth way to add a block can appear beside it. So the places that write the graph directly are counted: a test reads the store's source, finds every write, and checks the list against one with a reason for each. A new one fails the build. A reason for a writer that no longer exists fails it too, so the list cannot rot into decoration.

Eight remain, and each is deliberately not a verb: the batch applier itself, React Flow's per-frame change protocol, selection, and the handful that replace a whole document rather than editing one. A second check closes the other door - nothing reaches past the actions into the store directly.

Both halves were verified by planting a bypass and watching them fail. A guard nobody has seen fail is a guard nobody should trust.

13Nothing is written down twice

A hand-maintained description of 16 ops and 9 port types is wrong within a release, and a caller that trusts it is worse off than one that had nothing. So the spec is generated from the code that implements it: each verb is an interface with a doc comment on every field, and the reference is read out of those definitions.

The example batch in the spec is applied at generation time, so a broken example cannot ship. Templates are op batches applied at module load, for the same reason. And a test asserts the generated reference covers every verb that exists, which catches the other failure mode: a new verb documented but not regenerated.

A JSON Schema checks shape. It cannot know that a block id is not a block, that one port type cannot reach another, or what a block is for - so the catalogue carries that, and it comes out of the same source as everything else.

Where to go next

The spec has every field and every verb with its arguments. The catalogue has every block, every legal wire and all three vocabularies in one file. The templates are working bodes you can open and take apart.