← Docs

The bode format

The reference: every field of a bode, every verb that can act on one, and what a reader accepts or refuses. Generated from the code that implements it, so it cannot drift.

Looking for how it all fits together rather than what each field is called? Theory of operation walks through the graph, the fingerprint, typed wires, the three vocabularies and the layout - in prose, in order.

A bode is one JSON object, saved as a .bode file. Everything in it is the document - nothing in it is a session, so values a block owns only while it is open (a clock's tick, a running timer, a microphone you picked) are stripped on the way out. The same bode opened twice is the same bode.

Version 1JSON SchemaThe op vocabularyExport or import any bode with ⌘K → Import / export.

What maps to what

A bode is blocks and the wires between them. Each block is one entry in blocks; each wire is one entry in edges, naming the block and the port at each end.

textparams.text: "1700000000"pos: { x: 0, y: 0 }texttimeparams: {}pos: { x: 360, y: 0 }timeblocks[0].id = "n1"blocks[1].id = "n2"edges[0]from: { node: "n1", port: "text" }to:   { node: "n2", port: "time" }blockId - which block it is
A block you can see
one entry in blocks, with its settings in params and where it sits in pos
A wire you can see
one entry in edges, naming a block and a port at each end
An input takes one wire
a second is refused - the evaluator reads a single value per port
An output feeds many
the same value can go to as many blocks as you like

The document

kind
'bode'

Always bode, so a loose file can be recognised without its name - and told apart from a bode-archive, which is all of them at once.

version
number

Bumped only when an old file would be read WRONGLY by new code - see DOC_VERSION. A newer number is read with a warning, not refused.

nameoptional
string

What the bode is called. Absent on an unnamed one rather than empty.

iconoptional
string

One emoji, shown beside the name.

blocks
GBlock[]

Every block, in no particular order - position lives on each block.

edges
GEdge[]

Every wire. An input takes at most one; an output feeds as many as you like.

varsoptional
BodeVars

The bode's variables - item 157. What the FILE says about each name a block can write as << name >>: a static value it carries, or nothing but a hint, which is the author asking for something they would not put in a file. A binding to a credential is never here; it is this browser's business, per bode.

A block

id
string

Unique within the document. Edges refer to it.

blockId
string

Which block this is, from the manifest - text, jwt-decode, timer.

params
Record<string, unknown>

The block's settings. Merged over its defaults on load, so a file may carry only what differs. Session-only params are stripped on the way out (§33), which is why a shared bode asks for YOUR clock rather than mine.

posoptional
{ x: number; y: number }

Canvas-only; deliberately excluded from the fingerprint so moving or resizing a block never invalidates its cached result.

sizeoptional
{ w: number; h?: number }

A height only exists once one has been imposed: a card that has merely been widened, as a template's note is, still grows to fit its content.

notesoptional
string

Whatever you wrote about this block, in Markdown. Part of the DOCUMENT, like the position - it travels in a share link and belongs in a version, because the note explaining why a regex looks like that is worth more than the regex. Deliberately outside params: it is not an input, compute must never see it, and putting it there would put it in the fingerprint and invalidate a cached result every keystroke.

chipoptional
boolean

Show this block as a CHIP: its name and its output, and none of its form. Item 13, and the reason the Display block no longer exists - every block already previews what it produced, so a card whose only job was to show somebody else's value was a node and a wire spent on a second copy of it. What Display actually offered was a bigger place to look with the controls out of the way, and that is available on every block now. Part of the DOCUMENT, like the position and the note: "show me this one as a result" is a property of that block in that bode, so a shared link arrives arranged the way it was sent. Excluded from the fingerprint - nothing about it changes what the block computes.

An edge

id
string

Unique within the document. Nothing else refers to it; it exists so a wire can be named in an error, and removed without ambiguity.

from
Wire

The output end: a block id and one of that block's output ports.

to
Wire

The input end. Types must be connectable (§21) - lossy is allowed and shown as such, impossible is refused.

What a reader checks

Refused outright
Not JSON, not an object, no kind: "bode", no version, or no blocks/edges array. Nothing else is fatal.
Everything narrower is partial
A bad block or wire is dropped and the rest opens. Half a bode you can look at beats a dialog saying no.
Every problem, not the first
Each is reported against a path like blocks[2].blockId. Fixing a hand-written file one reload at a time is miserable.
A newer version still opens
With a warning. Refusing would make every future field a breaking change for every older build.
Unknown fields are kept
A file from a newer build may carry something this one does not understand, and dropping it silently would corrupt a document by reading it.
Wires are checked like the mouse checks them
The port must exist, the types must be connectable (lossy is allowed, impossible is not), an input takes at most one wire, and nothing may form a loop - the evaluator walks a DAG.

An example

{
  "kind": "bode",
  "version": 1,
  "name": "Readable timestamp",
  "icon": "🦉",
  "blocks": [
    {
      "id": "n1",
      "blockId": "text",
      "params": {
        "text": "1700000000"
      },
      "pos": {
        "x": 0,
        "y": 0
      }
    },
    {
      "id": "n2",
      "blockId": "time",
      "params": {},
      "pos": {
        "x": 360,
        "y": 0
      }
    }
  ],
  "edges": [
    {
      "id": "e1",
      "from": {
        "block": "n1",
        "port": "text"
      },
      "to": {
        "block": "n2",
        "port": "time"
      }
    }
  ]
}

The op vocabulary

Nine things you can do to a bode, as data. A bode you can drive without a mouse needs a way to say “add these blocks, wire them, lay them out” - and the same vocabulary serves the canvas, a paste, a model and a test, which is what keeps any one of them from having privileges the others do not.

JSON SchemaThe commandsThe queriesEvery op carries op, naming which one it is.

ops ──→ validate ──→ preview ──→ apply
         │             │           └─ one undo entry, whatever the op count
         │             └─ summarised, Apply or Discard
         └─ against the manifest and the coercion table; refusals say why

add

Add a block.

Placement is the interesting part, and it is three policies rather than one: at if you know where, else beside connectFrom (using that block's real width, not a constant), else to the right of everything. Whichever it is, the result is nudged clear of anything already there - a caller that cannot see the canvas must not be able to drop a block on top of another one.

Refuses an unknown blockId, an id already in the graph, and a capability param (see refusedParams).

connectFrom is best-effort about the WIRE and strict about the request. A port that does not exist is a mistake and is refused; nothing on the new block accepting that type is a fact about the two blocks, and the block is added unwired - which is what both shells already do and the honest outcome rather than a refusal. A caller that REQUIRES the wire says add then connect, which refuses loudly.

blockId
string

Which block, from the manifest - text, jwt-decode, timer.

idoptional
string

The id to give it. Minted when absent; supply one when a later op in the same batch has to name this block before it exists.

atoptional
Pos

Where to put it, before collision avoidance.

connectFromoptional
Wire

Wire this output into the new block's first input it can legally reach, and place the block beside its source. The chain-building gesture: it is what ⌘K does from the selected block and what the phone's Add does from the end of the chain. Left unwired when nothing on the new block accepts the type.

paramsoptional
Record<string, unknown>

Params to set at birth, merged over the block's defaults like any other.

remove

Delete a block, and every wire touching it.

Refuses an id that is not in the graph. Both ends go together because a dangling wire is not a state the evaluator has - and undo restores both, since the snapshot is of the whole document.

id
string

The block to delete.

connect

Wire one output to one input.

Refuses a missing block or port, types that cannot connect at all (lossy connects and says so; impossible is refused), a loop, and - unless replace - an input that already has a wire.

from
Wire

The output end.

to
Wire

The input end.

replaceoptional
boolean

Take over an input that is already wired, dropping the old wire. Off by default, and the asymmetry is deliberate. Dragging onto an occupied port is an unambiguous instruction - you aimed at it - so the canvas passes this. A caller working from a description has no idea the port was taken, and silently discarding someone's wire on its behalf is the kind of edit you only notice later.

disconnect

Remove a wire, by its id or by the input it feeds.

Both, because both callers exist: the canvas has the edge in hand, and a caller reasoning about a bode knows "whatever is feeding this input" long before it knows an edge id.

Refuses when neither is given, or when nothing matches.

idoptional
string

The wire's own id.

tooptional
Wire

The input end instead - at most one wire can be there.

setParams

Change a block's settings.

A patch, merged over what is there; it does not replace the whole param object. Setting a key to undefined removes it, which is the §29 rule - a param is absent, never empty, because an empty string reaches downstream as something to parse.

Refuses an unknown block and any capability param (see refusedParams).

id
string

The block whose params to patch.

params
Record<string, unknown>

The keys to change. Everything else is left alone.

note

Write a note on a block, in Markdown.

Its own op rather than a setParams key, for the reason the note lives outside params in the first place: compute must never see it, and putting it in there would put it in the evaluator's fingerprint and invalidate a cached result on every keystroke. It is still part of the DOCUMENT - it travels in a share link and belongs in a version.

Refuses an unknown block. An empty string clears the note.

id
string

The block to annotate.

notes
string

The note, in Markdown. Empty clears it.

chip

Show a block as a chip, or as a card again - item 13.

A chip is the block's name and its output, with the form put away: what the Display block used to be, available on every block instead of requiring a special one. Its own op rather than a setParams key for the same reason as note: compute must never see it, and it is not an input - it is how the block is ARRANGED, which is the document's business and nobody else's.

Refuses an unknown block. on: false takes the chip off rather than storing one that says no - absent, never empty (§29).

id
string

The block to fold up.

on
boolean

true folds it to name and output; false opens the card again.

move

Put a block somewhere.

Position is excluded from the evaluator's fingerprint, so this recomputes nothing - but it is part of the document, so it is saved and it is undoable.

Refuses an unknown block.

id
string

The block to move.

to
Pos

Where to, exactly. No collision avoidance: a caller that said move meant that spot, and layout is the op that chooses spots.

resize

Give a block a size.

h is optional because a height only EXISTS once one has been imposed: a card that has merely been widened, as a template's note is, still grows to fit its content. Omitting it is how you hand a height back.

This op exists because #111's boundary audit found it missing. GBlock.size is part of the document and templates/index.ts already sets size: { w } by hand, but React Flow's dimensions change was the only thing that could write it - so "make that card wider" was unsayable by anything that is not a mouse.

Refuses an unknown block, and a width that is not a positive number.

id
string

The block to resize.

sizeoptional
{ w: number; h?: number }

The imposed size. Omit h to let the card grow to fit its content again, and omit size entirely to take the imposed size off altogether - which is the only way to undo a resize, and was unsayable until a UI wanted it.

duplicate

Copy blocks, with the wiring that makes the copy useful.

Incoming wires are copied, outgoing wires are not. Duplicating a block whose input was fed should give you a copy that is also fed - that is the whole point of duplicating mid-chain. Copying its OUTPUT wires would propose a second wire into inputs that already have one, which is refused anyway, so the rule is the only coherent one rather than a preference.

The copies move as a group, keeping the arrangement you made, and land below the originals rather than beside them: beside reads as a longer chain, below reads as a second copy.

Refuses an unknown id. An empty list is a no-op, not an error.

ids
string[]

The blocks to copy. Wires between any two of them come along.

asoptional
string[]

The ids to give the copies, one per entry in ids. Minted when absent, exactly like add's - and absent for the same reason it is usually absent there: you rarely care. Supply them when a later verb has to NAME a copy, which until this existed was impossible: you could duplicate a block and then had no way to refer to what you had made.

layout

Straighten the canvas: columns by depth in the DAG, sources on the left.

This is #112's Tidy, reachable as an op because generated blocks cannot be allowed to land in a pile. Never refuses - a graph is always layout-able, and an unknown id in ids is simply not there to move.

idsoptional
string[]

Lay out only these, leaving everything else where it is - Tidy on a selection. Absent means the whole bode.

atoptional
Pos

Where the top-left of the result goes. Absent means "where this lot already is", which is what Tidy wants: it straightens without moving your work across the canvas. A caller BUILDING a bode has no existing position to preserve and does want to say, which is how a template places its chain below its note - the one thing layout cannot derive, because how tall a paragraph renders needs a browser.

rename

Name the bode, or give it an icon.

An empty string CLEARS the field rather than storing one, because §29's "absent, never empty" applies to the document too: an empty name is not a name, and a reader would have to decide what to display for it.

Never refuses.

nameoptional
string

What to call it.

iconoptional
string

One emoji.

open

Replace the content with a document.

One op for four things that were four code paths: a template, core/demo.ts, a share link and an import are all "open this bode". It ignores the graph it is handed and returns the document's, which (Graph, Op[]) => Graph takes without a special case.

Validated by `readDocument` - the same reader a file goes through - so the document's own rules apply inside the op: a thing that is not a bode is refused, but a single bad block or wire is dropped and reported as a WARNING rather than failing the batch. Those are the file's problems, not the caller's, and half a bode you can look at beats a dialog saying no.

It does not touch the bode's identity - its id, its versions, its save state. That is openBode, which is a command.

document
unknown

A BodeDocument, or anything claiming to be one. Unparsed: the op runs the reader, so a caller cannot skip the validation by pre-parsing.

clear

Empty the bode, keeping its name and icon.

Expressible as one remove per block, and earns its own op only because the label and the notification belong to the gesture rather than to N deletions - "Cleared 9 blocks" is what a person needs to read in an undo notice.

Never refuses. Clearing an empty bode is a no-op, not an error.

setVar

Declare one of the bode's variables, or change what the FILE says about it - item 157.

A variable is a name a block writes as << name >>. What this op can set is the half that travels: a static value the bode carries, and a hint saying what somebody opening it should put there.

It cannot bind one to a credential, and that is not an omission. A binding lives in the browser, per bode, and is the one thing a bode that arrived from somewhere else must never be able to make - the same reason §33 refuses a caller a file param: a caller cannot honestly consent on your behalf. There is simply nothing here to bind with.

value: "" clears the static value and leaves the variable declared and unset, which is §29's "absent, never empty" applied to a table that travels.

name
string

Lowercase letters, digits, - and _.

valueoptional
string

What the file carries. Empty unsets it, leaving the question.

hintoptional
string

What to tell whoever opens this bode: "a token with repo:read".

removeVar

Forget a variable entirely. A block still naming it stops with "not set", which is the honest state rather than a silent empty string.

name
string

The commands

An op changes the document. A command changes the session - what is selected, where the camera is, which bode is open, what a setting says. An op batch is atomic and undoable; a command cannot be either, because you cannot un-fit a viewport. Ops say op, commands say do.

Every command carries a cost, so a caller sees a gate rather than discovering one. Every op is writes by construction, which is why only the commands carry one.

select safe

Select blocks.

The verb that looked pointless and is not. *"Select these three so the person can see what I mean"* is the preview step of the pipeline - a builder needs it before it needs anything clever. It also matters mechanically: ⌘K wires from whatever is selected.

Refuses an id that is not in the bode. An empty list clears the selection.

ids
string[]

The blocks to select. Empty selects nothing.

focus safe

Put the camera on one block.

The store cannot do this itself - the viewport belongs to React Flow, inside the canvas. So this records a REQUEST that the canvas answers, the same shape fitView and Save already use. A caller that is not on a canvas (the phone, a test, a prerender) simply has nobody listening, which is the correct outcome rather than an error.

Refuses an id that is not in the bode.

id
string

The block to centre on.

fieldoptional
boolean

Also put the text cursor in this block's first editable field - what arriving from a tool page does, so you can start typing.

fitView safe

Frame the whole bode. Never refuses; an empty bode has nothing to frame and that is not an error.

run external

Lift the run barrier and evaluate - #105.

A block that needs: ['network'] does not run just because something upstream changed; it holds its last value and reports stale. This is the only way past that, and it is one-shot: the permission is spent by the evaluation it triggers, so a later keystroke cannot ride through on it.

With no ids, every stale block runs - the canvas's "3 blocks are out of date · Run". With ids, only those, which is Run on one card.

Never refuses. Nothing stale is not an error, it is the ordinary state of a bode you have not edited, and a caller that ran it on a timer should not have to check first.

idsoptional
string[]

Which blocks to run. Absent means every stale one.

undo writes

Step back through history. Refuses when there is nothing to undo, and refused outright inside a batch that contains ops - the batch is itself one history entry, so undoing within it means undoing the thing being built.

redo writes

Step forward again. Refuses when there is nothing to redo, and in a batch containing ops, for the same reason as undo.

saveVersion writes

Save a named version of this bode.

Versions are explicit and separate from autosave: autosave answers "what was I doing?", a version answers "take me back to this".

labeloptional
string

What to call it. A timestamp stands in when absent.

noteoptional
string

Why you saved it.

restoreVersion writes

Put a saved version back. Refuses an id this bode has no version for.

id
string

The version to restore.

deleteVersion destructive

Forget a version. Refuses an unknown id. Undoable only in the sense that the version list itself is restorable for a few seconds.

id
string

The version to delete.

updateVersion writes

Rename a saved version, or change its note.

The inverse of the hole emptyTrash was: reachable from the Versions dialog and not from the vocabulary, so a caller could save and delete a version but not correct the name it gave one.

Refuses an id this bode has no version for. A blank label falls back to unnamed rather than storing whitespace (§29).

id
string

The version to change.

labeloptional
string

What to call it.

noteoptional
string

Why you saved it.

newBode writes

Start an empty bode, with its own id, versions and save state. The current one is autosaved first, so nothing is lost. Never refuses.

openBode writes

Open a saved bode. Refuses an id that is not in storage.

id
string

Which saved bode, from bodes().

openDocument writes

Open a document as a NEW bode.

The hole the §135 review found. The open OP replaces a bode's content and deliberately leaves its identity alone - same id, same versions, same save state. loadGraph resets all of that and validated nothing, which is how every caller that actually wanted "open this file" ended up bypassing the reader: a template, the example bode, a share link and an import all took the second door.

So this is the first door, and it runs `readDocument` like the op does. A caller cannot skip §110's validation by pre-parsing, which is exactly what JsonModal was doing.

Refuses anything that is not a bode. A single bad block or wire is dropped and reported as a warning, because that is the file's problem and the readable part still opens.

document
unknown

A BodeDocument, or anything claiming to be one. Unparsed on purpose.

draftoptional
boolean

Open it as a DRAFT - it works across a refresh without joining All bodes, which is what a template or a shared link should do until you keep it.

fromoptional
string

What it came from, shown on the draft banner: a template's name, a URL.

renameBode writes

Rename a saved bode.

One verb with a documented branch, not two verbs - which is what the §39 inventory asked for. Renaming the bode you have OPEN goes through the document and is undoable; renaming one you do not goes straight to storage and is not. The branch belongs here rather than in every caller, because a caller that has to know which case it is in will eventually get it wrong.

Refuses an id that is neither open nor in storage.

id
string

Which bode.

nameoptional
string

What to call it. Empty clears it back to untitled.

iconoptional
string

One emoji.

trashBode writes

Move a bode to the trash, where it stays recoverable. Refuses an id that is not in storage.

id
string

Which bode.

restoreBode writes

Take one back out of the trash. Refuses an id that is not in it.

id
string

Which bode.

deleteBode destructive

Delete a bode for good. Refuses nothing - an id that is already gone is the outcome you asked for.

id
string

Which bode.

emptyTrash destructive

Delete everything in the trash.

The one the §39 sweep found with no function at all - an inline loop in CanvasesModal, which is how a destructive action ends up with no name, no test and no way to call it from anywhere else.

keepBode writes

Turn the draft into a real bode in All bodes. Refuses when what is open is not a draft.

nameoptional
string

What to call it. Falls back to the draft's current name.

setSetting writes

Change a setting.

Settings are in the language because the first draft of §39 left them out as "a developer's A/B harness", and proxyUrl is the counterexample: a string that decides what network a bode can reach, sitting in the same object as background: 'dots'. Operational configuration was already mixed in with cosmetics, so the exclusion was drawn around the wrong thing.

Refuses an unknown key, and a value the setting does not allow - SETTING_SPEC is what makes the second one checkable rather than a cast.

key
string

Which setting, from SETTING_SPEC.

value
unknown

The new value. Checked against that setting's kind and choices.

setFlag writes

Switch a Labs flag. Refuses an unknown key, and a variant that flag does not offer.

key
string

The flag, from flags().

variant
string

Which variant.

resetFlags destructive

Put every flag back to its default. destructive, because it discards choices with no history entry to undo.

wipeEverything destructive

Erase every bode, version, draft and setting this browser holds.

In the language precisely BECAUSE it is the most dangerous thing here: an absent verb cannot be discovered, and a caller that needs to reset a browser would otherwise go looking for localStorage itself.

setCredential writes

Add or replace a credential in this browser - items 103 and 157.

In the language because the Builder has to be able to finish the job: a bode it writes that calls an API needs somewhere for the key to go, and a caller that cannot put one there would hand back a bode that cannot run and no way to fix it but a dialog it cannot open.

It is a command, not an op, and that is the whole shape of it. Ops edit the document and travel with it; this touches the browser, is destructive because it silently replaces a key of the same name, and is in nothing that is ever saved, shared or exported.

No query ever returns a value, so a caller can write one and never read one.

name
string

Lowercase letters, digits, - and _.

value
string

The key itself.

removeCredential destructive

Forget a credential. Every bode bound to it stops, saying which key it wanted - which is the honest outcome of revoking something.

name
string

bindVar writes

Point one of THIS bode's variables at one of this browser's credentials.

The one gesture that is deliberately not an op: a binding is not in the document - a document that could carry one could name a stranger's keys - so it is a command, and it applies to the bode that is open.

name
string

The variable. It does not have to exist yet; binding declares it.

credentialoptional
string

The credential to answer it with, or omitted to take the answer back.

setLocalVar writes

Answer one of this bode's variables with a value kept in THIS BROWSER.

The unshared half of a variable: setVar writes what the file carries, and this writes what it does not. A caller filling in a bode somebody else wrote wants this one, because the alternative publishes the answer.

name
string
valueoptional
string

Omitted clears it, leaving whatever the file says.

The queries

Reading. Not verbs in a batch - nothing to order, nothing to roll back, no history entry - so they are asked one at a time rather than sorted into a phase. Every query is safe by construction: it changes nothing. Each carries ask.

results

What every block computed: its status, what came out, what went in, and what went wrong.

The most important query there is. It is the only way a caller learns whether the thing it just built actually computes, or what came out of it. Without this an agent wires blind and reports a success it never checked.

Use settle after an edit. Evaluation is debounced by 120ms so that typing never waits on the graph, which means a caller that applies ops and asks immediately is reading the results from BEFORE its own edit. settle waits for the pending evaluation instead, and resolves at once when there is none.

idsoptional
string[]

Only these blocks. Absent means every one.

settleoptional
boolean

Wait for the pending evaluation to finish first.

document

The open bode as a BodeDocument - #110's writer, as a read. Session-only params are stripped, exactly as they are on the way to a file.

shareUrl

A link that carries the whole bode in its fragment.

Side-effect-free by design - the share dialog rebuilds it on every keystroke - which is precisely what makes this a query rather than a command.

Answers with the payload always and the URL only where there is one: a caller outside a browser has no origin to build a link against, and the payload is the part that carries the bode.

passwordoptional
string

Encrypt the payload. Without one the bode travels in the clear, readable by anyone holding the link.

selection

Which blocks and wires are selected. The View row's read gap, which is what made select look pointless: a caller could set it and never see it.

viewport

Where the camera is, and whether a bode has been framed yet. Answered by the canvas; a caller with no canvas gets null, which is the truth rather than a zero that looks like a position.

bodes

Every saved bode, newest first - id, name, icon, block count, when it changed. Trashed ones are excluded; trash is its own query.

searchoptional
string

Filter by name, the way the Bodes dialog does.

trash

What is in the trash, most recently binned first.

versions

The open bode's saved versions, newest first.

storage

How much room is left.

The thing a caller has to know BEFORE a save, because saveCanvas answers a full localStorage by returning false - and a caller that never asked has no way to tell a refused write from a successful one.

settings

Every setting, its current value, and what it accepts - so a caller can discover background's three choices rather than guess at them.

flags

Every Labs flag, its variants, its current value, and whether a ?flag= override is masking the stored one.

vars

The bode's variables: what each one is, and whether it would resolve - item 157.

Every name the blocks reference plus anything the file declares, each with its source - shared (a value the file carries), local (a value this browser holds), bound (a credential answers it) or unset - and whether it would resolve right now. The names of this browser's credentials come with it, so a caller can offer one; no value is ever returned, by this or by any other verb.

It is the query that answers "can this bode run, and if not, what is missing" - which is the question a caller actually has.

catalogue

Everything a caller that is not a person needs - item 134.

Every block with its ports, every port type with the coercion table between them, the templates, and all three vocabularies with their costs. It turned out to be a query rather than a separate artefact, which is the whole of why #134 dissolved into #135.

Loaded on demand: it is generated data measured in tens of kilobytes, and a caller that never asks must not pay for it. Hence store.ask being async.

check

Run the bode against sample values, and say what breaks - item 159.

The gap this fills. A bode somebody has just built is EMPTY: the sources are blank on purpose, because the data is yours. So results immediately after a build says "waiting" for every block, and a caller that checked its work would be told everything is fine right up until you paste something in - which is exactly how a JSON Query with a guessed path reached a person with no match for $.email in it.

So: hand it the sample, get back what fails. The sample is applied to a COPY, evaluated by a throwaway evaluator, and thrown away - nothing is written to the document, nothing appears on the canvas, and nothing is in the undo history. It is a read, which is why it is a query.

It cannot be used to run what you are not allowed to run. A costly block stays behind the run barrier (#105) and a block carrying code nobody has allowed stays behind the consent gate (§41) - both are reported as held rather than quietly executed, because a dry run is not a person pressing a button.

withoptional
Record<string, Record<string, unknown>>

Sample params, by block id - { "src": { "value": "[{…}]" } }. The same rules an op obeys: a block's session-only params are refused (§33), because a caller cannot honestly produce somebody's photo even for a rehearsal.

idsoptional
string[]

Only report on these blocks. Absent means all of them.

For a machine

/bode.schema.json
A bode document.
/bode.ops.json
A verb batch - every op and every command, with its cost.
/bode.catalogue.json
Everything else: every block with its ports and worked examples, which wires are legal and how lossy each is, the templates, and all three vocabularies. A JSON Schema checks shape; this carries meaning.

What a batch guarantees

Ops are data, not methods
A pure (Graph, Op[]) => Graph with no store and no React in scope. That is what lets the canvas, a paste, a model, a test and a CLI share one path instead of each growing its own.
All or nothing
If any op is refused, NOTHING is applied. This is where a batch differs from a file on purpose: a file is a document you already have, so opening the readable part is a kindness; a batch is a proposal, and half a proposal is a bode nobody asked for.
Every problem, not the first
Each is reported against a path like ops[2].blockId, and later ops are still checked against the graph the earlier ones would have produced.
A batch is one undo entry
Whatever the op count. commit() was already the batch boundary, so this needs no transaction mechanism - one commit, one save, one evaluation.
Wires are checked by one function
checkWire - the same call a file goes through. A port must exist, the types must be connectable (lossy is allowed, impossible is not), an input takes at most one wire, and nothing may form a loop.
An op may not supply a capability
A block that declares needs: ["file"] or needs: ["permission"] gets its session params from a device or a file picker. A caller cannot honestly produce one, so setting it is refused: name it, never carry it.
Running is not an op
Nothing here runs, re-runs or cancels. Those act on the evaluator rather than the graph, and they arrive with the run barrier.

An example batch

It describes itself as “Added 2 blocks, connected 1 wire, tidied the canvas, renamed the bode”.

[
  {
    "op": "add",
    "blockId": "text",
    "id": "a",
    "params": {
      "value": "hello"
    }
  },
  {
    "op": "add",
    "blockId": "base64",
    "id": "b"
  },
  {
    "op": "connect",
    "from": {
      "block": "a",
      "port": "text"
    },
    "to": {
      "block": "b",
      "port": "text"
    }
  },
  {
    "op": "layout"
  },
  {
    "op": "rename",
    "name": "Encoded",
    "icon": "🔐"
  }
]