The weft book

Weft is a language and a runtime for programs that combine AI models, people and tools.

Running an agent puts one model in charge of the whole job, and you wait while it works. Weft goes the other way. You break the job into a graph of small pieces, called nodes. A node can run a model, open a webhook, ask a person, call an API or keep a database. Each one sees only what you wired to it, and the graph does the coordinating. The compiler checks every connection before the run, and every value that passes between nodes is written down where you can read it afterwards.

Let Tangle show you

Two things are yours to do, and both are quick. Install weft, which is mostly waiting, and decide which services you want weft to keep keys for. Then make a project:

weft new hello --assistant claude-code --remember

That puts Tangle in the project, and --remember makes Claude Code the default so your next weft new needs no flag. Tangle is our weft specialist: it knows the language, reads the catalog on your disk before it wires anything, writes any node you are missing, and will build you a web frontend if you ask for one. It also tests what it builds. It runs one piece at a time on a real input, looks at what came out, and goes back to fix the node that got it wrong. You can hand it a job and find the program working when you come back.

Open the project in your assistant and ask it to show you around, or just say what you want built. It walks you through everything below, pointing at your own screen while it does. You do not need the rest of this book.

Or read it yourself

If you would rather build with your own hands, or you just prefer reading, two sections get you to the same place.

Set it up gets you to a running program: install, your first project, the three things in a weft project that are alive on their own clocks, and how to talk to Tangle.

Build something real is where you take the wheel: editing the graph with a mouse, running one part of it on its own, connecting an account, giving your machine an address the internet can reach, and putting a person in the middle of a run.

After that the book stops being a path and becomes a reference. The language, writing your own nodes, connections, and what the runtime is doing underneath. Read a section when you need it.

The last part, why it is shaped this way, is the thinking behind the design: what weft handles for you, and how we decide what belongs in the language.

If something here is wrong

These docs are AI-written and the code moves fast, so mistakes get through. If you find one, or an explanation you cannot follow, tell us or come and say so on Discord. You do not need the correction worked out before you raise it.

Install

This gets you a weft runtime on your own machine, the weft command, and the graph editor in VS Code. It is mostly waiting, so keep reading while it runs.

Docker has to be there first. weft’s runtime is a program on your machine. Its database, its file store and the infrastructure your programs ask for (a database, a model server) run in Docker containers next to it, and your programs themselves run as plain processes, each in its project’s folder. If Docker is missing, the installer stops and prints the link to install it.

You also need Rust whenever weft has to compile something on your machine: a project with nodes of its own or with a standard node you edited (under nodes/base_catalog/), a project you build with --referenced, a live node test, and ./setup.sh --rebuild. The install itself needs it on a branch’s install, which always builds the CLI and the standard worker from source. The default install needs it whenever it cannot use what CI published for your exact checkout: you have local changes, CI has not finished building the commit you just pulled, you passed --debug or --from-source, or the release has nothing for your kind of machine. The installer says which one it hit, then compiles what it could not download. For which projects compile and which share the standard worker, go and read the worker.

The installer is a bash script, so on Windows run it inside WSL.

Install

curl -fsSL https://weft.weavemind.ai/install.sh | bash

It downloads weft into ~/weft and runs the installer from there. To put it somewhere else, start the line with WEFT_DIR=<folder>. Leave that folder where it is afterwards: weft reads its standard library and its assistant templates from it.

On a fresh machine the installer asks no questions: the first run starts the database and pulls images, then sets the runtime up as a service of your user (systemd on Linux, launchd on macOS), so it comes back on its own after a reboot. Each long step shows a spinner with the last line it printed; if you want to see everything as it happens, add bash -s -- --verbose in place of the final bash.

Put your keys in

Fill in the services you expect to use often, and leave the rest alone. We recommend at least OpenRouter, because a single key there reaches most models.

A service you set up here becomes one click forever after: a node that calls it picks the key up on its own, and your AI assistant can wire one in without stopping to ask you for anything. A service you skip asks you for a credential the first time you need it, which is fine for the ones you touch once.

cd ~/weft
cp access-apps.example.json access-apps.json

Open it and edit in place, leaving the services you are not using on their placeholder values. weft ignores an entry it cannot use, and reads the file each time it needs a key, so a change takes effect at once.

  "openrouter": [{
    "kind": "api_key",
    "label": "Runtime key",
    "key": "sk-or-REPLACE_WITH_YOUR_KEY"
  }],

The file also ships entries for Slack, Google, Notion, Airtable, fal, ElevenLabs, Exa, Firecrawl and Mistral. Most of them just need a key pasted in. Slack and Google want you to register an application with that provider first, which is a longer job, so do those only if they are services you will live in. For the whole format, go and read the apps file.

Check it came up

weft daemon status

A healthy answer counts your projects:

weft: running at http://127.0.0.1:14111 (install 'default'); 0 project(s)
public address: closed

closed there is the normal state and not a fault. It means nothing of yours is reachable from the internet, which is what you want until you need a public address.

If it says weft: unreachable at ..., run weft daemon logs to see how the runtime’s log ends (the line also names the log file), then run the install line again and read the last block it prints. If that block has scrolled away, every run writes the same thing to ~/.local/share/weft/setup-runs.log.

Two things that can go differently.

If weft is not found, the installer warned that its directory is not on your PATH and printed an export PATH=... line. Put that line in your shell’s startup file (~/.bashrc for bash, ~/.zshrc for zsh) and open a new terminal.

If VS Code was closed, or code is not on your PATH, the installer built the editor extension but could not install it, and printed the exact code --install-extension ... command to finish the job. Without the extension everything the weft command does still works; you just will not see the graph.

The installer also needs Rust when it cannot download a prebuilt weft for your machine, and Node 22.12 or newer with pnpm when it cannot download a prebuilt editor extension. It tells you which, up front, and stops rather than half-installing.

Add the browser extension

When a program stops to ask a person something, the question shows up in a browser extension called Weft tasks. Install it now, from Firefox Add-ons or the Chrome Web Store, and close it again. It has nothing to show you yet. You connect it to your runtime in putting a person in the loop.

Keep your projects elsewhere

Your projects do not belong inside ~/weft. Go wherever you keep code:

cd ~/code

Then build your first program.

When you come back to this page

To change your keys, edit ~/weft/access-apps.json; the change takes effect at once (the apps file).

To update, run weft maintenance on first, which takes down every trigger that is on and stops your programs’ infrastructure, then run the install line again, then weft maintenance off, which builds those projects again on the new weft and brings back exactly what on took down. The install line updates ~/weft and runs the installer, the same as git pull and ./setup.sh in that folder, and the installer refuses to replace the running weft while something is on. Your projects and their history stay where they are. Before you do, check the changelog for anything that needs you. For what each step does, go and read updating weft.

If something in a project does not come back with weft maintenance off, everything else is back anyway, and off says what went wrong. If the message says the project’s copy of the standard nodes is older than this weft, run weft catalog update in that folder (it replaces nodes/base_catalog/, so any edits you made in there are lost); otherwise fix what it says. Then run weft resync there, which builds the project and brings back what the update took down.

If you installed weft before it stopped running on Kubernetes, that update is the exception: its database cannot come along. ./setup.sh finds the old install and asks before wiping it. The wipe deletes the old cluster, your run history, versions and stored connections, and every container and image weft made, along with every named install on the machine (the question lists them). Your project folders stay, and weft run registers them again. If ./setup.sh has no terminal to ask on, run scripts/scrub-old-install.sh yourself first.

If your install’s database was built before executions were renamed runs, that update starts it over too. ./setup.sh asks before wiping that one install’s database: its run history, versions and stored connections go, and so does everything only that database gave a meaning to (the files the install stored, and the workers and infra of its projects). Your project folders, the install’s settings and every other install stay. Without a terminal to ask on, run ./setup.sh --yes.

To remove it, run ./setup.sh --uninstall in ~/weft. It stops the runtime and removes the CLI and the editor extension. Your database, stored connections and your programs’ infrastructure stay, so a later ./setup.sh brings everything back. Adding --purge deletes all of that too, your programs’ own databases included.

Your first program

Making a project takes one command, and it has one choice in it: which AI assistant you use. If you run weft new hello with no flag, weft asks you, listing the assistants it found on your machine first. Or pass --assistant with your row from this table. Either way weft copies Tangle into the project. Tangle is a persona that teaches your assistant the language, and it reads the catalog on your disk rather than trusting what it remembers.

If weft is run from a script or by an AI agent, there is nobody to ask, so it stops and lists these values: pass one. If you use more than one assistant, pass --assistant once for each. When weft asks, it also asks whether to keep your answer for later projects. A flag is for this project only, so if you want your next weft new to install the same one with no flag, add --remember, as here:

weft new hello --assistant claude-code --remember
cd hello
weft run

weft run says it is building, then prints the project’s name and id, then the run’s id and how many nodes it runs, then a line for every node as it starts and finishes, then a tick:

building hello
registered hello (3f2a1c4e-9b81-4d0a-8e55-7c2f1a6b30de)
started run 9b81d0a2-4e17-4a33-bc90-51d8e2f4a7c1 on version a1b2c3d4
2 nodes
→ started run=9b81d0a2 entry=greeting
  …
✓ completed run=9b81d0a2

hello uses only the standard library’s nodes, so on your machine it runs the worker program weft ships ready-made (the standard worker), and nothing compiles. Once a project has nodes of its own, or infrastructure, its build prints two lines for each worker it compiles and each infrastructure image it builds, indented under the rest:

  building <image> as <build>; its log: <url>
  built <image> in about <time>

The ; its log: <url> part shows only when the build has a log to point at.

That long id after started run is the run’s id, and it is how you point at this one run later. Everything that reads a run takes it, and the first eight characters are enough as long as they name only one.

If weft is not found, open a new terminal; the installer’s PATH line only takes effect in a fresh one. If the run stops saying it cannot reach the runtime, run weft daemon status and go back to Install.

See it as a graph

Open the hello folder in VS Code, click the Weft icon in the bar down the left edge, and click your project under Projects. The source opens on the left and the graph opens beside it. (If you opened src/main.weft yourself, click Open Graph to the Side in the file’s title bar.)

Type in either pane and the other updates.

This is what weft new wrote, and what you just ran:

greeting = Text { value: "Hello, World!" }
out = Debug { data: greeting.value }

Two boxes and an arrow. A box is a node. The dots down its left edge are what it takes in, the dots down its right edge are what it sends out, and each dot is coloured by the kind of value it carries, so two dots of the same colour fit together.

The arrow is greeting.value sitting where out’s data input goes. Writing a source and a port where a value belongs is how you connect two nodes, and it is the only wiring syntax there is.

While a run is going, each box glows: amber while it works, cyan while it waits for something, grey while it is paused only because its run paused, green when it finished, red when it failed. Click the magnifying glass on a box to see exactly what went in and what came out.

For adding a box and drawing an arrow yourself, go and read working in the graph.

What weft new made

Two more folders turn up later rather than now: layouts/, the first time you drag a box, and assets/, when something needs a prompt or a script kept in a file of its own.

weft new also runs git init and writes a .gitignore. Tangle’s files are ordinary project files, so they commit with the rest and anyone who clones your project gets Tangle without installing weft.

Next, the three lifecycles: what starts on its own and what does not.

The three lifecycles

Three things in a weft project are alive on their own clocks. Infrastructure and triggers start only when you (or your program) start them, and runs also start when a trigger fires or a caller arrives. The one exception: if infrastructure stops or breaks, the triggers that read it go down with it, and weft turns them back on by itself once it runs again (unless the node’s own health rules say otherwise).

Hitting Run never starts your database and never puts your webhooks live.

Your hello program has neither of the first two. It is two boxes and no listening, so weft run is the whole story until you build something that talks to the world.

Why they are separate

Infrastructure costs money while it runs, so weft will not start a container because you clicked something that did not mention one. If you run a program whose containers are down, it refuses up front and names them:

infra not running for: pg. Run `weft infra start` first.

Activating reaches out to other people’s systems. A trigger that waits for Slack messages registers a subscription with Slack during activation. A trigger holding a socket open dials it there and then. That is a real thing happening in somebody else’s account, which is why it is a separate decision from running your program once.

It also has a consequence you will meet: activation freezes the trigger’s inputs, because those values went to the provider and the provider is holding them. Edit one afterwards and your live listener carries on with what it registered, until you run weft resync.

A run can wait as long as it needs. It ends completed, failed or cancelled, or it parks at waiting_for_input while a node waits on a person or a service. Parking costs nothing: weft lets the run’s worker shut down, and a new worker picks the run back up when the answer lands, however many days later. Once everything in the run waits, the worker first stays up a few seconds (the trigger’s pauseAfterSecs, 10 unless you set it), so an answer that comes quickly carries the run on right there, before it parks. Otherwise the worker stays up only while the run cannot pause: a caller is still on the line, or the trigger has recorded off. Such a run holds the wait in its worker instead. Without a caller, if nothing moves in the run for its trigger’s holdSecs (60 seconds unless you set it), the waiting node fails; while a caller is on the line, the wait holds for as long as the caller stays, unless holdSecs is 0, which fails it at once.

The rest

For every verb, what each status means, the difference between a run that is waiting and one that is stuck, and which command to run after you edit something, go and read starting and stopping things.

Next, talk to Tangle and have it build you something with all three.

Talking to Tangle

Tangle is the weft expert that weft new --assistant copied into your project. Open the project in your assistant (the last lines weft new printed are the command that does it) and it is already there. Describe what you want in plain words and it builds it. You do not have to learn this language.

Say what it should do, not how

I want a WhatsApp bot I can forward voice notes to, and it replies with what was said in the audio. If I send it text, it just ignores it.

Tangle turns that into a graph and tells you the shape in a sentence or two before it builds anything. Say so then if the shape is wrong.

Notice what you did not say. Not which model transcribes the audio, not how the bot receives a message, and not how to tell a voice note from a text. That last clause, the one about ignoring text, is a branch in the finished graph.

What it does without being asked

It looks things up rather than remembering. The catalog on your disk is the truth, and Tangle reads a node’s real inputs and outputs before wiring it. The language moves fast, so anything the model remembers is probably stale.

It writes missing nodes. A node’s own logic is Rust, and if nothing in the catalog does what you need, Tangle designs the node’s inputs and outputs and hands it to a helper agent that writes that Rust.

It writes the prompts. When a model’s answer decides what happens next, Tangle hands that prompt to a helper that does nothing but write prompts, rather than typing one out as it goes.

It builds you a frontend. Ask for a page, an app or a site and Tangle puts one in front/, talking to your program through the program’s own HTTP routes. The default stack is SvelteKit, PostgreSQL, BetterAuth and shadcn-svelte, and if you name a different one, yours wins.

It tests as it goes. Tangle runs one piece of the program on its own, with values it makes up or a real input you gave it. It reads what came out, fixes the node, then runs only what changed. When a case comes out right, Tangle freezes it, and after a later change it runs that case again and reads what moved. You do not have to be there for any of that.

It offers guard rails on risky programs. If strangers can post into your program, or it sends, deletes or spends money on its own, Tangle names the protections that slow things down (a check, a gate, a person who has to approve) and asks you before it builds. When the program is finished, it attacks it before handing it over.

Give it one real case

Paste in a real input: an actual email, an actual message. Then read what came out, and when it is wrong, say what is wrong with it rather than restating the goal.

This email is asking for a replacement, but the extracted request says the customer wants a refund. Fix the prompt for that node.

Tangle builds one stage, runs it on your case, and shows you the result before writing the next one. For the longer version of that habit, go and read Sequential Diffusion Programming.

When you want to do it yourself

The .weft file is the source, and the graph edits that same file. For every command, go and read the CLI.

That is the first ten minutes. Next, work in the graph with your own hands.

Working in the graph

Everything here works with the mouse. Whatever you change on the canvas is written into your .weft file, so the two never disagree. The one exception is where a box sits: positions are kept in layouts/, beside your source.

Getting around

Scroll to move around. Drag empty canvas to move around faster. Zoom is the + and - buttons at the bottom left, with Fit View beside them for when you drag something into the distance and lose it. Scrolling does not zoom, on purpose, so a stray trackpad gesture cannot throw your whole graph off screen.

Hold Shift and drag to select several boxes at once.

Add a node

Press Ctrl+P (Cmd+P on a Mac) and search. Right-clicking empty canvas and picking Add Node… opens the same list.

The list holds every node your project knows about, and Group and Loop are in there too.

It also holds the plain actions, so you can find them without remembering a chord: Undo, Redo, Duplicate Selected, Delete Selected, Select All Nodes, Fit View, and Auto Organize Layout, which tidies the whole canvas.

If you already know what should come next, drag out of a dot and let go over empty canvas. The list opens, and the node you pick arrives with the arrow already drawn. One Ctrl+Z takes away both.

If the text of the file changes outside the graph (you type in the code tab, or an AI writes the file), the graph forgets its undo history, because what it remembered no longer matches the text. Undo those earlier graph edits in the text editor instead. The graph never writes over a change made to the text.

Connect two nodes

Drag from a dot on one box’s right edge to a dot on another box’s left edge. The line takes the colour of the dot it started from.

Three things will refuse the drop, and each tells you which:

• The types do not fit. Same colour is the quick check. The full rules are in Types.
• The two boxes are in different groups. A value crossing that line has to go through the group’s own dots. That is what a group is for.
• The input already has a value written into it. You get '<port>' is driven by a config assignment; unset it first to drive it with an edge. Clear the field, then draw the arrow.

Near the top of each node’s right edge, set apart from its output ports, there is a small red circle with a ! in it. That is _error, where the node’s failure comes out, and you drag a wire out of it as you would from any output. While nothing is wired to it, it is an outline and a failure stops the run. Once a wire leaves it, it fills in red, and a failure goes down that wire instead. For which failures go there, go and read when a node fails.

To remove an arrow, grab it near one end and drop it on empty canvas.

To take one field out of a value instead of the whole thing, right-click the arrow. You get the keys inside it with their types, and clicking one narrows the arrow to that key. Up one level goes back and Read the whole value undoes it.

Values written by metadata ports

A metadata port is a value fixed in the program, which the compiler copies into every input the code wires from it, before anything runs. For what metadata ports are for, go and read metadata ports.

The graph draws neither the ports nor the wires from them: both are written in the code (tools.search = search.tool, or a value gathered from several, self.tools = [...screen.tools, pause.tool]). What it shows is where each value comes from, and it lets you follow it:

• An input a metadata port fills shows the value, read-only, with a link such as from calls.tools beside its name. Click it and the editor takes you to that box, opening the groups it sits in.
• A group’s metadata ports show in the Config strip at the top of the open group. A value written out in full is a field you can edit there. A value gathered from others is read-only, written the way the code writes it, with each port it names as a link: follow the links down until you reach the box that writes the text itself.

Change what a node does

The small arrow in a box’s header opens its body, where its fields are: text boxes, dropdowns, tickboxes, code editors, file pickers. A field fed by an arrow hides itself, because the arrow is now the source of that value.

Under the inputs there is a + input button, and output + under the outputs. A port you add with no type takes its type from what you wire to it. If you want to set one yourself, right-click the new dot and pick the Type: row.

That same right-click menu makes an input required or optional, removes it, or puts a catalog port back the way it was.

Double-click a box’s name to rename it. Right-click a box for Duplicate, Delete and Tags….

On an infra node, the same menu has One per instance: each instance of your program then gets its own copy of it, and it shows a per instance badge. Share across instances takes the mark off.

If you want each instance to get its own value for a field (an account, a spreadsheet, a schedule), click the ⧉ button beside the field’s name, or right-click the field and pick Let each instance fill this (the same entry is on the right-click menu of the field’s input port). The field then shows Filled per instance instead of a control, and the node a filled per instance badge. If you had already written a value, an instance that gets none gets that one. Click ⧉ again, or pick Stop letting each instance fill this, and that value becomes the one value for everyone again, or the field goes back to empty if there was none. A field with a wire into it offers neither, because its value comes from the wire.

A box that reads from a per-instance node or an instance-filled field runs once for each instance too, and shows a dashed per instance (follows) badge. For what all of this means, go and read programs with instances.

Run part of the graph

Select the boxes whose answers you want (click one, or hold Shift and drag around several). The selection bar appears at the bottom center of the canvas with a big RUN 2 TARGETS button (RUN 1 TARGET if you picked one box). Click it, or press Ctrl+Enter, and those boxes run together with everything they need. That is the same run as:

weft run --target dailyReport --target weeklyReport

To work out what a box needs, weft follows the wires back up from it and stops at any trigger. That trigger does not fire in this run, so a box only a trigger feeds is skipped. If you want that box to run, fire the trigger with a made-up event from the CLI (weft run --fire). A box that two branches share does not drag the other branch in. If the box sits inside a group, only the boxes of that group it needs run, plus whatever feeds the switch that decides whether the group runs at all (its _should_flow or _should_not_flow). If weft reaches a loop on the way, the whole loop comes along. A box inside a loop needs what the loop hands its body, so picked on its own it reaches the loop’s start without its end, and Run stays grey saying so. If you want to run part of a loop’s body, start the run inside it from the command line (weft run --from ... --target ..., see running part of a loop’s body).

Triggers and infra have no Run button: select one and the bar offers its own buttons instead (Turn on, Turn off, Resync for a trigger; Start, Stop, Upgrade, Terminate for infra; covered below). If you select them together with other boxes, RUN N TARGETS counts and runs the other boxes. Pressing Ctrl+Enter with only triggers or infra selected tells you Run leaves them out.

While weft works out what the selection needs, the button is greyed out and says Checking what this run needs... on hover. If the run cannot start, the button stays grey and its tooltip gives weft’s reason: the refusal weft run --check prints, or the infra the run reads that is not running (Start db first: this run reads it, and it is not running.). Several boxes selected are one run, so one blocked box blocks it: the tooltip names each blocked box with its reason, and the boxes that could run on their own.

If you want the whole program, open the Weft icon in the side strip and click Run Project on the project’s row. That is a plain weft run.

The editor has no button for starting partway in with values you supply, running one group on its own, firing a trigger with a made-up event, running a saved example (examples/*.json) or reusing what did not change since the last run. For those, use the CLI: --from, --group, --fire, --seed, or an example’s name after weft run. For the rules behind them, go and read versions, seeds and frozen examples.

Watch it go

The status bar, at the very bottom of the canvas, is the same bar as the selection bar above: what is happening now comes first, then what the selected boxes offer. With nothing selected and nothing going on, it is not drawn (the eye buttons that show only the trigger or the infra subgraph stay). While the run on the graph is going, it shows Stop and how far the run got (run 3f2a... 4/9 nodes). Which run that is depends on the toggle in look at an older run. The bar also shows work started elsewhere: an infra start typed in a terminal, or asked for by Tangle, shows as Starting infra…, an activation as Turning triggers on…, a build as Building…. If that work can still be cancelled, the label ends in (Cancel), and clicking the label cancels it.

If a command fails, a red banner sits above the bar with the error. Click it for the whole message, and the × to dismiss it. A dark line above the bar shows the last thing the command printed, while it runs and, if it failed, for as long as the banner is up. Clicking it shows everything it printed.

Each box gets a glow and a small mark:

Click the magnifying glass in a box’s header, Inspect run, for what went in, what came out, how long it took and what it cost. A failed box shows its error there. A skipped box says why in words, such as its _should_flow said no or the required input 'x' closed, and you follow the arrows backwards from there to find the node that decided. A bus’s messages end with * the bus closed here, or with * the bus failed here: and the reason when it broke off (go and read how a bus ends). If a node changed a stored file in place (added a turn to a conversation, say), its panel lists each change under Files edited: the file, the versions it moved between, and the lines added and removed.

A box that ran several times, which happens inside a loop, gets a ‹ 2/5 › in its header to step through the firings.

Look at an older run

The toggle at the top left decides which run the graph shows. Hover any of its three parts to see what it does:

• Following puts every run that starts on the graph. It is the default, and clicking Run in the editor always comes back to it.
• Locked keeps the graph on the run it shows, so you can read it while others start.
• Off takes the run away and leaves just the program.

While locked or off, runs that start are counted in a button beside the toggle, like 2 new runs · Follow, and clicking it shows the newest and follows again. A run started from a terminal, yours or an assistant’s, never changes the mode. Each project remembers whether you left it following.

For a run from yesterday, click the Weft icon in the side strip. Runs lists every run of the project you last opened, newest first, and each row has View in Graph, which puts that run back on the canvas with its values in place and locks the toggle onto it. A replayed run looks exactly like a live one.

If your project deploys to a cloud install, the switch at the top right shows the graph as that install runs it. For how it works, go and read Look at prod from the editor.

Turn triggers and infra on and off

Select a trigger or an infra node, or several (with the graph focused, Ctrl+P opens its list, and Select All Triggers there picks every trigger). The selection bar then offers what each can do right now, with a count when a button covers more than one of the selected nodes: Turn on, Turn off and Resync for triggers, Start, Stop, Terminate and Upgrade for infra. These are weft activate, weft deactivate, weft resync and the weft infra commands.

If you want to choose how triggers go down, options… (shown when a selected box has something to choose) asks you three things. What happens to work that arrives while they are down: Hold it, Hold it, hidden (held, but not listed for the people who answer your program’s questions), or Refuse it. If you hold it, you can also say “then refuse after N minutes”. What happens to work already waiting: Keep it or Drop it. And what happens to the runs going now: Wait for them or Cancel them. Each starts on the default the weft commands use: Hold it, Keep it and Wait for them. If you are stopping, terminating or upgrading infra, the panel asks the same three questions again for the triggers that go down with it, and names them. For turning triggers on, it asks what to do with what they held while they were down: Run it or Drop it. For what each answer does, go and read taking triggers down.

If a selected node exists once per instance, the bar shows an instance: picker. It starts on shared, the copy that belongs to no instance; you can pick all instances, or find or type one instance’s id. The pick applies to every action on the bar and is remembered until you close the editor.

Each trigger and infra node carries a small badge with its state, and hovering it says more:

If the health check took a trigger down, the hover says so. With the built-in health rules, the trigger comes back on its own once its infra is healthy. If the infra node’s own rules never bring it back, click Turn on. For what the health check watches, go and read when a unit stops being ready.

If a resync stopped partway with triggers still down, the status bar shows Resync stopped, with Resync to pick it up where it stopped and Give up to leave those triggers off.

Fold a big program down

Every group has Collapse group in its header, and Expand group when it is shut. The wiring outside does not change either way. Groups start shut.

If you are zoomed in when you open a group, the view zooms out around your mouse until about a dozen of its boxes fit on the screen. If closing one leaves five boxes or fewer on screen, the view zooms back in. Each zoom takes under half a second, and scrolling or dragging during it stops it where it is.

An included file’s box has an Open button that shows that file’s own graph, where you can edit it. There, the group holding the whole file starts open. Return at the top left takes you back.

To make a group, add a Group from the list (Ctrl+P) and drag boxes into it. weft decides where a box landed from its centre, so drag it until its middle is inside. To undo that, delete the group: every box inside climbs out one level and keeps its position.

Moving a box in or out of a group changes your program, because it changes what that box can reach. Dragging a box anywhere else does not: positions live in layouts/, beside your source, not in it.

To show your program to somebody, there is a Simplified view switch at the top right. Every box becomes a plain square with one dot on each side. You can still move boxes and fold groups, and you cannot wire anything, which is the point.

Next, connect an account.

Connecting an account

A node that sends a Slack message needs a Slack account. You connect it once, weft keeps the credential, and your program passes around a reference to it rather than the secret itself.

Do it in the graph

A node that talks to an outside service has a blue Connect Slack… button in its body, named after whatever service it needs. Until you pick something, that node will not fold shut: the fold arrow is greyed out, and hovering it says Pick a connection first.

Click it and you get your existing connections for that service, then, under + Add a connection, the ways to make a new one:

• Use App name (one click), one row per application your runtime was configured with, each showing the permissions it asks for. Those permissions are fixed per application, so you pick an application rather than ticking boxes.
• Use ours (uses your credits), when the runtime holds a key for that service. This is the row that appears because you filled in access-apps.json before installing.
• Your own…, always. Tick the permissions you want, follow the guide for registering an application with that provider, or just paste a key you already have.

Sign-in opens your browser for the provider’s consent screen and the panel waits, then flips to a green Connected as your name with Change and Disconnect beside it.

If you take the shared door, weft warns you once that somebody else in the same workspace using that same application may disconnect you, and that your own application avoids it.

Or from the terminal

weft connect

Run it in the project folder, pick the node, and answer the prompts. weft connect --list prints what is already stored and changes nothing. weft connect account goes straight to one node: any node that takes a connection of its own, an access node or a route that checks its callers. --disconnect clears a node’s pick and leaves the stored account alone, and --forget <id> deletes the stored account for good.

Every project on the install can pick any stored connection, so if you keep two keys for one service, their names are how you tell them apart: the list shows each one’s account and its name. When you connect a new one your own way, with your own key or your own application, weft connect asks for a name (--label <name> answers without asking), and pressing Enter names it after the service. The editor’s Name field does the same when you leave it empty. If you sign in through a shared application, or through the one your project declares, that application names the connection (a shared key is named after the service), so nothing is asked and --label is refused. A name with the project in it, like acme-scraper, suits a key only that project should use.

Picked on each install

Which connection a node uses is kept by the install you picked it on, never written in your .weft files. A connection lives in one install, so its id means nothing on another: your machine and your cloud each have their own accounts, and each keeps its own pick. If you want a node connected on your cloud install, run weft connect --on prod there (it is the same walkthrough). A node inside a file you include twice is two nodes, one per place, and each place gets its own pick.

If you run a program with a node nobody connected on this install, the run is refused before it starts, naming the node and the weft connect that fixes it. weft activate and weft resync check every node of the program the same way before any trigger moves, so a missing pick is caught there and not at the first call. Forgetting a stored connection takes every pick of it with it.

A pick is kept under the node’s full address, and the file a node is written in is part of that address. So if you move chat.weft into a studio/ folder, the node that was chat.send.agent is now studio.chat.send.agent, and its pick stays behind under the old name. weft never guesses where a node went. If a node in the program can hold every field the old one kept (the same field, picked the same way, on the install or @instance_filled, and connecting to the same service; extra fields are fine) and nothing is stored for those fields there yet, activating refuses and names both addresses:

'chat.send.agent' has connections or values stored on this install and is no
longer in the program; did you move it to 'studio.chat.send.agent'?
`weft connect --move chat.send.agent studio.chat.send.agent` carries them across

weft connect --move <old> <new> carries the program’s pick and every instance’s values for that node across in one go. It refuses if nothing is stored at the old address, if the new address is not in the program this install last built, if the new node already has something stored, or if it cannot hold every field the old one kept.

If a build refuses a line like account: {"id": "...", "identity": "..."} with “that was the old way of connecting a node”, the connection was written into the source by an older weft. Erase that line and connect the node again; the install keeps the pick from then on.

Never paste a key into a node’s field

Values written into a node travel through the journal and render in the inspector as plain text, where anybody who can open the project reads them. That is also true of anything you paste into a chat with your assistant.

A connection is the other thing: the secret goes into weft’s own store, and what moves along the wire is a small reference with no secret in it.

{
  "__weft_access__": {
    "accessId": "connection-id",
    "service": "slack",
    "identity": "Acme Corp",
    "requiresPermissions": ["chat:write"]
  }
}

When a node consumes it, the runtime adds what that node needs onto it. When the node opens it, a missing stored value is refused, and so is a missing permission on a verified connection, rather than failing halfway through a call.

What weft can tell you before a call fails

Providers differ in how honest they are. Some state exactly what they granted, and weft blocks a node whose permission is missing. Others only confirm the credential is alive, or say nothing at all until a real call comes back refused, and then weft lets the call through because it has nothing to block on.

So a bad credential sometimes shows up for the first time when a node tries to use it. For the whole picture, go and read how connections work.

Next, put a person in the loop.

A public address

If you want Slack, Stripe or Telegram to push events into a program running on your laptop, they need somewhere to push them. Your laptop is behind a router and has no address they can reach, so weft opens one for you:

./setup.sh --public-url

That opens a tunnel from a public address to a port of its own on your machine (14112 on the default install), where weft serves a short list of paths. The choice sticks: later runs of ./setup.sh keep the tunnel open until you pass --no-public-url.

What it exposes, and what it does not

These paths, and nothing else. Everything else on that address answers 404.

Every /signal-token/... request, and a DELETE /signal/<token>, carries the signal token in its Authorization: Bearer header, so it stays out of proxy logs. The <token> in a /signal/ path is a different one: the link’s own token, which is made to be pasted.

Your dispatcher’s real API, your projects, your journal and your runs are not on that port at all, so nothing arriving through the tunnel can reach them. They stay on 127.0.0.1:14111 (the default install’s address; weft daemon which gives another’s), which listens on your machine only, asks every caller for an operator key and sends no CORS headers. For how that key works, go and read the key the install’s API asks for.

Find your address

weft daemon status

weft: running at http://127.0.0.1:14111 (install 'default'); 1 project(s)
public address: https://something.example (./setup.sh --no-public-url closes it)

The installer prints it too, when it is open.

Hand a provider the full path for what it is sending, not the bare address: https://something.example/events/slack/messages. Each trigger’s connect panel shows you the exact one it wants.

It changes when the tunnel restarts

This is the thing that bites. The address is not yours to keep. When the tunnel comes back up with a different one, anything you registered against the old one is pointing at nothing, and events stop arriving without an error anywhere: the provider is posting into the void.

So after a restart, check weft daemon status and re-register the address with any provider you configured by hand. A Slack app’s Request URL and a webhook you pasted into somebody’s dashboard both need it.

A stable address of your own

If you want an address that never changes, run the tunnel under a hostname you own. You need a Cloudflare account with that domain on it.

1. In the Cloudflare dashboard, create a tunnel (Zero Trust, then Networks, then Tunnels) and copy its token.

2. Add a public hostname to that tunnel, say weft.example.com, and set its service to the port weft serves those paths on: on Linux, http://127.0.0.1:14112, because the tunnel shares your machine’s network; on macOS, http://host.docker.internal:14112. 14112 is the default install’s port. A branch’s install has its own: the outside value in ports.json, in the folder weft daemon which prints.

3. Install with both set:

   WEFT_PUBLIC_TUNNEL_TOKEN=<token> WEFT_PUBLIC_TUNNEL_HOSTNAME=https://weft.example.com ./setup.sh --public-url
   

   The hostname is the bare https:// address, with no port and no path.

Once the tunnel is up, weft daemon start fetches the page at your address through it. If the service in step 2 is wrong, the start fails and says so, naming the value it expects.

The install remembers that tunnel, so a later weft daemon start or weft daemon restart from a shell that sets neither variable opens the same one again. If you set both, they win, and the install remembers the new ones. To go back to a quick tunnel, run ./setup.sh --no-public-url, then ./setup.sh --public-url with neither variable set.

Close it

./setup.sh --no-public-url

The tunnel comes down and the address stops answering.

Devices on your own network

If you want a phone or another computer on your wifi to open what your program hands out, without the internet in between, give weft this machine’s address on that network:

WEFT_NETWORK_ADDRESS=192.168.1.20 weft daemon start

network address: http://192.168.1.20:14112 (the doors outside callers use, for devices on this machine's network; a start with WEFT_NETWORK_ADDRESS=off closes it)

weft then answers the paths in the table above on that address too, on the port the tunnel uses (14112 on the default install), and nothing else: your projects and runs stay on 127.0.0.1. weft remembers the address for every later start. If you want to close it, start once with WEFT_NETWORK_ADDRESS=off.

It takes the bare IP (ip -brief address lists yours), and weft adds the scheme and the port itself. The start refuses a value with a scheme, a port or a path. It also refuses a loopback address (no other device can reach it), 0.0.0.0 or :: (that would open these paths on every network this machine is on), a link-local IPv6 one starting fe80:, and one this machine does not have. Each refusal names what to give instead.

Your own site in front

If your project has its own site and you want links to its stored files to go through that site, tell weft the address where the site passes its visitors’ calls on to weft (the weftPassThrough helper from @weft/connect/server, mounted at /weft on the site):

weft frontend visitor-address shop https://shop.example/weft

shop is the name you gave the frontend with weft frontend add. If you are making the frontend now, weft frontend add shop --visitor-address https://shop.example/weft sets it in the same step. To clear it, give off in place of the address. One frontend per project can hold it: asking for a second is refused, naming the frontend that has it.

Which address a file link gets

When your program hands somebody outside a link to a stored file (a file in a route’s answer, say), the link goes through this tunnel only on a local install whose project has no visitor address. With the tunnel closed too, it goes to the install’s own address: the network address if you set one, which only devices on your network can open, otherwise 127.0.0.1, which only this machine can open. For the full order and what a node sees, go and read handing a file out.

If your tunnel is the one whose address changes on restart (./setup.sh --public-url without a hostname of your own), weft asks it for its address each time it makes a link, so a new link always carries the current address. A link handed out before the tunnel restarted still points at the old one. If the tunnel cannot say its address at that moment, the link is refused:

the install's tunnel does not say its address right now; `weft daemon start` opens it again

When you do not need it

Triggers that go and fetch rather than wait to be pushed work with no public address at all: a timer, a poller, anything weft opens an outgoing connection for. So do runs you start yourself, and so does a person answering through the browser extension, because that talks to your runtime directly.

You need this page when a provider insists on pushing. For which triggers those are and how a service declares its event transport, go and read events from a service.

Putting a person in the loop

A node can stop and ask somebody a question. The run parks, the worker shuts down, and when the answer arrives a fresh worker picks the run back up exactly where it was. Waiting costs nothing, so a program can sit on a question for a week, as long as the run can pause (for when it cannot, go and read when a run cannot pause).

This is HumanQuery, and it looks like this:

review = HumanQuery {
  title: "Send this answer?"
  fields: [
    { "kind": "display", "key": "question" },
    { "kind": "display", "key": "answer" },
    { "kind": "approve_reject", "key": "send" }
  ]
  question: ask.content
  answer: draft.answer
}

The fields list builds both the form and the node’s ports. A display field takes a value in and shows it to the reader. An approve_reject field gives you two boolean outputs, sendApproved and sendRejected, so you gate what happens next on the one you want:

# ask is the BaileyReceive trigger the message came in on, whatsapp its BaileyBridge
reply = BaileySend {
  _should_flow: review.sendApproved
  bridge: whatsapp.bridge
  to: ask.chatId
  message: draft.answer
}

Where the question shows up

Not in VS Code. The graph shows you that something is waiting, with a cyan ring round the box and the word Suspended in its body, and the inspector says Waiting for input.... Answering happens in the Weft tasks browser extension you installed earlier.

Give the extension a way in by minting a token from your project folder:

weft token mint --name "my laptop"

A signal token lets an outside client list a project’s waiting nodes and answer them. The full value is printed once, at mint, and never again, so copy it now. --projects and --tags narrow what it can reach, and weft token ls and weft token revoke <id> handle the rest.

Open the extension, go to its settings, and add your runtime: its address and that token. The browser will ask you to allow access to that host, because the extension holds no permission to reach anything until you give it one.

What the person sees

One card at a time. Your title, the values you wired into the display fields, and the buttons or boxes your other fields asked for. The primary button says Submit for a question inside a running program, and Fire for a trigger that starts one.

Beside it, Skip declines the question: the node that asked ends skipped, every output of it closes, and the nodes reading them skip in turn while the rest of the run carries on. Cancel run ends the whole run. Neither shows up on a trigger, which has no question to decline: weft refuses a skip there.

After a submit the card says Submitted and moves to the next one. Back in the graph, the cyan ring goes green and the rest of your program runs.

Starting a run from a person

HumanTrigger is the same form pointed the other way: instead of parking a run that already exists, it starts a new one when somebody fills it in. It shows up in the extension under trigger tasks rather than resume tasks, and it only appears once you have run weft activate, because a trigger is only listening after you arm it.

For why activating is a separate step from running, go and read the three lifecycles.

When nobody answers

A parked run waits, with no deadline. HumanQuery has no timeout setting and weft will not invent one, because a question that expires on its own leaves you with a run that ended for a reason nobody wrote down.

So ending it is a decision somebody makes. The person looking at the card can press Cancel run, and you can run weft stop <run-id>. To find the ones still sitting there:

weft runs --status waiting_for_input

That lists only the runs parked on a wait. weft runs --status running lists them too, beside the ones still working, and the status column tells them apart.

How a program runs

Do not read a weft program top to bottom. A node can send its answer before it has finished, or sit waiting for a week while the rest of the program carries on. If you want to predict what happens, look at what arrives at each node’s inputs.

Values arrive one at a time

When a node emits, the value travels along every arrow leaving that output. Each delivery is a pulse, aimed at one input, carrying a tag saying which run it belongs to. One output wired to three inputs is three deliveries.

A node waits until every input with an arrow into it has either a value or a closure. Optional inputs count too: an arrow is an arrow. An input can also be satisfied by a value written into the node or by a default, so not everything needs an arrow.

Once every wired input has settled, weft decides whether the node runs or is skipped. A node with nothing wired into it has nothing to wait for, so weft starts it when the run begins.

How a branch stops the nodes after it

Here is the problem. A node decided not to send anything. Everything wired to it is now waiting for a value that is never coming. How does the program know the difference between “not yet” and “never”?

A closure is the answer: it is a pulse that says nothing will ever arrive here, for this run. It is how a node says no rather than saying nothing.

It is not null. null is a value, and a port whose type allows it takes it like any other.

Here is what a closure does to the node it reaches:

By default a node needs every input that is wired, and writing ? on one lets it run without it. For which inputs a node needs, with an example of each, go and read optional and required inputs.

If every input wired into a node is written with ?, nothing says when it should run, and the compiler stops with run-undecided: gate it with _should_flow, drop the ? from the input it cannot do without, or add @require_one_of. A node that joins branches, like FirstInOrder, needs none of these. Neither does a node whose input comes from a port that always carries something when its group or loop runs, such as a port of a group whose gate is wired, a group port with a value written on it (g.x = "hi"), the item a loop iterates over (a port named in its over), or self.index: the way its value arrives already says when it runs.

A skipped node closes its own outputs, which can skip the next node, and the next, until the closures reach something that can carry on with what it has.

flowchart LR
    choice[Switch] -->|true| send[Send]
    choice -. closed .-> review[Review skipped]
    review -. closed .-> archive[Archive skipped]

Streams close differently. A closure on a stream is the stream’s end rather than a skip, so a reader whose stream carried nothing still runs and sees that nothing came.

A failed node closes whatever it had not already sent. Anything it did send is not taken back. For how a program carries on past a failure, go and read when a node fails.

Choosing a branch, and joining back up

Every node has _should_flow, and it defaults to true. Wire a value into it to decide whether that node runs.

Only a literal false says no. Any other value lets the node run, and so does anything the node’s own code would have considered falsy. The node never sees this port: weft checks it before calling in.

Switch gives you one output per case. It tries them in the order you wrote them, and the first one that matches emits true while every other one closes. Wire a case’s output into a node’s _should_flow and that node runs on that case only. If nothing matches and you gave no otherwise, they all close.

To bring two alternative answers back into one arrow, use FirstInOrder. It waits for its wired inputs to settle, then takes the first one that actually supplied a value, in written order. Moving those lines changes which answer wins. Which one arrived first makes no difference.

_should_flow takes one wire, so “only if the model said it was rude and said it was sure” is one gate fed by two conditions. All is the AND: wire both conditions into it and gate on what it emits. It emits when every input arrived and none of them is false, and a branch that closed never arrives at all, so a closed input is not a false.

Running on the thing that did not happen

Everything above skips when its inputs close. So how do you run a node because something did not arrive?

Wire that something into _should_not_flow instead. Every answer flips: a value arriving means the node stays off, and a closure, the structural “nothing is coming”, is what runs it.

route = Route -> (body: { title: String, photo?: File }) { path: "cards", method: "POST" }

# A card sent with no picture: the wire reading `photo` closes, so this runs.
defaultArt = FetchToStorage {
  url: "https://example.com/blank.png"
  _should_not_flow: route.body.photo
}

This is the one port in weft that starts a node on a closure. Reach for it when the absence is data, like a key the caller did not send. When the absence is a decision your own node made, have that node say so on a second output and gate on that, because the wire then reads forwards.

A failure is not an absence. When the node it watches fails, its ports close too, but that closure carries which node broke and its error, and the gate reads it: the node stays off, skipped with the reason what its _should_not_flow watches did not finish ('query' failed: the database is down), and the run reports the failure. So a “nothing there” branch never runs over a database that is down. The same holds through a group or a loop: a failure inside closes the scope’s outputs with the failure on them, so a watcher outside reads it as one (and a loop whose carried value is lost to a failure stops and fails, see loops). And it holds through a skip: a node that skipped because its input closed on a failure did not decline either, so its own ports close with that same failure on them (its skip reason ends in because 'query' failed: ...), and a watcher two nodes down still reads a failure, not an absence, and still sees query named as the node that broke rather than the node that skipped. The one exception is a node whose _error is wired: it handled its failure, so it counts as finished and its ports close as plain absences (below).

A node has one gate. Wiring both spellings is the two-gates error.

When a node fails

Left alone, a node that fails fails the whole run. If you want the program to carry on instead, wire the node’s _error output. Every node has one, given by weft. When it is wired and the node fails, the reason comes out on _error as text, the node counts as finished, and every output it had not sent closes.

So to run a backup only when something broke, gate the backup on _error:

fetch = HttpRequest { url: "https://example.com/prices", method: "GET" }

backup = HttpRequest { url: "https://mirror.example.com/prices", method: "GET" }
backup._should_flow = fetch._error

When fetch works, its _error closes and backup skips. When the host does not answer, the reason arrives on _error and backup runs. The failure still shows in the node’s log, as failed, handed to the '_error' output: ..., so weft logs and the inspector tell you it happened.

Only a failure of the node’s own work goes to _error: a service refusing or not answering, a script raising, a wait that gave up, a node whose worker died in the middle of a durable run, or a value that does not fit the type you declared on its output (a model’s answer missing a field of the record you declared on LlmInferenceJson, or a value a Cast cannot convert). A mistake in the program, like a bad setting or an input the node cannot read as the type that input declares, fails the run even with _error wired, because only changing the program fixes it. Scripts are the exception to the output case: a script’s code is part of your program, so a script returning the wrong type for an output is a mistake in the program and fails the run. For what a script may return, go and read declaring ports, and for which nodes fail and which run again when a worker dies, how a run is kept. A cancel, or a node pausing to wait for an answer, is not a failure, so it never comes out on _error either.

Once a node has started a stream, its failure fails the run. As soon as anything went out on a Bus or Generator output, the readers already hold part of the answer, and a backup gated on _error would send a second answer on top of it. The stream ends failed instead, and its readers are told (go and read how a bus ends). A producer can open its bus on the first piece, the way LlmStream does. So if a model refuses a prompt before writing a word, the refusal still comes out on _error. The node’s bus port then closes like any output it never sent: a reader that needs the bus skips, and the backup can answer.

A group, a loop or an included file has no _error of its own. If you want to handle a failure from inside one, take the failing node’s _error out through one of the group’s outputs, like any other value.

_error belongs to weft. A program that declares an output called _error on a node is refused, while error, without the underscore, is a name like any other.

One node, several firings at once

A firing is one go at one node. Three things say which firing you are looking at: the run, the node, and the loop iterations it sits inside. Inside a parallel loop the same node can have several firings alive at the same time.

Those iteration numbers are called frames. Work at the top level has none, and work inside two nested loops carries one frame for each. weft only ever combines inputs whose run and frames match, which is what stops iteration three eating iteration four’s answer.

An ordinary output emits at most once per firing, though it can emit on one output now and another later. Whatever it never mentions is closed when it finishes. Generators and buses have their own rules, in streams and buses.

Groups and loops at run time

When the program runs, no node stands for a group, and a loop becomes two nodes, a LoopIn and a LoopOut. For the details, go and read no node stands for a group and loops.

What happens when you hit run

A manual run starts every node at the top level that has nothing wired into it, plus every trigger in the project, wired or not. Triggers get no event on a run like that, so they close their outputs, and only the paths that do not need an event go anywhere.

To run part of a project:

weft run --target dailyReport --target alert

weft takes those nodes and everything feeding into them, stopping the walk when it reaches a trigger. A node that several branches share does not drag those other branches in. A target inside a group brings only the work needed through it, and the group’s _should_flow comes along too, unless it is wired straight from a trigger the run does not fire. A loop the walk reaches from outside comes along whole: a target after a loop runs every iteration of it. If you want to run part of a loop’s body, start and end the run inside the body (see running part of a loop’s body).

What runs is a cut: a smaller program holding only what the walk kept, with every node under its own name, so the journal and the inspector line up with your source.

You can also start in the middle, handing values in where the walk begins:

weft run --from classify='{"text":"..."}' --target reply
weft run --group triage='{"text":"..."}'

A value you hand in is that port’s value: in this run the wire into that port delivers nothing there, so nothing upstream can replace it. For which flag picks which part of the graph, go and read versions, seeds and frozen examples.

--group runs the group’s own nodes and nothing that feeds it, so a group port wired from outside gets only what you hand it. If a cut leaves an input with nothing, weft looks at who needs it. When a node would skip without it (it is an input written without ?, default or not, other than an input of a join node such as FirstInOrder, which is optional anyway; or the only member of a @require_one_of set that could get a value; the node’s own, or one inside the group it enters, followed through every group, loop and included file on the way), the run is refused before it starts, naming the input and what it feeds:

triage.text gets nothing in this run: ask.text is outside it, and
triage.classify.text cannot run without it. Hand it a value at this start
(--group triage='{"text": ...}'), run what feeds it with --feed triage, or
start further up so ask runs too.

The flag in the message is the one the start was named with: --group for a --group start. An input no start lies in front of is named where the wire lands, and the way to hand it a value is to start there. When the value could only come from a trigger the run does not fire, the message says so and offers --fire on that trigger as well as handing the value in.

The input is named at the start you gave, even when the missing value would pass through more group ports on the way (a group inside an included file), and a value you hand there feeds everything behind it. A trigger’s own inputs never count: a run that does not fire it never reads them. An input that only feeds inputs written with ? just closes, with a warning.

A start is where the walk upstream stops, for --from and --group alike, so a start’s own ports get only what you hand them. To have weft run what feeds them instead, add --feed:

weft run --from 'hear.note={}' --feed hear.note --target hear.note

For each input of hear.note you did not hand a value, that runs the node feeding it and nothing above that node. The value is followed through every group port it passes, however deeply the groups nest, and a feeder shared by several inputs runs once. A loop’s result comes from the whole loop, so a loop feeding the start runs whole. You can also name the feeders as starts yourself (--from db --from accounts --from hear.note): when one start lies upstream of another, the run keeps both, and --target still leaves out every branch that target does not need.

A gate only holds a start back when something in the run decides it. The walk upstream stops at a start, so the start’s own _should_flow, and that of each group it sits inside, stays out of the cut unless another start, or the trigger you fire, runs whatever feeds it. A group’s gate wired straight from a trigger the run does not fire stays out too, for a start or a target. A wired gate left out acts as if nothing were wired to it, so the node or group runs (a gate written in the braces still applies): that is how a node inside a group gated by a Route runs when you start it by hand. If you want the condition checked, start further up instead, so whatever decides it runs too, or drop the start and --fire the trigger with an event.

Without --target, a run goes everywhere downstream of its starts, so --from db alone runs every branch db feeds. --target narrows that to what the target needs, starting no further up than the starts. It is one shape, not a run that goes until it reaches the target.

If you want everything a node needs but not the node itself (say a node called post that publishes the result), end with --before post instead of --target.

If you want to get past a node without running it (a trigger you have not activated, an infra node, a call you do not want to pay for twice), stand in for it with --emit: --emit fetch='{"body": "..."}' says what fetch would have sent, and the run starts from there, the way it starts at a --from.

Any of these flags can name a node or a group inside a loop’s body, as long as the run does not cut a loop in half: it holds both ends of a loop (the loop runs whole, every iteration) or neither (only the part of its body you picked runs, once). For what that part gets and what is refused, go and read running part of a loop’s body.

On a --seed run the check waits for the seed, since a saved result can supply the input. It only can when the run it reads completed that node and the node’s code has not changed since; a refused seeded run names the run it read.

A trigger firing picks the work downstream of that trigger, plus whatever that work needs upstream, again stopping at other triggers. Only the trigger that fired gets the event; any others close. Two triggers can share the nodes in the middle without becoming one run.

In a program with instances, a run is also for one instance or for none (weft run --instance user-42 picks one). For what is checked before such a run starts, go and read programs with instances.

How a run ends

A run is finished when there is no work left and nothing still in flight. It does not need an end node. It can also fail, when a node failed and nothing was wired to its _error, or when weft could get no further. A person or another run can also cancel it.

A run can pause without ending. Waiting for input means a node is parked on an answer from outside, and the run carries on when that answer comes.

If work is left that can never proceed, weft reports the run as stuck and names the nodes and inputs involved. A run parked on a person’s answer is waiting, not stuck.

What survives a restart

As a run goes, the worker writes down each thing that happened, in a log called the journal. Those records are what the graph shows you.

If its worker dies, what happens to a run depends on its trigger’s durable setting: for that, go and read how a run is kept. Before you put side effects around a wait, go and read surviving a restart.

What the build catches

The compiler checks that every arrow’s types fit, that every required input is covered, that no wire crosses a scope boundary it should not, that there are no cycles, and that the loop and channel restrictions hold. It also runs whatever validation rules a node declares for itself.

Some things are checked when you build and some only when you run, so a build can succeed and a value can still be rejected later, when a node emits something its declared output type does not allow.

It cannot check whether a node does useful work. A model can return a perfectly typed answer that is wrong. For every rejection by name, go and read what the compiler refuses. To start writing weft yourself, carry on to syntax.

Syntax

A .weft file names some nodes and connects them up. This program puts HELLO in front of you:

message = Text { value: "hello" }
shout = ExecPython(text: String) -> (text: String) {
  text: message.value
  code: "return {'text': text.upper()}"
}
show = Debug { data: shout.text }

message, shout and show are names you choose, unique where they sit. Text, ExecPython and Debug are node types, from the project’s nodes/ folder.

Naming a node

name = NodeType, and braces if you have anything to put inside:

message = Text { value: "hello" }

A node with nothing to configure can drop the braces, so Debug and Debug {} mean the same. You still have to supply whatever that node requires.

A name the catalog does not know is unknown-type. Writing a name does not bring a node into existence; the declaration has to be there.

Connecting things

Write source.output where a value would go:

show = Debug { data: message.value }

Or put it on its own line, which is the same connection:

show.data = message.value

Values travel right to left, into the input on the left, and the type has to fit. Write the wire in the braces whenever you can. The line of its own is for the ports a group, a loop or an @include declares, which you set from outside because their braces hold something else or there are none.

To take one field out of a value, keep going with dots:

show = Debug { data: reader.profile.stats.wpm }

That reads stats.wpm off reader.profile. For the type rules, go and read types.

Writing values in

Inputs take strings, numbers, true, false, null, lists and objects, as long as the type allows it. Lists and objects can spread over several lines, and commas between fields are optional.

message = Text {
  value: "hello"
}

Some inputs only take arrows and some only take written values; the input-accepts diagnostic tells you which. Anything the compiler has to read to work out the node’s shape, such as a form’s field list, has to be written inline: an arrow, @file or @asset cannot supply it.

For text kept in another file, go and read files and reuse.

Triple backticks hold code, or anything with newlines in it:

answer = ExecPython -> (value: Number) {
  code: ```
    return {'value': 42}
  ```
}

You can write a value into an input. Outputs are filled by the node when it runs, so answer.value = 42 in that example is the value-on-output error. The same holds inside a group: connect a child’s output to self.result, and if you want a constant to come out, use something like Text to produce it.

Declaring ports

Inputs in brackets, outputs after ->:

calc = ExecPython(a: Number, b: Number) -> (sum: Number) {
  a: 7
  b: 2
  code: "return {'sum': a + b}"
}

ExecPython hands your code a and b and expects a dictionary back, keyed by output name. A key left out sends nothing on that output, and return {} sends nothing at all. A key set to None sends a real null on an output whose type takes Null (last: JsonDict | Null), and nothing on any other output.

If you want the program to carry on when the script raises (a request it makes fails, or it raises on purpose), wire the node’s _error output: the exception’s type, message and traceback come out there, and the other outputs send nothing. Left unwired, the exception fails the run. A mistake in the program fails the run either way: code that does not compile, a script that ends without returning a dictionary, a key that is not one of its outputs, or a value of the wrong type for its output. _error counts as a key it may not return, since weft fills it; to fail on purpose, raise. _error is not only for scripts: every node has one. For which failures reach it, go and read when a node fails.

You can declare any of the node’s own inputs, with its type or a narrower one, and add new inputs on a node that takes them. An output you can declare only where the node leaves it open: one it lets you add, one typed with a type variable (a stand-in like T that takes its type where the node is used), or one it lets you narrow. Declaring an output looks like this:

answer = LlmInferenceJson -> (response: { label: String })
convert = Cast -> (value: Boolean)

Those are fragments: the nodes still need their other required inputs before they can run. For narrowing an output like response, go and read saying what a broad output holds.

A group or a loop can also list a metadata port among its outputs, with a * before the name: -> (results: String, *tool: LlmTool). Its value is written in the program instead of made by a run. For what that is for, go and read metadata ports.

Optional and required inputs

A node’s metadata says which of its inputs it can run without. Where you use the node, you can declare the input yourself: without ? it is required, and with ? the node runs without it. If the metadata requires that input, the ? is a compile error.

A wire closes when its source finished without sending on that port, or failed. A node that skips closes its own outputs in turn. A ? lets a node run without a failed source’s value, but the failure still fails the run unless that source’s _error is wired (go and read when a node fails).

One exception to the table: an input in one of the node’s oneOfRequired sets (or in a @require_one_of you wrote on it) is decided by its set. The node skips only when every member of the set closed, unless you declared that input without ?.

If you want the build to refuse a node until something fills an input, declare that input without ?. SlackSendMessage takes text or blocks, so neither is required on its own, but this message must have text:

send = SlackSendMessage(text: String) {
  account: slack.access
  channel: "#support"
  text: draft.answer
}

Leave text out and weft validate refuses send: required input 'send.text' has no driver (no edge, no body value, no default).

If you want a node to run when a wire into it brings nothing, write the ?. Here ask is a SlackReceiveMessage, whose thread sends nothing when the message was not in a thread. With threadTs?, such a message gets its answer at the top of the channel. Without the ?, answer waits for threadTs and skips:

answer = SlackSendMessage(threadTs?: String) {
  account: slack.access
  channel: "#support"
  text: draft.answer
  threadTs: ask.thread
}

Extra inputs

Some nodes, ExecPython and FirstInOrder among them, let you invent input names. Writing a key in the body creates that input and works out its type from what you put there:

summary = ExecPython -> (out: String) {
  text: draft.answer
  limit: 3
  notes?: review.notes
  code: @file("assets/scripts/summary.py")
}

limit becomes a Number. text takes whatever type draft.answer has. A bare null gives it nothing to work from, so that fails.

The ? on notes? works like x?: T in the table above: the node runs without notes even when its wire closes. Without the ?, a port you create this way is required. That spelling only works when you are creating the port; for a port the node already has, write the ? in the signature, like (threadTs?: String).

Extra inputs stay in the order you wrote them, which matters for FirstInOrder, since it takes the first one that supplied a value.

The four underscore keys

Any other key starting with _ is an error.

send = SlackSendMessage {
  _should_flow: review.approved
  channel: "#support"
  text: draft.answer
}

A node has one gate, and wiring both spellings is the two-gates error. For what each one does to the nodes after it, go and read how a program runs.

Groups and loops

A group’s braces hold its children, and its signature says what the outside can see:

shout = Group(text: String) -> (result: String) {
  # Uppercase the message
  convert = ExecPython(text: String) -> (text: String) {
    text: self.text
    code: "return {'text': text.upper()}"
  }
  self.result = convert.text
}
shout.text = "hello"

Set a group’s inputs from outside, as shout.text does. self means this group’s own interface. _should_flow can go inside the braces too, and when it skips a group it skips everything in it. The only literal you can write on self is a metadata port’s value: self.tool = { "name": "search" }.

Loops work the same way with iteration settings of their own. Go and read groups and loops.

Declaring a node where you use it

You can write a node straight into the place its value is wanted, ending with .port to say which output you mean:

show = Debug {
  data: Text { value: "hello" }.value
}

That makes the node and the arrow together, exactly as a named declaration would. The .port on the end is required even when there is only one output.

Needing one of several inputs

@require_one_of says a node needs at least one out of a list:

lookup = SlackFindUser {
  @require_one_of(email, id)
  account: slack.access
  email: "person@example.com"
}

Every name in there has to be a real input. Supply none of them and the compiler says require-one-of-unmet. At run time, the node skips if they all close without a value.

It goes in a node’s body or its inline signature. A node’s author can bake the same requirement into its metadata as oneOfRequired. Groups and loops reject it: put it on the child that needs the value.

One copy per instance, one value per instance

@per_instance on its own line in an infra node’s body gives each instance of the program its own copy of that node (its own container):

bridge = BaileyBridge {
  @per_instance
}

It takes no arguments.

@instance_filled goes where a field’s value would, and makes the value each instance’s own: @instance_filled alone, or @instance_filled(<value>) with the value an instance that was given none gets. A connection is a value too:

google = GoogleAccess { account: @instance_filled }
digest = Cron { cron: @instance_filled("0 0 8 * * *") }

The fallback can also be a file, read the way a written one is: personality: @instance_filled(@file("prompts/default.md")).

For what both do, go and read programs with instances.

Spelling a name

Every name you choose in a program is camelCase: what you call a node, a group, a loop or an @include (sendReply), and every port you declare on a node, a group or a loop, or in an included file’s header (maxRetries: Number). A key you write in a node’s body that creates a port counts too (userId: 3 on ExecPython). A node type is spelled exactly as the catalog spells it, which is PascalCase (ExecPython).

If you spell a name you chose any other way, the program still runs, and the compiler warns not-camel-case. When it can respell the name, the message says how:

node 'send_reply' is not camelCase: write 'sendReply'

The gates, _should_flow and _should_not_flow, are the language’s own names, so this warning skips them.

If the ports you add are named after data from outside weft, you can keep that data’s own spelling on a node built for it: body = JsonObject { user_id: ask.id } draws no not-camel-case warning for user_id, though the name you give the node, body, is still checked. A few nodes that ship with weft let you do this (Route for its path’s captures, JsonObject for the keys of the object it builds, among others), because each one sets addedPortsAreDataKeys in its metadata.json. For the full list, go and read the addedPortsAreDataKeys row in the features table.

Comments

# starts a comment. A plain comment as the first thing inside a group or loop body becomes its description, which is what the graph shows when it is folded shut, as in the shout example above. A comment anywhere else is just a comment.

The parser keeps your whitespace and comments, so the editor can change one field without reformatting everything around it. There is no enforced formatting style.

Types

Every port has a type, and the compiler checks every arrow before anything runs. Same colour on two dots is the quick version of what this page explains.

What you can write

String
Number
Boolean
Null
List[Number]
Dict[String, Number]
String | Number
{ role: String, name?: String }
{ role: String, .. }
Generator[String]

A stored file on a wire is never the bytes. It is a small marker saying where the file is, which is why a String holding a URL is not an Image.

What fits into what

Records are strict. A field the target does not declare is a mismatch, not something quietly carried along. If you want a record that takes keys it does not name, end it with ..: { email: String, .. } takes any record with an email. At run time, a value checked against it (a request’s body, a model’s answer, what a Cast makes) loses every key the type does not name, so what flows on carries only email. A missing required field is refused either way.

A field that can be null says so: extra: JsonDict | Null. A JsonDict alone refuses a null, so if you declare a query’s rows as List[{ id: String, extra: JsonDict }] and a row comes back with extra null, the node fails with ... does not accept: [0].extra: expected JsonDict, got Null, and the fix is the | Null on that field.

Empty is the type of a value that cannot exist. An empty list [] is List[Empty], because there is no item to learn from, and that goes into a List[String] or a List[Number] without complaint. Inside a union it disappears: Number | Empty is just Number.

A port typed with a type variable (T, T2) gets its type where the node is used: from the type your program declares on it, from what is wired to it, or from a value written into it. Cast’s output is the type variable T2 (its input is T), so it takes the type you declare on it (-> (value: Boolean)), or else the type of the port it feeds. A port you declare in a header with no type, like (x), gets a type variable of its own, so for a group g = Group(x) -> (y: String), writing g.x = 3 makes x a Number. A type variable nothing pins is the unresolved-typevar error.

A type variable can be limited to some types. A group says so right after the word Group, blur = Group[T: Media](file: T) -> (out: T), and so can a node you declare inline (ExecPython[T: Media](f: T)). A node’s author does it in its metadata.json (KeepFile only takes a file); for how, go and read typeParams. Wire a String into that group’s file and the build stops with type-bound: `T` has to fit in Media, and what is connected makes it String.

Saying what a broad output holds

Some outputs carry a shape only your program knows, like the JSON a model answers with or the body of a request. Their node types them broadly, usually JsonDict, and lets you declare what they hold on the node, like this:

type Verdict = { label: String, score: Number }
judge = LlmInferenceJson -> (response: Verdict) {
  prompt: "Label this review and score it from 0 to 1"
  provider: model.provider
}

From there on the wire carries a Verdict, so judge.response.score reads as a Number. At run time every value is checked against Verdict, and one that does not fit fails the node, which _error catches when it is wired.

You can only do this on an output whose node allows it, and only with a type that fits inside the widest one the node accepts there. Declaring -> (response: Number) on LlmInference, whose answer is always text, is refused when you build: ... output port 'response' is declared Number, but LlmInference always gives it String: only an output its node marks narrowable takes the type the program declares.

Giving a type a name

type CustomerId = String
type Ticket = { id: CustomerId, body: String, priority?: Number }

A declaration goes at the top of a scope, meaning the file, or a group’s or a loop’s body. Not inside a node’s braces. Order does not matter. A name is visible in its scope and every scope inside it, included files too: for how a type reaches into an @include, go and read files and reuse.

Names are compared as names. CustomerId and String are different types even though one is the other underneath. That is the point: a customer id cannot be wired into a port that wanted any old string by accident.

A name flows into its underlying shape for free, because the name just falls away. Going the other direction needs a Cast, which checks the value really has that shape.

Nothing shadows. A name already visible cannot be redeclared, even to the same thing. Two catalog packages shipping an identical type is fine (for two that disagree, go and read custom types). And a port that restates a declared name with a different body is the named-type-conflict error, because a named type has one body everywhere.

Reading a key off a wire

speed.wpm = reader.profile.stats.wpm

The dotted path goes on the source side only. A wire lands on a port, never on a key inside one.

Each step of the path has to name a field of a record. A JsonDict has no declared fields, so reading a key off one is the deref-path error telling you to declare the type on the source port, or Cast it first.

The interesting case is an optional field. If you read ?-marked key and it is missing, or it is null, the wire closes. It does not deliver null. So the node you wired it into applies its own rules: it skips, unless you declared that input with ? (x?: T), and then it runs without it. For what a closure does, go and read how a program runs.

A required key that is missing is an error naming the key, never a quiet null.

Cast

Cast is the node for converting a value and checking the result. You declare the type you want on its output, and the compiler tells you whether that conversion exists at all.

If an ordinary arrow is refused and a cast would work, the type-mismatch message says so and tells you to wire it through a Cast.

At run time, a value that does not convert fails the node naming the field that was wrong: cannot cast the value into Verdict: not a valid Verdict: field "score": "high" is not a number. If you want to handle that instead of failing the run, wire the Cast’s _error.

Secrets

Secret[T] is a T that flows through a run like any value while the run’s record holds only a marker naming it. A caller’s Authorization header on a Route or a Socket comes out this way, on credentials, and so does a token MintInstanceToken makes. The record, the inspector, weft events and search show the marker. The value is kept sealed beside the record, and goes when the record goes.

A secret turns back into its value only inside a node that asks for it, and only where the type of what you wired in says a secret is. Some of weft’s own do it for you: HttpRequest sends a secret in its headers or its body revealed, Reply and Stream send one to their caller revealed, and ExecPython hands its script the value of an input you declared as a secret.

If a secret reaches one of them somewhere its input’s type does not declare one (inside a JsonDict, or in a Stream’s bus message, which carries no type), the node fails and names the input and where the secret is, rather than sending the marker. Declare the type, like an object’s fields, and it goes out revealed. If you want an HttpRequest body to carry a token, declare the object you build for it:

mint = MintInstanceToken { instance: "user-42", expiresInHours: 24 }
handoff = JsonObject -> (object: { instance: String, token: Secret[String] }) {
  instance: "user-42"
  token: mint.token
}
notify = HttpRequest {
  url: "https://partner.example/tokens"
  method: "POST"
  body: handoff.object
}

Left as JsonObject { token: mint.token }, the same body builds, and the HttpRequest fails when it runs, naming body and /token.

A body with no secret in it needs no declared type: a plain object, written or wired, goes out as it always did. For writing a node that makes or reveals one, go and read the ctx.

Only a node makes a secret, so nothing written in a .weft file can be one. If you need to make one without writing a node, declare an ExecPython output as Secret[String], and what the script returns there becomes a secret. The build refuses a value written on a Secret port, a secret’s marker written anywhere (secret-literal: it would name a secret of another run), a Cast into or out of a secret, and an @instance_filled secret (instance-filled-secret). A wire cannot read a key inside one either: if node s has an output session typed Secret[{ token: String }], s.session.token is the deref-path error, since what flows is the marker.

What an unwired port starts as

A port nobody wired and nobody wrote a value into has a zero value, which is what seeds a loop’s carry when you did not give it a starting value.

Groups

A group holds several nodes under one name and folds shut like a folder. Its signature says what the outside can see.

credit = Group(db: Access[postgres], user: String) -> (paid: Boolean, refusal: String) {
  # Take one credit off this account, or say why we cannot
  debit = PostgresExecuteQuery(telegram_id: String) {
    query: @file("assets/sql/spend_credit.sql")
    account: self.db
    telegram_id: self.user
  }

  read = ExecPython(rows: List[JsonDict]) -> (paid: Boolean, refusal: String) {
    code: @file("assets/scripts/outcome.py")
    rows: debit.rows
  }

  self.paid = read.paid
  self.refusal = read.refusal
}
credit.db = pg.access
credit.user = ask.user

self is the group’s own interface. On the right of an arrow it means the values coming in from outside; on the left it means the values going out. It is always the innermost scope, so inside a loop inside a group, self is the loop.

Set the group’s inputs from outside, on its name, as credit.db does. You cannot write a literal onto self.port: a group’s input is given its value from outside. The one exception is a metadata port, whose value you write in the body.

A plain comment as the first thing in the body becomes the group’s description, which is what the graph shows when it is folded shut.

No node stands for a group when the program runs

A wire through a group’s ports is one wire, from the node that sends to the node that reads, and the group’s ports change nothing on the way. The group itself is a scope: the runtime decides, once for each copy of it (one per iteration of a loop around it, one per @include of a file), whether it opens or skips, and everything inside follows.

So folding a group in the editor costs nothing, and neither does nesting five deep.

When a group starts

A group with a gate wired to it (_should_flow or _should_not_flow) waits for that value and opens or skips on what it says. One with a gate written in its braces decides at once. One with no gate opens on the first value that reaches any node inside it from outside, or at once when nothing comes in from outside; if every wire coming in closes with nothing on it, it skips. An included file is a group, so each @include starts the same way.

When it opens, every node inside that no wire feeds starts with it. So a node with no inputs needs no _should_flow to get its turn. Every other node inside waits on its own inputs, and every output leaves the moment it is made.

It only runs in a run that takes it along, though. A trigger’s run holds what the trigger feeds plus what those nodes read, so a node with no inputs inside a group comes along when something that run uses reads it, or when the run feeds the group’s _should_flow, which brings the whole group in. If several routes feed one include, a route that did not fire never holds it up: it is either left out of the run, or it runs only to close its outputs, and a closure counts as arrived.

A group input passes through

This is the part that surprises people.

You give a group a db: Access[postgres] input, then the thing feeding it closes. You would expect the whole group to skip.

It does not. A group input holds nothing: whatever reaches it, a value or a closure, goes straight inside, and whichever node actually needed that value skips there, and the skip cascades from that node outward. Without a gate, the whole group skips only when every wire coming into it closes with nothing on it.

That is deliberate. A group is usually several jobs, and one missing input often only kills one of them. Skipping the whole group would throw away work that had everything it needed.

So a group input is never required or optional itself, and a ? on one is refused with optional-pass-through-port. The editor draws these ports with their own marker, a ring with a dot in the middle. Whether a node runs without the value is said on that node’s own input. It also means @require_one_of is refused on a group: put it on the node inside that needs one of those values.

A loop is the exception, for the ports it iterates or threads: with no list to walk, there is no iteration to launch. Those ports keep their ?, and every other port of a loop passes through like a group’s.

When a group input has to be connected

What the compiler checks is whether a node inside needs the port.

It follows the port inward, through any group, loop or included file nested behind it, until it reaches the nodes that read it. If one of them takes it into an input it needs (one written without ?, see optional and required inputs; a default does not help, since it only fills an input no wire reaches, and an input of a join node such as FirstInOrder is optional without any ?), or into the only member of a @require_one_of set that could get a value, and nothing outside connects or writes the group’s port, the build fails with required-port-unmet, naming both ends:

input 'g.b' has nothing connected, and inside it feeds 'g.f.y', a required
input, so 'g.b' is required too: wire or write it

A port that only inputs written with ? read may stay unconnected: the closure goes inside and each of them handles it the way it handles any closure. An included file’s ports and a loop’s other ports follow the same rule.

Skipping the whole thing

_should_flow goes inside the braces, and when it skips a group it skips everything in it, however deep, including nested groups. One line guards a whole subgraph.

brief = Group(request: String) -> (prompt: String) {
  write = Format(request: String) {
    template: "Draw this: {{request}}"
    request: self.request
  }
  self.prompt = write.text
}
brief.request = ask.text
brief._should_flow = credit.paid

The gate is consumed at the boundary. The nodes inside never see it, and they do not each get to decide: they take the group’s decision as a whole.

Only the incoming side takes a gate. The outgoing side has nothing to decide, because a group that did not run has nothing to forward.

What crosses the boundary

A stream is a live edge between two running nodes, so both ends have to be in the same scope. If you need a stream to cross, either move the consumer in, or have a node read the stream and emit ordinary values. A loop is the one thing that takes a stream across its edge, through its own over.

That last row is the scope-reachability error. A value crossing the line has to appear on the interface, where somebody reading the group can see it.

Metadata ports

Say a group is a tool a model can call. The model has to be told about the tool (its name, what it does, what arguments it takes) before it runs, and the group only runs once the model has asked for it. The description belongs to the group, but the node that needs it sits before the group in the graph. An ordinary wire from the group back to the model would be a cycle.

A metadata port holds a value you write in the program, which no run computes. You declare one among the group’s outputs with a * before its name, and write its value in the body, on self:

search = Group(query: String) -> (results: String, *tool: { name: String, description: String }) {
  self.tool = { "name": "search", "description": "Search the web." }
  echo = Text {}
  echo.value = self.query
  self.results = echo.value
}
search.query = "cats"
tools = List {}
tools.search = search.tool

The value is JSON, so its keys are quoted. The port needs a type, and the type cannot hold a type variable like T, because nothing wired to the port could tell what T stands for. (A tool a real model reads also needs parameters: see the LlmTool further down.)

A wire that leaves a metadata port is a metadata wire, and it never runs. When the program compiles, the compiler writes the value into the input the wire points at, as if you had typed tools.search = { "name": "search", ... } yourself. So search does not have to run for tools to have its value.

That is why a metadata wire may point backwards. This compiles, and with an ordinary wire from g into tools it would be a graph-cycle:

g = Group(items: List[{ name: String }]) -> (*tool: { name: String }) {
  self.tool = { "name": "g" }
  shown = Debug { data: self.items }
}
tools = List {}
tools.g = g.tool
g.items = tools.list

Where the value lands

The value ends up where the wire ends, and from there on it is a value you wrote:

• On a node’s input. The input takes the metadata port’s type, so in the first example the List’s output is List[{name: String, description: String}]. If the value does not fit the input, that is config-type-mismatch. If the input already has a value written on it, or a second metadata wire, that is double-driven-port. An input that takes only wires refuses it with input-accepts.
• On a group’s input, from outside (h.t = search.tool). The value is written on the group’s port, and the nodes inside that read self.t get it when the group opens, like any value written there.

If the wire reads one key of the value (search.tool.name), that key’s value is what gets written, and a key the value does not hold is deref-path.

Taking the value from other metadata ports

Instead of writing the value out, a group can take it from other metadata ports. Name one where a value goes, as member.port, and the compiler puts that port’s value there. A name reads the way it does where you write it: a member of the group first, else something of that name in an enclosing group, nearest first, else something at the top of the file. That is how a value gets out of a nested group:

outer = Group() -> (*tool: { name: String }) {
  inner = Group() -> (*tool: { name: String }) {
    self.tool = { "name": "deep" }
  }
  self.tool = inner.tool
}

A name can also sit inside the JSON, and inside a list ... puts a list’s items in place of the name, so a group can gather what its members describe:

toolbox = Group() -> (*tools: List[{ name: String }]) {
  one = Group() -> (*tools: List[{ name: String }]) {
    self.tools = [{ "name": "one" }, { "name": "uno" }]
  }
  two = Group() -> (*tool: { name: String }) {
    self.tool = { "name": "two" }
  }
  self.tools = [...one.tools, two.tool, { "name": "three" }]
}

toolbox.tools is the four tools, in that order. A name reads keys off a value the way a wire does (act.tools.anthropic), and ... on a value that is no list is type-mismatch. What comes out is held to the type the port declares, item by item, so one spliced item of another shape is config-type-mismatch.

Only another metadata port can fill one this way. If made is a node, self.tool = made.value is metadata-value-not-literal, because made.value only exists once the program runs. A name that is nothing declared is unknown-source-node, a port that member does not have is unknown-source-port, and two metadata ports that take their value from each other are metadata-reference-cycle. A group’s own ports are no value of its own: self.x inside the value is a parse error.

If you write a tool once in its own file and @include it in several places, every include hands out the same value, the one the file works out.

What is refused

• A metadata port with no value is metadata-port-not-written, and the message shows the line to add.
• A node inside the group cannot read the group’s own metadata port: shown.data = self.tool, written inside search, is metadata-port-read-inside. If a node inside needs the same value, write it on that node’s input too, or keep it on a member’s metadata port and name that port in both places.
• Nothing goes into a metadata port from outside. A wire into search.tool is metadata-port-as-target, and a value written there (search.tool = ...) is refused with the same message.
• The value cannot leave a group through an ordinary output: self.out = search.tool, where out has no *, is metadata-into-output. Declare out as a metadata port instead.

A few mistakes are caught while the file is read, and come back as a parse error: a * in the input list, a * on a node (a node type declares its own, in its metadata.json), a metadata port with no type or with a type variable, a metadata port with the name of an input or an output, two self.tool = ... lines for one port, a value written on a key of one (self.tool.name = ...), an inline node as a metadata port’s value (it computes its value during the run), and a value that does not read. For why a name may not repeat an input’s, go and read names you cannot use.

A model that calls tools

Here is one round of tool calls: the model is asked once, and each tool call it makes is answered. It compiles as written, with model standing in for whichever provider node you use. The loop runs once per call: because of over, self.calls holds one call each time round, and carry hands the conversation file from one call to the next. For how over and carry work, go and read Loops.

model = CustomProvider { baseUrl: "http://127.0.0.1:9/v1", model: "m" }

handle = Loop(calls: List[ToolCall]) -> (historyFile: File, *dogTool: LlmTool) {
  over: ["calls"]
  carry: ["historyFile"]
  dog = Group(call: ToolCall) -> (callId: String, result: String, *tool: LlmTool) {
    self.tool = { "name": "dogName", "description": "The dog's name.", "parameters": { "type": "object" } }
    work = ExecPython(call: ToolCall) -> (callId: String, name: String) {
      code: "return {'callId': call['id'], 'name': 'Biscuit'}"
    }
    work.call = self.call
    self.callId = work.callId
    self.result = work.name
  }
  self.dogTool = dog.tool
  route = Dispatch
  route.value = self.calls
  route.dog = dog.tool
  dog.call = route.dog
  unknown = Debug
  unknown.data = route.otherwise
  answer = ChatHistoryAppend { role: "tool" }
  answer.historyFile = self.historyFile
  answer.toolCallId = dog.callId
  answer.text = dog.result
  self.historyFile = answer.historyFile
}

tools = List
tools.dog = handle.dogTool

ask = LlmInference { prompt: "What is my dog's name?" }
ask.provider = model.provider
ask.tools = tools.list
handle.calls = ask.toolCalls
handle.historyFile = ask.historyFile
done = Debug { data: handle.historyFile }

The tool is the group dog. Its *tool port describes it as an LlmTool, { name: String, description?: String, parameters: JsonDict }, where parameters is a JSON Schema for the tool’s arguments ({ "type": "object" } is a tool that takes none). Each call the model makes is a ToolCall, { id: String, name: String, arguments: String }, with arguments holding the model’s JSON as text.

Three metadata wires carry that description. Two take it to the model: self.dogTool = dog.tool hands it out of the loop on the loop’s own metadata port, and tools.dog = handle.dogTool puts it in the List that feeds the model’s tools. The model runs before the loop, so that wire points backwards.

The third, route.dog = dog.tool, adds a branch named dog to the Dispatch node, which sends each call to the branch whose name matches the call’s. route.dog is written twice, and the two are different ports: on the left of = it is the branch’s input, which takes the description, and on the right (dog.call = route.dog) it is the output of the same name, which the compiler makes and which carries the calls that branch claims. A call that matches no branch leaves on route.otherwise. For how a node asks for that pairing, go and read pairsAddedPorts. The tool’s name is written once, on its own group, and both the model and the routing read it from there.

If you want a second tool, write a second group beside dog with its own *tool, add *catTool: LlmTool to the loop’s outputs, and give cat the same wires as dog: self.catTool = cat.tool fills that port, tools.cat = handle.catTool adds it to the List, route.cat = cat.tool adds its branch, and cat.call = route.cat takes its calls. answer would then get two wires into toolCallId and two into text, and an input takes one. So read the id straight off the call instead of dog.callId (answer.toolCallId = self.calls.id), and take whichever result came back with FirstInOrder (answer.text = FirstInOrder { dog: dog.result, cat: cat.result }.value).

For a model that keeps calling tools until it answers, this round goes inside a loop of turns that carries the conversation file. For that shape, read the LlmInference node’s description: weft describe-nodes --node LlmInference.

Names you cannot use

Group, Loop, LoopIn, LoopOut and self are the language’s. So is any name containing a double underscore, which is the compiler’s own separator.

A metadata port’s name may not be the name of an input or an output of the same group, so self.tool and search.tool only ever mean one port. An input and an output may still share a name.

Naming a group or a node after a node type is also refused, because Ticket.body would then read as an inline node rather than a reference. That is the reserved-name error.

How big a level should be

Six items on one level is what the language asks for. The compiler warns past fifteen, names the level, and tells you to group.

A group counts as one item on its parent’s level, whatever is inside it. So a program grows downward into nested folders rather than sideways into a wall, and every level stays something you can hold in your head.

A file’s top level is counted per connected part. Everything a wire links counts together, a database or a key set that several pieces use included, so the warning reads “one connected part of the top level holds N items”. Only pieces that share no wire at all are counted apart. The inside of a group, a loop and an included file is counted whole (“this included file holds N items”).

Loops

A loop runs what is inside it once per item of a list, or until the body says stop.

grade = Loop(cards: List[JsonDict], rubric: String, provider: LlmProvider) -> (scores: List[Number | Null]) {
  over: ["cards"]

  ask = Format(card: JsonDict, rubric: String) {
    template: "{{rubric}}\n\nThe card: {{card}}\n\nAnswer with one number."
    card: self.cards
    rubric: self.rubric
  }
  mark = LlmInference {
    prompt: ask.text
    provider: self.provider
  }
  self.scores = Cast { value: mark.response }.value
}
grade.cards = pull.rows
grade.rubric = "Score this flashcard from 0 to 10 for clarity."
grade.provider = model.provider

Unlike a group, a loop becomes nodes: the compiler turns it into a LoopIn and a LoopOut, and the runtime drives the iterations between them.

The five settings

They go in the body as ordinary lines. Anything else starting with a letter is a node, and anything else that looks like a setting is a hard error, because a typo like maxItres: 10 silently running your loop uncapped is exactly what the language refuses to allow.

The four kinds of port

Which kind a port is depends on where it is and whether you named it.

A gathered output has to allow null, because an iteration that sends nothing on it (it failed, or a branch inside it was not taken) leaves a null in its slot. If you declare it without | Null, the build stops with gather-output-must-be-nullable.

The list that comes out is built for every gathered port, even one that no iteration ever wrote, because a port that produces nothing at all would leave whatever is downstream waiting forever. A port nothing inside the loop writes at all is refused when you build (loop-output-unwritten): it could only gather nulls.

A carried value that an iteration does not write keeps what it had, as long as nothing broke: a branch not taken or a gate that said no is fine.

A carried value needs a seed from outside, wired or written (myLoop.total = 0 for a loop named myLoop); without one, the build fails with required input 'myLoop.total' has no driver. The one case it can go without: you declare it among the loop’s inputs with a ? (total?: Number) and nothing inside wires it into an input written without ?. Then it starts at the zero for its type: 0 for a number, "" for a string, false for a boolean, [] for a list, {} for a dict, and null for a type with no empty value, such as a File or an Image. A seed that is wired but arrives as null starts at the zero too, and for a type like Number | Null that zero is 0, not null.

A loop can also declare a metadata port (*tool: LlmTool), which is none of the four: it holds one value written in the program, never a list.

Two implicit ports

self.index is a Number, readable inside, and it is which iteration you are in, counting from zero.

self.done is a Boolean you can write inside, and it is how the body votes to stop.

Both only appear if you did not declare a port of that name yourself. And index as an input name, or done as an output name, is the reserved-port-name error.

One at a time, or all at once

Sequential is the default. The next iteration launches once this one’s values reach the loop’s edge: its carried values, what it gathers, and its self.done. That is what makes carry possible: the next iteration reads the value the last one wrote. Nothing else holds the next iteration back, so a loop with no outputs launches its iterations back to back. If one item’s work has to finish before the next item starts (a database write the next item reads), carry a value out of that work into the next iteration.

A loop launches its iterations and does not own them. Work inside an iteration that does not feed the loop’s edge keeps running after the loop has moved on, and after the loop has ended. That is what lets a loop start twenty agents, each holding a bus, gather the buses and exit, so the nodes after the loop can talk to every agent while they all keep running.

parallel: true launches every iteration up front. Three things it refuses:

• with carry, because carrying means each turn feeds the next, and that is sequential by definition
• without over, because there is nothing to spread out
• with self.done, because a vote to stop means nothing when everything already started

How a loop ends

• It runs out of items in over.
• It hits maxIters.
• The body writes self.done = true, on a sequential loop.
• A carried value is lost to a failure, and then the loop fails (see below).

A sequential loop with none of those is the loop-unbounded-no-termination error, refused at compile time rather than left to run forever.

With several over lists of different lengths, the default trims to the shortest. Set trimOnMismatch: false and a mismatch fails the run instead, naming the lengths.

When an iteration fails

If you only gather, the run carries on. That iteration’s slot in every gathered list is null, so a loop over a hundred rows where three fail gives you a hundred slots with three nulls in them. Whatever reads that list decides what a null means.

If the failure means a carried value never got written, the loop stops there and fails. The next iteration would start from the same value and meet the same failure: an agent loop whose model call broke would otherwise pay for the same doomed call up to maxIters times, then hand on a stale history as if all went well. The loop fails with

loop 'agent' stopped at iteration 4: its carried value 'history' could not be updated because 'ask' failed: <the error>

where ask is the node that actually broke, even when other nodes between it and the loop’s end skipped because of it. Everything reading the loop’s outputs sees a failure, the same as for any failed node, and ask shows as failed in that iteration too.

A carried value that closed with no failure behind it, because a branch was not taken or a gate said no, still keeps what it had.

What cannot go in one

A trigger and an infra node are both refused inside a loop, with trigger-in-loop and infra-in-loop. A trigger registers once for the project, and infrastructure is provisioned once for the project, so a per-iteration one is not a thing.

Running part of its body

If you want to prove one stage of a loop’s body without running the loop over every item, run that stage on its own. Every way of cutting a run (--group, --from, --emit, --target, --before, --feed) works inside a body, loops inside loops included. Say the loop clips runs a group edit on each item, reading the item and self.index, then caption and upper after it:

weft run --from 'clips.edit={"clip": "intro.mp4", "at": 0}' --target clips.upper

The part you pick runs once, as if it were the first time round: inside iteration 0 of each loop around it, so weft runs, weft events and the graph show its nodes at #0. Nothing of those loops runs: no other iteration, and nothing reaches the loop’s outputs. A loop that sits wholly inside the part you picked runs normally, every iteration of it.

What the loop would have handed the part (the item, self.index, a carried value) is a value from outside the run like any other: you hand it at the start, as edit’s clip and at above, or the run is refused before it starts, naming the input that would get nothing.

What is refused is cutting a loop in half. A loop has two ends, its start (where its inputs go in) and its end (where its outputs come out), and a run holds both or neither. Ending the run inside the body with nothing started there reaches back to the loop’s start for the item:

the run holds loop 'clips''s start but not its end: include both to run the loop, or neither to run part of its body

Starting inside the body with no end there reaches the loop’s outputs, which runs the loop whole, every iteration, around a start that cannot apply to all of them:

'clips.edit' is inside loop 'clips', and the run holds both of the loop's ends, so it runs the loop
whole: a run cannot start, stand in or stop inside a loop it runs whole. To run part of the loop's
body, end the run inside the body too (--target a node in it), so the run holds neither end; to run
the loop, start or end at the loop

In both cases you either start and end inside the body, or run the whole loop.

A loop in a file you include at several places is one loop at all of them, so one run takes it the same way everywhere: whole at every place it holds it, or part of its body at every place. A run that holds all of it at one place and part of its body at another is refused, naming both; run them in two runs.

Streams and buses

Most wires carry one value. Two things carry more than one, and they are for different jobs.

A stream is one node handing items to one other node, in order, until it ends: the numbers Range counts out, or the messages a Socket hands on as its caller sends them.

A bus is several nodes that are all running at once talking to each other: a model writing its answer, a Stream passing the words to the caller, and a voice reading them aloud as they come.

Streams

A stream is a port typed Generator[T]. Range hands out numbers that way, and a loop over it takes one per iteration:

numbers = Range { to: 1000 }
double = Loop(n: Generator[Number]) -> (doubled: List[Number | Null]) {
  over: ["n"]
  times = ExecPython(n: Number) -> (out: Number) {
    n: self.n
    code: "return {'out': n * 2}"
  }
  self.doubled = times.out
}
double.n = numbers.values

The | Null is required, because an iteration that sends nothing leaves a null in its place in the list. For the other kinds of loop port, go and read the four kinds of port.

Items travel as ordinary pulses, each checked against the element type. The consumer starts when the first item arrives and pulls the rest as it goes, so it is running while the producer is still producing.

A closure on a stream is its end, not a skip. This is the one place where a closed wire does not make the consumer skip. It runs, sees the stream is over, and acts on it. A stream that carried nothing is an empty stream, which is a result, not an absence: zero rows has to behave like one row, not like a branch that never happened.

If the producer failed, the consumer finds out through an error rather than a clean end, so nothing mistakes a broken stream for an empty one.

What a stream will not do

A producer that runs far ahead of its consumer will fill the buffer: 4096 un-taken items, and then it fails and tells you the three ways out, which are to yield instead of pulse so each item waits to be taken, to let the consumer catch up, or to raise the cap.

Buses

A bus is a channel any number of nodes join. One node makes it and emits a marker, and anything that gets the marker can join.

ask = Route -> (body: { question: String }) { path: "ask", method: "POST" }
answer = LlmStream {
  prompt: ask.body.question
  provider: model.provider
}
toCaller = Stream { bus: answer.stream }
voice = ElevenLabsSpeak {
  account: eleven.access
  text: answer.stream
  voice: "JBFqnCBsd6RMkjVDRZzb"
}

LlmStream makes the bus and sends the model’s answer on it as it is written. Stream passes it to the caller, and at the same time ElevenLabsSpeak turns the same words into audio on its own audio bus (its voice is an ElevenLabs voice id). model and eleven are the model and the ElevenLabs connection, set up elsewhere in the program.

The marker is an ordinary value. It crosses group boundaries, goes into loop bodies, sits inside records, and travels like anything else. Only the live channel is special, and it lives in the worker rather than on the wire.

Every participant registers a name, which is the stamp on everything it sends and what other nodes wait for. Registering is the “I am here and ready” moment, so a node with a slow warmup holds the bus and registers when it is genuinely ready rather than when it starts.

Each reader has its own position. Reading does not consume, so ten readers all see everything.

Two modes

Ephemeral is for a firehose. Video frames should not stall because something downstream is slow, and they should not end up in permanent storage either.

A node that streams lets you pick the mode with two settings: journalEphemeral (on keeps payloads out of the record, off by default) and journalWindowMs (a whole number from 100 to 60000, 1000 by default). Every message sent within one window lands in the same row of the record. A shorter window shows messages in the inspector sooner and gives a row per message on a slow stream. A longer one writes fewer rows for a fast stream (audio frames, tokens), and the inspector trails the live stream by up to that long. A row also closes early once it holds 2 MB, and at once when the bus ends or the run pauses. Route and Socket have both settings, and so do LlmStream, ElevenLabsTranscribe and PostgresWatchQuery. Other nodes have them only if their author turned them on.

The window is 64 messages either way. What is always kept, in both modes, is who joined and who left, so nothing a reader needs can disappear into a gap.

The record exists so you can read the conversation in the inspector afterwards, and so a paused run gets its buses back: the worker that picks the run up opens each one again from it (below).

How a bus ends

Picture a reader at the end of a model’s answer. Did the model finish, or did it stop halfway through a sentence? A bus says which. It ends when the node that made it is done, or when a node that joined it is, and it ends one of two ways:

• finished, when that node’s work completed, or when the node closed the bus early on purpose;
• failed, with the reason, when that node failed or was cancelled. weft also ends a bus failed when the run got stuck, when it ended while the bus was still open, and when a node was still running as its worker died.

Each reader decides what a failed end means for it. Stream fails the answer to its caller (what the caller sees), even on a route whose whenChunkFails is drop_chunk, because that setting skips one message and a failed bus has no next one to go on to. Debug logs a warning naming the reason, and the bus’s panel in the inspector ends with * the bus failed here: <reason> instead of * the bus closed here.

If a producer fails before its first piece, it may not have opened its bus yet. For what the program can do then, go and read when a node fails.

A bus pauses with its run

A bus is memory in the worker running the run, and it does not stop the run from pausing. A node can wait a week on a question while a bus between two other nodes stays open: once every node still running waits, the run pauses, buses and all, and the worker lets go. Nobody on the bus sees anybody leave.

When the run picks up, the new worker opens every bus that was open again, with the same id, so every marker still names it, and its messages carry on numbering from where they stopped. A journaled bus comes back with its last JSON messages, as many as its window holds, so a reader can still reach back; the record keeps a message over 100 KB trimmed, so that message and every one before it are left out. An ephemeral bus, or one that carries bytes, comes back empty. A reader that was waiting for the next message had read everything and loses nothing. One that stopped to wait on something else carries on where it stopped, and if the messages it had not read did not come back, its first read fails, saying so. A node that must not stop reading at all holds the run instead (ctx.hold()), which keeps the run from pausing while it reads.

A worker that dies is different, because the last messages it carried may never have reached the record. If a durable run carries on in another worker and any node was still running when the first one went, each bus that was open ends failed, with the worker holding this bus went away, so messages it carried may be lost.

A seeded run cannot reuse a node that emitted a bus, since that bus belonged to the earlier run: weft leaves the producer and its readers out rather than handing you a marker pointing at nothing.

What a bus does not check

Payloads. A stream checks every item against its element type; a bus carries whatever you send. You pick JSON or bytes when you make it and that is frozen, but what is inside is between the nodes talking.

Which one

For the Rust on both sides, go and read streams and buses in Rust.

Triggers and routes

A trigger is how a program starts without you. A message arriving, a schedule coming round, a form somebody fills in, a request hitting an address.

ask = TelegramReceiveMessage { account: telegram.access }

Wire it like anything else. What comes out of it is the event.

Nothing listens until you run weft activate. Go and read the three lifecycles for why that is its own step.

What a run started by a trigger covers

Everything downstream of the trigger that fired, plus whatever that work needs upstream. Any other trigger in the project closes its outputs, so paths that needed it skip.

A trigger’s inputs are frozen

Whatever fed a trigger’s ports when you activated is what it uses on every firing. The nodes upstream do not run again per event.

Everything upstream of every trigger runs at activation as one program, so two nodes that do not depend on each other run at the same time. Setup that several triggers share, like the schema all their tables live in, is written once and wired to each of them; two copies of create extension if not exists racing each other is how one of them fails on a duplicate key.

If you want something done once before the triggers listen, like creating the table they write to, wire it in front of them. A gate is enough, since any value but false lets the trigger through:

pg = PostgresDatabase {}

schema = PostgresExecuteQuery {
  account: pg.access
  query: "create table if not exists cards (id text primary key, title text)"
}

add = Route { path: "cards", method: "POST" }
add._should_flow = schema.rows

list = Route { path: "cards", method: "GET" }
list._should_flow = schema.rows

schema runs once, at weft activate, before either route listens, and if it fails the activation is cancelled. A request never runs it again.

So after changing anything in front of a trigger, weft resync. Until then weft status shows the trigger as behind, and your listener carries on with what it registered. weft tells you when a bake is stale:

the code changed since trigger 'inbound' was last prepared, so its bake is
stale. Prepare it again: `weft bake` does it and changes nothing that listens;
if the trigger is off, `weft activate` does it and turns it on; if it is on,
`weft resync` brings it onto the new build and prepares it there

Answering on a URL

Route claims an address and starts a run when somebody calls it.

type Card = { title: String, color?: String }

post = Route -> (body: Card) {
  path: "cards"
  method: "POST"
}

answer = JsonObject {
  title: post.body.title
  status: "saved"
}

reply = Reply { body: answer.object }

The caller is held open while your program works, and Reply is what answers them. For streaming an answer as it is produced, and for the Rust side, go and read talking to a live caller.

If only some callers may call it, set its auth (auth: "api_keys", say) and pick the connection holding the keys with weft connect post. For every scheme, go and read checking a signed request.

The request’s body comes out whole on body. Left undeclared, it is a JsonDict. If you declare a type on it, as Card above, a call whose body does not fit is answered 400 naming what is wrong, and no node after post runs. A body carrying a key that Card does not declare is answered 400 too. If callers may send more than you read, end the type with ..; for what that does, go and read what fits into what. If callers send JSON of any shape, a list or a bare number as well as an object, declare -> (body: Json). A request with no body, like a GET, closes body, whatever the route’s dataType. A json body that is null is a value: it comes out on a body whose type takes Null (Json does), and closes body on any other, the way a null counts as nothing on a port that does not take it.

If you want part of the path as a value, capture it with {name} and declare an output of the same name:

card = Route -> (id: String) {
  path: "cards/{id}"
  method: "GET"
}

A call to cards/42 puts "42" on card.id. Every other output you add to a Route has to be a capture of its path, typed String, or the build stops with route-output-not-a-capture. A capture can’t share a name with one of Route’s own outputs (body, method, path, query, headers, credentials, caller, fired), so cards/{body} is the route-capture-shadows-output error, asking you to rename the capture.

A caller’s credentials come out on credentials, never on headers. The headers that carry one (authorization, proxy-authorization, cookie, weft-instance-token, and any header the route’s auth reads, like the X-Api-Key that auth: "api_keys" checks) are each made a secret the moment the call arrives, before anything of the run is written, so the run’s record, the inspector, weft events and search hold a marker in their place and never the value. The value is still there for the run, and for the same run picked up after a pause. If you want to pass them on, wire them into a port that takes secrets, like an HttpRequest’s headers, which sends them revealed. Here a route hands its caller’s credentials on to your own backend:

me = Route { path: "me", method: "GET" }
profile = HttpRequest {
  url: "https://api.internal.example/me"
  method: "GET"
}
profile.headers = me.credentials

A plain String port refuses a secret: wired into a Dict[String, String], me.credentials is a type-mismatch telling you the node has to take the secret and reveal it. For what a secret is, go and read secrets.

Two routes that one call could reach, where neither is more specific, is an error. cards/count beside cards/{id} is fine, because the first is more specific. Two spellings that genuinely overlap are the route-overlap error, because a call arriving would have no defined answer.

You know a route’s address before you activate: on your machine it is http://127.0.0.1:14111/connect/local/<project id>/cards (the install’s address, then /connect/local/, then your project’s id, then the path). The project id is the id under [package] in your weft.toml, so it is the same on every install, and two projects can each serve a cards route without getting in each other’s way. On a cloud install it is the install’s own address, then /connect/local/<project id>/, then the path. weft activate prints the id (activated cards (<project id>)), and the route’s trigger shows its full address in the editor.

If you want the fastest way in, or a frontend wants your routes at the root of an address, call the project’s own address, where your program answers with nothing of weft’s in between. On your machine that is a free port the project gets the first time you activate it and keeps from then on (http://127.0.0.1:14200/cards); if another program takes that port, the project moves to another free one. On a cloud install it is the project’s own Cloud Run address. On your machine, if you want a port of your choosing, weft activate --port 8080 opens that one, and the project keeps it for later activates. If another program or another of your projects holds that port, weft activate fails and nothing is activated. weft activate prints the address, and weft status shows it later or says why it is unavailable. Your routes keep answering under /connect/local/<project id>/ as well.

If a call arrives while the route’s trigger is down or still being set up, it does not wait for the trigger: it is answered 503 at once, with a Retry-After of 5 seconds, so a client that retries gets through once the trigger is back on. The exception is a trigger taken down with weft deactivate --door refuse --held drop, which takes its route away with it, so a call is answered 404, the same as a call to a path no route serves. For what a take-down does with other work, like a webhook or a form, go and read starting and stopping things.

How a run is kept

Your runs happen inside a worker: a copy of your compiled program, running as a process on your machine, or as a Cloud Run service on a cloud install. A worker keeps the runs it is working on in its memory. A trigger has inputs that decide what happens to those runs: whether they survive their worker dying, whether they are written down, how long they are kept once they end, and how long a wait holds when the run cannot pause. You write them in the trigger’s braces like any other input:

pay = Route -> (body: JsonDict) {
  path: "pay"
  method: "POST"
  durable: true
}

By default (durable off), a run is fast: it only waits for the database when it has to. That is when it pauses (a timer, a form), and in a few other places (for the full list, go and read when a run waits for its writes). The rest of the time its work lives in the worker’s memory, and its record (the journal that weft events and the editor read) is written a moment behind it, as it goes. If its worker dies, the run ends cancelled and is not run again. For why, and for what happens when the platform shuts a worker down on purpose, go and read what happens when something dies.

If a run must not end when its worker dies (it moves money, say), turn durable on. Before each node starts, everything the run did so far is written to the database, and a route’s answer is written before it is sent. The exception is a pure node (Text, JsonObject, Switch, Reply), which does nothing outside the run but answer its caller and handle the run’s own files, and starts without waiting.

If the worker dies mid-run, another worker picks the run up where it stopped: every finished node stays finished, and a node that was in the middle of its work is failed with a message saying it may have partly happened, so you know which node to check. Two kinds of node run again instead: one that saved a state (ctx.keep), from its last save, and a pure node that takes no stream and had not passed anything on yet. If a caller started the run, its connection was on the old worker and is gone: the run carries on in the new worker with nobody on the line, so a node that answers the caller fails, saying no live caller is attached. If the platform stops the worker instead, a run that can pause gets 5 seconds for the nodes already running to finish, and a node still running after that runs again from its last save if it saved a state, or is failed if it did not. A run that cannot pause (below) keeps running on the stopping worker for as long as the platform lets it, and if the worker goes before the run ends, that is the same as the worker dying. If you want to know what a wired _error does with that failure, or what happens to a node that was waiting on an answer or reading a stream, go and read surviving a restart.

Even with durable off, a paused run survives its worker. A run that cannot pause is the exception, below.

When a run pauses

A run pauses in one way: every node running in it waits (on a timer, a form, a message, a bus or a stream), at least one of those waits needs an answer from outside, and the run has stayed like that for the trigger’s pauseAfterSecs (10 seconds unless it says otherwise). Then every node saves where it is, all together, the record is written, and the worker lets go.

During those seconds each wait stays open in its node. If its answer arrives, it goes straight into the node, which carries on from that very line: nothing pauses and nothing starts again. So a run fed by a steady trickle of messages is not paused and picked up again for every one of them. Each time it goes quiet again, the count starts over. With pauseAfterSecs: 0 it pauses as soon as everything waits.

The run does not stay when weft needs it off its worker: if the worker is stopping, or the run has to move to a fresh one, it pauses straight away and the next worker picks it up. On a cloud install it also never stays past its hour on the worker, since reaching that would end it.

When a run cannot pause

Two kinds of run cannot pause: one whose caller is still on the line (the caller cannot follow it to another worker, whatever outlivesCaller says), and one with recorded off (there is no record to pick it back up from). A node test cannot pause either, since it has no program for another worker to pick up.

When such a run reaches a timer or a form, the wait holds in the node’s call for as long as it needs. The wait is registered as usual, the run stays on its worker, and the answer carries it on right there. The hold clock only runs while the run is quiet, meaning every node still running is waiting, on an answer or on a bus, and never while a caller is on the line. Anything that moves (a bus message, a node finishing) starts it over. If the run stays quiet for holdSecs (60 seconds unless the trigger says otherwise), the call that was waiting fails, saying it gave up, and the wait is withdrawn, so a form is no longer offered. The node’s code can handle that error like any other, and if it does not, the program can: it comes out on the node’s _error when that is wired (when a node fails). With holdSecs: 0, such a wait fails at once.

A node that holds the run (its code called ctx.hold(), because its work cannot be picked up from the middle) works differently. While it holds, none of its waits pauses, a timer or a form as much as a read, and the run keeps its worker as a run that cannot pause does: for as long as a caller is on the line, otherwise until nothing has moved in it for holdSecs, when the waiting call gives up with WaitGaveUp, saying the node holds its run. The other nodes’ waits stay open in their calls meanwhile.

If the run becomes able to pause while a wait holds (its caller hangs up, on a route with outlivesCaller on), it pauses the way any other run does, once it has been quiet for its pauseAfterSecs. A run whose caller leaves while outlivesCaller is off is cancelled, as always. And a fast run holding a wait still ends with its worker.

If a page asks a route for a status every few seconds, turn recorded off, or weft runs fills with hundreds of runs. weft keeps no history of such a run, not even in its worker’s memory. If it fails, weft runs lists it with the node that failed and why, and nothing of what ran before. If it reports a cost, or asks weft for something on its behalf that its worker does not already hold (a stored file, a new connection or infrastructure address, a task such as starting or stopping its infra, a stop through ctx.stop_tagged, a tag through ctx.tag_run, a wait on a timer or a form), it is listed with its costs and how it ended. Otherwise it leaves nothing. If you want to check that a trigger with recorded off is being called at all, weft status shows how many runs each trigger started in the last minute or two, and how many of them failed.

If you only want a key kept out of the record, you do not need recorded off. A value that arrives as a secret (a caller’s credentials, a node’s Secret output, an ExecPython output you declared Secret[String]) is already kept out. For more, go and read secrets.

An unrecorded run cannot pause, so a timer or a form in it holds (when a run cannot pause). A tag works on it (a label you later find or stop runs by, ctx.tag_run): the run is listed, as above, and a stop by that tag reaches it while it runs. The compiler also refuses durable: true with recorded: false.

On a cloud install, one stretch of a run lasts an hour at most. Cloud Run cuts a request at 60 minutes, so a run stops itself 59 minutes after it started on its worker. It ends cancelled with a message saying so, instead of being cut off while a node is still running, with no ending written. A run that pauses starts a fresh hour when it picks back up; one branch waiting while another runs does not. So if a job can take longer than an hour, split it with a pause. On your machine no run is cut.

A run that answers a caller lives on the worker the caller reached, and stays there while the caller is on the line. If the caller is still there at 59 minutes, the route’s outlivesCaller decides. Off, the run stops, with a message telling you to have the client reconnect. On, the run moves to a fresh worker, with a fresh hour. It starts no new node, and the nodes it is running get 5 seconds to end, while the caller’s connection stays open for what they still send. Once they have ended, or the 5 seconds are up, the caller gets a 504 with the usual failure (Something went wrong and the run id; a socket closes with 1011), and the run carries on in the fresh worker. Why goes on the run’s record, where weft logs <run id> shows it: this connection ended 60 seconds before the 60 minute limit this platform puts on one connection; run <id> goes on without it (its route outlives its caller), so reconnect to talk to the program again. A node still running after the 5 seconds stops where it is, and the worker that picks the run up runs it again from its saved state, or fails it as cut short if it keeps none.

Once the caller has gone, a route with outlivesCaller on keeps its run going. It pauses if everything in it is waiting, and otherwise, on a cloud install, it moves: it starts no new node on that worker, and once the nodes it was running end or settle into a wait, it carries on under a call weft holds open for it, with a fresh hour. Buses between its nodes come along: the worker that picks it up opens them again where they stopped. Moving works from the run’s record, so the compiler refuses outlivesCaller: true with recorded: false.

When a run ends before it answers

Every answer a route’s run gives, good or bad, carries a Weft-Run-Id header holding the run’s id.

If a run ends before it has finished answering its caller, the caller gets one of these statuses instead, and this JSON body:

{"error": "Something went wrong", "runId": "9b81d0a2-..."}

A 504 means one of four limits ran out: on a cloud install, the run’s hour; the route’s or socket’s maxSessionSecs (the longest one connection may stay open, off unless you set it); a wait that held for its whole holdSecs; or, on a cloud install, the hour a worker’s connection to weft may last, when it runs out while every run on that worker only waits (for why, go and read the broker).

The caller never sees why the run ended: the reason can name your nodes, your files and a provider’s words, and those are yours to read. The whole reason stays on the run’s record, and you open it with weft logs <run id> or in the graph. The id is safe to hand out, because opening a run takes your own credential. If you want a caller to get a message of your own instead, wire _error on the nodes that may fail and gate a Reply of yours on it; the run then no longer fails (when a node fails).

A 503 here carries no Retry-After, because calling again would start a second run beside the one that may still be going. If the answer had already started, its status was already sent, so the error comes at the end of the body instead, in the answer’s own format:

A socket closes with 1011 where a call would get 500 or 504, and with 1013 where it would get 503, and the close reason is that same Something went wrong (run <id>).

A Stream answers this way too when the bus it reads ended failed: a 500 if nothing was sent yet, the marker above if it was, 1011 on a socket. Its done output then stays absent.

Answering on a socket

Socket is the same idea for a WebSocket: the caller connects, your program runs, and the two talk until one of them stops.

A client that can send headers (a server, a script, an app) opens its socket at the route’s address and is checked like any other call. A browser can’t put a credential on a socket’s opening request, so on a route that checks callers it asks first with a plain GET, which carries the credential, and gets back {"url": "...", "protocol": "websocket"}; it opens its socket at that url within a couple of minutes.

On a cloud install, one connection lasts an hour at most. Google cuts any request to weft at 60 minutes, and an open socket is one long request, so a socket (or a streaming answer) that is still open then is closed. A connection can also drop sooner for ordinary reasons: a phone changing networks, a laptop going to sleep. When it does, the route’s outlivesCaller decides what happens to the run: off (the default), the run stops; on, it carries on and what it sends goes nowhere.

So if you want a conversation to last longer than one connection, keep what it needs outside the run, and have the client reconnect:

• the client picks a session id once (or the program hands it one in its first message) and sends it on every connection, as a query parameter or in the first message;
• the program keeps the conversation’s state in its own storage, keyed by that id (a table in the project’s Postgres, a file), and reads it back when a connection arrives with an id it knows;
• the client reconnects whenever its socket closes, with the same id.

Each connection is then its own run, and losing one, at the hour or before, loses nothing the conversation needs. If your client is a web page, the connect library’s openLiveSocket does the client’s half: it keeps the session id, sends it as the session query parameter on every connection (your program reads it off the trigger’s query port), and reconnects until the page closes the socket, your program closes it with code 4000, which means the conversation is over (a run that simply ends closes with 1000, and that ends only its connection), or, when the page passes credentials, the route refuses them. A browser is told nothing about a socket refused at its opening (it sees only that it closed), so a socket opened without credentials keeps trying, at most every 15 seconds.

Watching a folder

If you want a run each time a file lands in a folder on your machine (a scan, a download, an export from another program), use FolderWatch:

invoice = FolderWatch {
  folder: "/home/me/Invoices"
  pattern: "*.pdf"
  events: ["created"]
}

Each run gets the file’s absolute path on invoice.path, what happened to it on invoice.event (created, changed or removed), and its size on invoice.sizeBytes, which is absent for a removed file. The worker runs on the same machine, so a node downstream opens the path itself.

folder has to be an absolute path to a folder that exists when you run weft activate. recursive: true watches the folders under it too, however deep. pattern matches the file’s name only (*.{pdf,docx} for either). If you leave events out, all three fire.

A save or a slow copy that writes one file many times starts one run, sent once the file has been quiet for a second. To decide what happened, weft compares the file with what it last saw rather than trusting the operating system’s event, because systems report a save differently: as a write, as a rename over the old file, or as a removal followed by a creation.

weft keeps what it last saw in its database, so a file that arrives, changes or goes while weft is stopped, while it is in maintenance for an update, or while your machine is off still fires once the trigger is back up, the same as if weft had been watching. While you have the trigger down behind a door that takes or hides, weft keeps watching, and what fires waits for the trigger to be back on. Behind a door that refuses, or once a door’s --door-for window ended, nothing is watched: what happened in the folder meanwhile never fires, and turning the trigger back on starts it as if for the first time. A poll keeps its place in its feed by the same rule; for the rule itself, go and read taking triggers down.

The first time the trigger starts, the files already in the folder fire nothing. Changing folder, pattern or recursive counts as a first time; changing events does not. If weft stops just after a file’s run started and before it wrote that down, that file fires once more when weft is back. If a file’s run could not be handed over at all, weft offers it again the next time that file changes or the trigger starts.

It only works on a local install, since that is where your folders are. On a cloud install, weft activate refuses it, with a message that starts a folder watch needs the install to run on the machine the folder is on. On WSL, a folder under /mnt/<drive> is refused too, because Windows tells Linux nothing about the changes made there: move it under ~/.

Slow callers and messages that cannot be made

Picture a live price page streaming from a Route, and a phone on a bad connection reading it. Your program writes faster than the phone reads, so messages pile up for it. Up to 256 wait; past that, the route’s whenCallerIsSlow decides what gives:

db = PostgresDatabase { database: "shop" }

prices = Route -> (symbol: String) {
  path: "prices/{symbol}"
  method: "GET"
  whenCallerIsSlow: "drop_oldest"
}
latest = PostgresWatchQuery(symbol: String) {
  account: db.access
  symbol: prices.symbol
  query: "SELECT price FROM quote WHERE symbol = $symbol"
  channel: "quote_changed"
}
feed = Stream { format: "ndjson", bus: latest.row }

The other setting, whenChunkFails, is for a message your program cannot turn into the route’s dataType at all: a value that is not a String on a text route, a file that cannot be read.

A Socket has both settings and they mean the same, for every message a Reply or a Stream sends on it; under surface the socket closes with 1011. A run that fails, or a bus that ends failed, is told to the caller whatever whenChunkFails says.

If a caller says part of a stream never arrived, the run’s record shows which. The inspector strikes each lost message through and says why, and weft events prints them on the caller’s rows as dropped=<offsets> (<why>), an offset being the message’s place in the conversation. The messages still waiting when the caller left are named the same way, whatever whenCallerIsSlow says. A message skipped under drop_chunk shows as an error row saying a chunk was dropped and the exchange went on, then why.

Which triggers need a public address

Only the ones a provider pushes to.

./setup.sh --public-url opens one. Go and read a public address.

What a trigger cannot do

All three are compile errors, named trigger-into-trigger, trigger-into-infra and trigger-in-loop.

Firing one by hand

While you are building, you do not want to expose anything:

weft bake
weft run --fire inbound='{"chatId":"123","text":"hello"}'

weft bake prepares every trigger’s settings and starts no listeners. --fire then runs exactly one, with an event you typed.

The payload is checked against what that trigger declared it fires with, both ways: a missing field is refused, and so is one you invented.

A route fired this way cannot carry authorization, proxy-authorization, cookie, weft-instance-token, or a header its auth reads a credential from (an API key’s X-Api-Key, a signature’s header), nor anything on its credentials key: a route hands its caller’s credentials to the program as secrets, which only a real call makes, so the fire is refused, naming the header. If you need one, call the route for real (weft activate prints its URL), or leave the header out.

A run you fire this way follows the trigger’s durable and keepRunsFor, and it is always recorded, even when the trigger has recorded off, so you can find it in weft runs. For the flags that change how one run is kept, go and read the weft run flags.

For writing a trigger of your own, go and read writing a trigger.

Files and reuse

Three markers pull something in from outside the line you are writing.

Where a path is measured from

This catches people, so it is worth stating on its own.

@file and @asset are measured from the project root, wherever you write them. @file("assets/prompts/triage.md") means the same file in src/main.weft, in src/billing/charge.weft, and in a file included from either.

@include is measured from the file that writes it, like an import in any other language. So @include("../lib/clean.weft") inside src/billing/charge.weft climbs one level from src/billing/.

Both refuse a path that climbs out of the project, and @include refuses it on the spelling before it even looks, so a ../ that escapes is refused whether or not anything is there.

A path starting with __catalog/ is measured from neither place: it is measured from the project’s nodes/ folder, where the standard library and your shared nodes live, and it may not climb out of nodes/. If you want to include nodes/my_pkg/triage.weft, write @include("__catalog/my_pkg/triage.weft"), and that spelling reaches it from any file in the project. In @file and @asset, which are already measured from the root, __catalog/x is nodes/x, so a file under nodes/ can name its neighbours the same way in all three.

If you put a .weft file under nodes/ for others to include, make its first line a # comment saying what it does: weft describe-nodes --list ends with every such file, spelled the way you include it, with that line beside it.

@asset is the one exception to the rule that a path stays inside the project: it may name a file anywhere on your machine by an absolute path, or under ~. For when that works and when it is refused, see where an @asset is read.

@file

write = LlmInference {
  prompt: @file("assets/prompts/image_brief.md")
}

The type is String unless you say otherwise, and a String is taken verbatim: no parsing, no trimming. That is the common case, which is a prompt or a document. Give it another type and the text is parsed and checked: @file("limit.txt", Number).

It goes both ways. The editor shows that field as backed by a file, and editing it writes the file rather than pasting the text into your .weft. So a prompt lives in a real file that a person can open, and the graph is still the place you edit it.

That is also why a @file cannot name a URL or a file type. There would be nothing to write back to. The error points you at @asset.

The built program does not carry the text. It carries the file’s name and a hash of what the file holds, and the version stores the file, so a 2 MB SQL script costs the program a few bytes, and a file two versions share is stored once. The worker that runs the program reads the file and gives the node the value, as if you had typed it in.

@asset

terms = Text {
  value: @asset("https://example.com/terms.txt", String)
}
fal = FalAccess
sharper = FalUpscaleImage {
  account: fal.access
  image: @asset("assets/logo.png", Image)
}

The type is required, because weft will not guess it from the extension or from the bytes. For text, it is the type to read the text as (String, Number, JsonDict, a record). For a file, it names one concrete kind: Image, Video, Audio or Blob. File and Media are refused: each covers several kinds, and weft has to know which one the file is.

It is resolved when you build. If it is a URL with a text type, the build fetches it once and stores the text, which the program names the way it names a @file’s. If it is a URL with a file type, the node gets the address, and the file is fetched when the run reads it.

Where an @asset is read

The install builds from a version, so it looks for the file there first. A file the version holds (anything under assets/, prompts/ and the other folders a version covers) is already stored with the version, so nothing is read off your disk or uploaded for it.

If the version does not hold the file (an absolute path, ~/..., or a project file outside those folders), an install on your machine reads it off your disk (a relative path from your project folder) and stores it, with a file type and a text type alike. A cloud install cannot reach your machine, so it refuses the build:

assets that cannot be used:
  @asset("/home/me/logo.png", Image): '/home/me/logo.png' is not in the version, and this install runs in the cloud, so it cannot read files off a machine: put the file in the project, under `assets/`, and name it from there

On an install on your machine, a program building a project that has no folder can still use an absolute or ~ path, but a relative one has nowhere to be read from, so that build is refused.

@file in your program can only name a file the version holds, because the install compiles the version.

In the editor, a file you choose with the file picker is used where it is, and a file you drag onto a node is copied into your project’s assets/ (with -1, -2 added if the name is taken).

@include

An included file is one group, and its header is the interface:

# triage.weft
Group(email: JsonDict) -> (severity: String) {
  # Classify an inbound ticket
  classify = ExecPython(email: JsonDict) -> (severity: String) {
    email: self.email
    code: "return {'severity': 'high' if 'urgent' in str(email) else 'low'}"
  }
  self.severity = classify.severity
}

# main.weft
triage = @include("triage.weft")
triage.email = inbox.message

The file has to be exactly one anonymous group, with nothing beside it. No loose nodes, no top-level connections, no top-level includes, not two groups, and not a named one. The group’s header is the file’s interface and the file name is its identity, so anything else would be quietly thrown away, which is why weft checks rather than assumes.

Includes inside that group’s body are fine, and they resolve against that file’s own folder. A file that ends up including itself, through however many hops, is a compile error naming the cycle.

Ten includes, one body

A file is compiled once, however many places include it. Each @include is a call: the values on its ports go into the one body under a frame naming the call site, the body runs, and the results come back to that site alone.

Ten includes of the same file are one body and ten frames, the way ten iterations of a loop are one body and ten frames. The two nest freely, so a loop inside an include inside a loop is just a deeper stack.

Only the type check runs once per include. If blur.weft holds Group[T: Media](file: T) -> (out: T) ([T: Media] limits T to kinds of Media; without it, T takes any type), you can include it once fed an Image and once fed a Video, and each out keeps the type that went in. That holds however deep you go: for a group nested inside the file, for a node’s type variable, and for another file the file includes. If img and vid are your two includes of blur.weft, and it includes a file as inner, img.inner and vid.inner each get their own types. The nodes and their code stay one copy each.

Whether a node runs once per instance is decided per include too. A file included under a per-instance part and also somewhere shared is per instance only under the first; for what that means, go and read programs with instances.

Naming a node inside one

An included file has no name you write. Its nodes are named through the site: triage.classify is the node classify of the file that triage includes, and only that use of it.

That spelling is the same everywhere. It is what weft events prints, what --node triage.classify filters on, what weft run --group triage runs, and what the box header shows in the editor. Include the same file twice and the two read apart, as triage.classify and again.classify.

Cutting a run works inside a call too, so --target triage.classify runs inside that one call.

Types reach down into an included file

A type declared above an @include is visible inside the file it pulls in, the same way it is visible inside a group written in place. Declare Settings once at the top of main.weft, and bot.weft and facts.weft can both use it. It keeps going down: a file bot.weft includes sees it too.

It only goes down. A type declared inside a group reaches the includes inside that group and nothing beside it, and a type an included file declares stays in that file. Since nothing shadows, an included file can’t declare a name its including file already has.

A file included from several places has to find each type it uses at every one of them. If one place doesn’t have it, the build says so on the file’s own line. When you open an included file on its own, weft reads it with the types of the first place that includes it, so it looks the way the build compiles it.

The including file doesn’t see an included file’s types, but the call site’s ports still type-check, because a named type carries its shape along with its name.

If two files use the same type name with different shapes, that is the named-type-conflict error. A named type has one body everywhere.

Where each belongs

Put a prompt, a SQL query or a script in assets/ and pull it in with @file, so somebody can open it, read it and edit it without reading your graph.

Put a picture, a sound or a document in with @asset.

Pull out a group into its own file with @include when it gets big enough to stop fitting on a screen, or when two places need it. For what that costs at run time, which is nothing, go and read groups.

What the compiler refuses

Every compiler finding carries a message saying what went wrong, usually with the fix, and a slug naming the rule. The editor shows the slug beside the message, and weft validate puts it under code. The slug stays the same when the wording of a message changes, so look yours up here.

Everything here is checked when you build, except rule-runtime, which is only checked by weft validate and by the editor just before you Run, Activate or Resync, so a half-wired sketch whose provider has no model named yet still builds while you work on it.

A row marked (warning) is reported and the build goes on, unless the row says otherwise. Every row with no mark is an error, except rule-structural and rule-runtime, which take whatever severity the node’s own rule sets: error, warning, info or hint.

Before the rest can run

parse and enrich are buckets: they carry the underlying message rather than a slug per cause.

Wires

Values you wrote

Names and shape

Ports that come from a list

For a node whose ports are built from entries you write, like a form’s fields or a switch’s cases.

Metadata ports

For what a metadata port is, go and read metadata ports.

Loops

Streams

Triggers, infrastructure and addresses

For why a trigger cannot be wired into another trigger or have an infra node after it, go and read what a trigger cannot do. For why neither a trigger nor an infra node can sit inside a loop, go and read what cannot go in a loop.

Instances

For what @per_instance and @instance_filled do, go and read Programs with instances.

Types you named

Rules a node declared for itself

A rule whose answer depends on a value that arrives on a wire cannot be decided here, so it is checked again when the node runs, on the value that arrived, and fails the node with the same message. For how, go and read rules on a value that arrives on a wire.

Things that have no slug

Some refusals happen before the compiler gets a graph at all, so there is nothing to look up.

A broken metadata.json fails when the catalog loads, with the path and a sentence. A fire payload that does not match a trigger’s firesWith is refused at run time, not at build time. And in the editor, a node whose metadata is mid-edit is skipped with a warning rather than blanking your graph.

What a node is

A folder with two files in it.

word_count/
  metadata.json    what it takes and what it gives back
  mod.rs           what it does

The metadata.json is what makes the folder a node. Put the folder anywhere under your project’s nodes/ or src/ folder and weft finds it. The two folders make one catalog, so a name (a node type, a service, a package) has to be unique across both.

A folder with metadata and no code

That is not an error. weft finds it, warns that it has no mod.rs yet, and leaves it out of the build. A program that never names it builds fine, and a program that does is told which folder is waiting for its Rust:

node type 'WordCount' is not ready yet: node 'WordCount' at <project>/nodes/word_count
has no mod.rs yet; it is left out until it does

So you can write the metadata.json first and the Rust later.

Packages

Drop a package.toml in a folder and it becomes a package. Every subfolder holding a metadata.json is then one of its nodes, found automatically. There is no list to maintain.

slack/
  package.toml        [package] name = "slack", plus shared dependencies
  api.rs              shared code, reached from a node as `super::api`
  metadata.json       optional defaults every node here inherits
  access/
    metadata.json
    mod.rs
  send_message/
    metadata.json
    mod.rs

For the shared code, the defaults and the dependencies, go and read packaging.

The trait

#[async_trait]
pub trait Node: NodeManifest + Send + Sync {
    async fn run(&self, ctx: RunContext) -> WeftResult<()>;
    // everything below has a default
    fn node_type(&self) -> &'static str;
    async fn provision_infra(&self, ctx: InfraProvisionContext, input: ValueBag) -> WeftResult<InfraSpec>;
    async fn setup_trigger(&self, ctx: RunContext) -> WeftResult<()>;
    fn tests(&self) -> Vec<NodeTest>;
}

run is the only one you have to write.

provision_infra and setup_trigger have defaults that fail loudly, naming your node, if your metadata said you implement them and you did not. So requiresInfra: true without a provision_infra is an error you get told about when the infra is provisioned, not a silent nothing.

You never check which phase you are in. The engine reads your metadata and calls the right body. For a plain node that means run is called in every phase, including while a trigger is being set up, because a value feeding a trigger’s settings has to be produced then too. For a trigger, run only fires on a real event, with the payload on ctx.wake.

How it gets into the binary

There is no registration file: the compiler generates the lookup table from the folders it finds.

It only compiles the packages your program uses, each as its own cargo crate. For what that buys you, go and read shared code.

Your program’s definition is not baked into the binary. The worker fetches it by hash at run time, which is why rewiring your graph without touching any Rust reuses the worker already compiled (a program on your machine, an image on a cloud install).

The one macro

#[derive(NodeManifest)]
pub struct TextNode;

That reads the metadata.json sitting beside your file and attaches it to your type. It reads the package defaults too, so what your code sees at run time is the same merged document the compiler saw.

It checks at compile time that the file is there, is valid JSON, is an object, and has a string type. Editing the JSON rebuilds the crate.

The struct’s name is how it finds the file, so TextNode has to live in the same folder as its metadata. By convention the struct is the node’s type with Node on the end.

Next, write one.

Your first node

Here is Text, one of the smallest nodes in the catalog, with the lines that hook up its tests left out. Text takes a string you typed and sends it on.

catalog/basic/text/metadata.json:

{
  "type": "Text",
  "label": "Text",
  "description": "Emit a literal string (a prompt, a label, a config value).",
  "tags": ["literal", "string"],
  "icon": "Type",
  "color": "#64748b",
  "inputs": [
    { "name": "value", "type": "String", "widget": { "kind": "textarea" },
      "required": true, "label": "Value" }
  ],
  "outputs": [ { "name": "value", "type": "String" } ],
  "features": { "pure": true }
}

catalog/basic/text/mod.rs:

//! Text: emit a literal string configured at design time.

use async_trait::async_trait;

use weft::{RunContext, Node, NodeManifest, WeftResult};
use weft::node::NodeOutput;

#[derive(NodeManifest)]
pub struct TextNode;

#[async_trait]
impl Node for TextNode {
    async fn run(&self, ctx: RunContext) -> WeftResult<()> {
        let value: String = ctx.inputs.get("value")?;
        ctx.pulse_downstream(NodeOutput::new().set("value", value)).await
    }
}

Read an input, send an output. That is the shape of every node.

Write one

Make a folder anywhere under your project’s nodes/ (except nodes/base_catalog/), or anywhere under src/, for example next to the .weft file that uses it. nodes/base_catalog/ holds the standard library, and it is a folder of nodes like any other: weft loads and builds it the same way, and you can delete it if you do not use it. The one thing particular to it is that weft catalog update replaces it with the installed weft’s copy, so anything of yours in there would be lost.

nodes/word_count/
  metadata.json
  mod.rs

metadata.json:

{
  "type": "WordCount",
  "label": "Count words",
  "description": "Count the words in a piece of text.",
  "tags": ["text"],
  "inputs": [
    { "name": "text", "type": "String", "required": true, "label": "Text" }
  ],
  "outputs": [
    { "name": "count", "type": "Number" },
    { "name": "longest", "type": "String" }
  ]
}

mod.rs:

//! Count the words in a piece of text, and find the longest one.

use async_trait::async_trait;

use weft::{RunContext, Node, NodeManifest, WeftResult};
use weft::node::NodeOutput;

#[derive(NodeManifest)]
pub struct WordCountNode;

#[async_trait]
impl Node for WordCountNode {
    async fn run(&self, ctx: RunContext) -> WeftResult<()> {
        let text: String = ctx.inputs.get("text")?;

        let words: Vec<&str> = text.split_whitespace().collect();
        let longest = words.iter().max_by_key(|w| w.len()).copied().unwrap_or("");

        ctx.pulse_downstream(
            NodeOutput::new()
                .set("count", words.len() as f64)
                .set("longest", longest)
        ).await
    }
}

Now use it. The type name from your metadata is the name you write:

words = WordCount { text: draft.answer }
show = Debug { data: words.count }

weft run compiles your node into the project’s worker program, on your machine with your own Rust, and runs it. If you have not installed Rust yet, go and read the install page.

Five things that would have bitten you

Do not check your inputs. No asserting that text is really a string, no unwrapping something you were already promised. Every wire was checked before anything ran. A wrong value fails before it reaches your code.

Do not use .get(...).unwrap_or(...). That turns a real type error into your default and you never find out. ctx.inputs.get_or("limit", 10) is the same shape and fails honestly.

Emit each port at most once. Several calls are fine if they touch different ports, which is how you release a value early and a done flag at the end. Touching one port twice is an error naming it. Anything you never mention is closed for you when the body returns, and that closure is what tells everything downstream to stop waiting.

Keep values small. A value over 100 KB fails the emit, naming the port. Bytes go in storage, and what travels the wire is the marker saying where they are. If a big answer is not a file, go and read emitting for how to send less of it.

If your code does heavy work, hand it to spawn_blocking. Your body shares a few threads, one per CPU, with the calls arriving at the worker and with its other runs, and a thread only changes hands at an .await. Parsing a big document, resizing an image or hashing a large file in one go keeps the thread until it is done, and everything waiting for that thread waits with it. On a worker with one CPU, that is everything. The worker keeps its hold on your run from a separate thread, so a slow body never loses the run; it only slows the rest down.

let rows = tokio::task::spawn_blocking(move || parse_csv(&text))
    .await
    .node_err("parsing the export")?;

Failing well

let body = response.text().await.node_err("reading the reply")?;

.node_err("...") wraps somebody else’s error with what you were doing. On an Option, the message is what the reader sees when it was None, so say what was missing.

weft::node_bail!("pick a destination: a channel or a user");

node_bail! is for something your own code worked out. Write the message as an instruction, because it is going in front of whoever is building the program.

Those two, plus ? on anything the ctx hands back, cover almost every failure. The exception is a mistake in the program that your code spots, like SQL that does not parse: return Err(WeftError::Input(..)) for that. For why, and for which failures a program can catch on _error (an output weft gives every node), go and read which failures a program can handle.

Then a test

#[cfg(feature = "node-tests")]
mod tests;

and in your impl Node:

#[cfg(feature = "node-tests")]
fn tests(&self) -> Vec<weft::NodeTest> {
    tests::tests()
}

tests.rs:

pub fn tests() -> Vec<NodeTest> {
    vec![NodeTest::fake("counts_words", counts_words)]
}

async fn counts_words(rig: FakeRig) -> WeftResult<()> {
    let outcome = rig.run(&WordCountNode, json!({ "text": "one two three" })).await.ok()?;
    assert_eq!(outcome.outputs["count"], json!(3.0));
    assert_eq!(outcome.outputs["longest"], json!("three"));
    Ok(())
}

weft test-node WordCount

For the tiers, the rig and what a live test costs, go and read testing a node.

metadata.json

Every node has one, beside its mod.rs. It declares the node’s type, its ports, and everything the editor and the compiler need to know about it without reading your Rust.

If you write a key weft does not define, the node fails to load: it is left out of the catalog, with a warning naming the error, and a program that uses it fails to compile, saying the node failed to load and why. Places that hold someone else’s names, like authParams or an input’s default, take any key. Under accessApps, an entry takes label, client_id and the registration keys its service declares; for how that is checked, go and read accessApps. A port’s type is parsed when the file loads, so a misspelled type (Strng) fails then too.

Three keys are required: type, label and description.

Spelling

The node’s type and any types you declare under types are PascalCase (WordCount), and a type variable under typeParams is T, or T and a number (T1). Every key weft defines (requiresInfra) is camelCase, and so is every port, setting and record field you name. So are the fields under firesWith, and the names under each event’s fields in a service’s events (for what those are, go and read Events from a service). The names of the values a connection stores (imapHost) are camelCase too, both where a service declares them (the name of each entry in fields, captures and registrationFields) and where an input asks for them in requiresValues.

Two kinds of key are snake_case: a service’s event topics (drive_changes) and the keys under accessApps (google, the service’s name). They are snake_case because a node also writes them as values (a trigger picks a topic by name, and a node names its service as "service": "google"), and every value from a fixed list is snake_case. A name somebody else chose keeps their spelling, like an OAuth parameter under authParams (access_type), or a field of a request body you send to a provider. Inside an accessApps entry, client_id keeps OAuth’s spelling, and any other registration key is spelled exactly as the service names it in its registrationFields.

If you write a key weft renamed in its old snake_case spelling (requires_infra), the node fails to load, and the error names the new spelling: “requires_infra is spelled requiresInfra now … Rename it”. In a package root’s metadata.json (the defaults its members inherit), the error is reported against the root’s file, and the package’s members are left out. For how those defaults work, go and read Package defaults.

If any other name in a metadata.json breaks these rules, the node still loads and you get a catalog warning. Your project’s own nodes get this check too. It also covers the field names and port templates a portsFromConfig spec declares. The check never reads a node’s data, so it says nothing about a select’s options or an input’s default.

If you have the graph open in the editor, these warnings show up in the graph view’s problems list as “node spelling warning”. On the command line, weft validate < src/main.weft and weft describe-nodes --list print them on stderr, and the JSON from weft validate and from bare weft describe-nodes lists them under warnings, each as {"kind": "spelling", "message": ...}. On stderr a warning looks like this, and the JSON message is the same line without warning: :

warning: <NodeType> (<path to metadata.json>): <message>

If a name is off in a package root’s metadata.json, including a port it gives its members and that port’s record fields, the warning names the root, not each member, and starts package '<name>' defaults (<path>) instead of a node type. A declared type’s fields are checked once, where it is declared.

If you are changing a node that ships with weft, the catalog’s casing test fails on any such warning. For the command, go and read the Code style section of CONTRIBUTING.

The top level

inputs

A blank text counts as no value

If you take an optional input that takes text (String, or a union with String in it, like String | List[String]), a blank text on it (empty, or only spaces) reaches your node as nothing at all, whether it was written in the program or arrived on a wire. ctx.inputs.opt::<String>("title")? gives None, a default fills it as it would fill any missing input, oneOfRequired counts it as not given, and the rules below see it as not set. So read it plainly, with no filter of your own:

let title = ctx.inputs.opt::<String>("title")?;

This holds for the inputs your metadata.json declares. A port the program adds to your node keeps whatever arrives on it, a blank included, because it is the program’s data, and so does a required input. If a blank is a real value for your node, set "keepsBlank": true on the input; on a required input or one that does not take text, the node fails to load. A list is still a value, even an empty one: only a blank text counts as nothing.

outputs

An output has no required. A firing that emits nothing on a port closes it, which is what downstream reads.

Do not declare _error: weft gives every node that output for its failures, and the loader refuses a metadata.json that declares it. For what comes out on it, go and read which failures a program can handle.

metadataPorts

A metadata port holds a value written here, by hand, and the node never computes it. A wire a program draws from it is a metadata wire: before the program runs, the compiler writes the value into the input the wire points at. For what that is for, go and read metadata ports.

"metadataPorts": [
  { "name": "tool", "type": "{ name: String }", "description": "What this node is, for a model", "value": { "name": "pick" } }
]

If one of these rules is broken, the node fails to load, and the message names the port.

features

display

Exactly one of input and output, never both and never neither.

widget

Every widget, by its kind:

Leave widget out and weft picks one from the type: a file type gets file_drop, Boolean gets checkbox, Number gets number, List[String] gets text_list, String gets text, and everything else gets textarea.

remote_select sources

A Lookup takes get, items, label and value, and optionally page (an object holding cursorParam and cursorPath), public, where, errorPath and okPath. get is the URL to call. items is the dotted path to the array in the answer (data.channels for {"data": {"channels": [...]}}), or "" when the answer is the array itself. label and value are dotted paths inside one item: the text the person sees and the id that gets saved.

If you want the service to do the searching, put {query} in get, and it becomes what the person typed in the search box. If get has no {query}, the service never sees the search text, and the list only shows the items whose label or id contains it, ignoring case. If you want another input’s value in the URL, list that input in the widget’s dependsOn and write its name in braces: {team} becomes whatever is set on team. Weft percent-encodes every value it puts into the path or the query. A value before the path, like a {base} holding https://..., goes in as it is. If a brace in get is never closed, the node fails to load and says so.

If the endpoint is https and needs no credential, add "public": true. The list then works before anyone picks a connection, and the call never carries the connection’s credential, even after they pick one.

If you only want some of the items the service sends back, add where. Each key is a dotted path inside one item, and its value is what the item must hold there. An item is kept only if every path matches, type included: true does not match "true". An item with nothing at a path is dropped, so null only matches a field the service sends as null.

ElevenLabs’ models endpoint answers with a bare array of every model, each carrying flags like can_do_text_to_speech, so a text-to-speech node sets "items": "" and keeps the ones that can speak:

{ "kind": "list", "get": "https://api.elevenlabs.io/v1/models", "items": "",
  "label": "name", "value": "model_id", "where": { "can_do_text_to_speech": true } }

If the lookup also has a page, where filters each page as it arrives: a page where nothing matches adds nothing to the list, and the editor still shows “More…” for the next one.

If the service answers a failed lookup with a 200 and says so in the body, like Slack’s {"ok": false, "error": "missing_scope"}, add errorPath and okPath so the lookup fails with the service’s own words. For what they read, go and read refusals answered with a 200.

validate

Each rule is { "when": <condition>, "then": <diagnostic> }.

The diagnostic takes message (with {id}, {port} and {field} filled in, plus the ones the conditions below name), level (structural, the default, or runtime), severity (error by default, or warning, info, hint), and optionally port or field to say what the finding is about.

A structural rule is checked every time the project is parsed or built. Pick runtime for a rule that only matters once the project runs, like a provider with no model named yet. The build skips it; for when it is checked instead, go and read What the compiler refuses.

The conditions are a closed list:

A value condition takes any of these checks, and all the ones you write must hold. In each { "min", "max" }, both bounds are optional and both included.

{ "kind": "value", "field": "voice", "oneOf": ["alloy", "verse"] }
{ "kind": "value", "field": "schedule", "each": { "range": { "min": 50, "max": 500 } } }
{ "kind": "value", "field": "messages", "each": { "key": "role", "oneOf": ["user", "assistant"] } }

A check meeting the wrong kind of value is false (matches on a number, range on text), and a field that is absent or null fails every check. So a rule that refuses a bad value with not around a check refuses a missing one too. If the field is optional, put the check inside all with a bare value. Here an optional list that must hold at least two items when it is given:

{ "when": { "kind": "all", "of": [
    { "kind": "value", "field": "options" },
    { "kind": "not", "of": { "kind": "value", "field": "options", "count": { "min": 2 } } } ] },
  "then": { "message": "Pick '{id}' needs at least two `options` to choose between.", "field": "options" } }

On a required input, the not alone does it.

with picks nodes by one feature they declare, never by type, so your own node counts the same as a catalog one: {"answersCaller": true} is any node that answers its caller, {"answersCaller": ["stream"]} only a Stream-like one, {"liveConnection": ["http"]} a trigger with an HTTP caller.

Two examples from the catalog. A route warns when nothing in its run answers its caller, and refuses to become per instance, since its public address is one for everybody:

{ "when": { "kind": "not", "of": { "kind": "run_reaches", "direction": "downstream", "with": { "answersCaller": true } } },
  "then": { "message": "Route '{id}' starts a run that never answers its caller...", "severity": "warning" } }
{ "when": { "kind": "per_instance" },
  "then": { "message": "Route '{id}' would exist once per instance, because {perInstanceReason}..." } }

A node that starts an instance’s copy of an infra node, when it is given an instance, refuses a name that is no such node, and SetInstanceValues refuses a key that is no field an instance fills:

{ "when": { "kind": "all", "of": [{ "kind": "input_satisfied", "port": "instance" }, { "kind": "not", "of": { "kind": "input_names", "port": "node", "names": { "node": { "role": "infra", "perInstance": true } } } }] },
  "then": { "message": "StartInfra '{id}' names {names} in `node`...", "port": "node" } }
{ "when": { "kind": "not", "of": { "kind": "input_names", "port": "values", "names": { "field": { "instanceFilled": true } } } },
  "then": { "message": "SetInstanceValues '{id}' gives {names} in `values`...", "port": "values" } }

Rules on a value that arrives on a wire

If a rule’s answer depends on a value a wire brings, the compiler cannot decide it. It records the rule on the node in the compiled program, and the rule is checked again with the values that actually arrived, before your node’s body runs. If it fires, the node fails with the rule’s own message. That failure is an input error, so a wired _error does not catch it: the fix is in the program. A rule asking whether an optional wired input is set (input_satisfied) is one of these too, because the wire may close empty.

So a rule you write here covers every value, written or wired, and your node’s Rust never checks it again. A node with no undecided rule pays nothing. Only rules with severity: error are recorded; a warning the compiler could not decide is dropped, because it could not fail a firing anyway.

Which connection a node takes

If your node takes a connection, its input’s type names the service: "type": "Access[slack]". The compiler then refuses any other service’s connection on that wire, so a program cannot wire a Mistral connection into your node and send the Mistral key to your provider. If the node works with several services, write a union, Access[openai] | Access[anthropic]. If your node declares its own service, the input it takes that connection on (account, or connection) is typed with that service, Access[google] on GoogleAccess, and the catalog refuses the node when it names another one. A bare Access takes any service, so write it only where the service is not known until the program is written (a Route’s connection, whose service follows its auth). When the node opens the connection, weft checks the service again and fails the node naming both if they differ.

portsFromConfig

For a node whose ports come from a list the author writes, like a form’s fields or a switch’s cases.

Each spec takes kind (required), keyField (default "key", the entry key holding the port name), label, render, fields, catchAll (at most one, and it goes last), addsInputs and addsOutputs (at least one of them).

A port template is { "nameTemplate": "...", "portType": "..." }, with {key} replaced by the entry’s key.

A spec field is { "key", "label", "required", "shape", "valueType", "widget" }, where shape is one of typed (needs valueType), value, value_list, number, element or regex. Every shape but typed needs matchInput set. You can also write a field as a bare string, such as "email": that is a typed String field with a text widget, labelled from its key.

types

A flat map from a name to a type, usable by every node in the project:

"types": { "ChatMessage": "{ role: String, content: String }" }

For how the names are shared and compared, go and read custom types.

typeParams

If a port is typed with a type variable (T, or T and a number), it takes whatever type is wired to it. If you want to limit what that can be, give the variable a bound here:

"typeParams": { "T": "File" }

KeepFile does this with "T": "File". Its file input and its file output are both T, so a Video in gives a Video out. Wire a String into it and the build stops with type-bound. A bound never picks the type: the compiler works the variable out from what is connected, then checks the result against the bound. A bound may name another variable that one of your ports uses ("T": "List[T2]"). The file fails to load if a variable here is used by no port, or if two bounds name each other in a cycle.

placeholdersAreInputs

If your node takes a text setting whose placeholders name inputs the program adds to it (a query’s $userId, a template’s {{name}}), say so here, and the compiler checks that the placeholders and those inputs match. The node needs features.canAddInputPorts, or the file fails to load.

"placeholdersAreInputs": { "in": "template", "pattern": "\\{\\{\\s*(?<name>[A-Za-z_][A-Za-z0-9_]*)\\s*\\}\\}" }

in is the input holding the text, and it must hold a String. pattern is a regular expression finding one placeholder, whose group named name is the input it stands for. If a match leaves the name group unmatched, weft ignores it, which is how a pattern skips text that only looks like a placeholder: the pattern '[^']*'|\$(?<name>[A-Za-z_]\w*) skips '$userId' inside a string literal and finds the bare $userId. Back-references are allowed (\k<tag>), so a pattern can skip everything up to the delimiter that matches its opening one, like SQL’s $tag$ ... $tag$.

When the program writes the text itself, in the node’s settings or through @file (files and reuse), every placeholder in it must be an input the program added (placeholder-not-an-input), and every input it added must appear in it (input-not-a-placeholder). Text that arrives on a wire or through @asset is only known when the node runs, so your node checks it then: find the placeholders in the text yourself and pass their names to ctx.inputs.for_holes (it calls them holes), which matches them to the inputs and fails on either mismatch. For its arguments, go and read reading inputs.

firesWith

firesWith says exactly what a trigger’s event carries: a flat map from field name to type. Only a trigger may have one; on any other node, the file is refused when it loads. Each type is parsed when the file loads, so a misspelled type fails then too. A ? goes on the name, not the type:

"firesWith": { "chatId": "String", "caller?": "JsonDict" }

The payload has to match it exactly. Whenever the trigger fires, whether a listener sends the event or you fire it by hand with weft run --fire, the payload is checked before the trigger’s body runs. A payload missing a field you declared without ? is refused, and so is one carrying a field you never declared, whether at the top level or inside a field whose type is a record. The refusal names the field and ends with It wants { ... }, the shape you declared. If a trigger has no firesWith, its payloads go through unchecked.

claimsRoute

pathField names the config field holding the route pattern, and the optional methodField names the one holding the HTTP method. Leave the method out, or leave it empty on the node in your program, and the node claims every method.

If your node puts the path’s captures on outputs a program adds (-> (id: String) on cards/{id}), set capturesAreOutputs: true; the node also needs features.canAddOutputPorts. The compiler then refuses an added output the path does not capture, or one not typed String, with route-output-not-a-capture, and a capture named like one of the node’s own outputs with route-capture-shadows-output. Filling each port is your node’s code: emit the capture under the port’s name.

accessApps

If you want people to connect your node’s service without registering an OAuth application of their own, ship a public one here, keyed by service: when somebody connects through the own door (the “Your own” page, where people paste their own app) and fills in none of the app fields, it signs in with this one. For what the doors are, go and read How connections work.

Each app needs a label (the name shown in the connection list) and a client_id, plus every registrationFields entry the service does not mark optional:

"accessApps": { "google": { "label": "Acme", "client_id": "1234.apps.googleusercontent.com" } }

Every check on an app here runs when the catalog loads, and an app that fails one leaves its node out of the catalog, with a message naming what is wrong:

• the key under accessApps names no service any node of the project declares (no node in this project declares a service named 'slak');
• the service connects without an app, because it does not sign in through OAuth;
• label or client_id is missing or empty, a required registration field is missing or empty, or the app has a key the service does not declare (the message lists the keys it knows).

An app a package root gives its members is reported once, against the root’s file, unless it leaves out label or client_id entirely: then every member that inherits it fails to load, each against its own file. A project’s catalog holds its copy of the standard nodes (nodes/base_catalog, which weft new copies in), so the standard services count as declared.

An app here is a public client, one that signs in with no secret (OAuth’s PKCE flow). A metadata.json ships with the node to everyone who uses it, so a secret written here would go to all of them: a client_secret is refused, and so is any registration field the service marks secret (a field is secret unless the service marks it "secret": false). A service that needs a secret field in every app cannot ship a public app at all. An app with a secret goes in the install’s apps file (access-apps.json), or is pasted on the “Your own” page when somebody connects.

Package defaults

A package root can hold a partial metadata.json whose keys every member inherits. Members win, key by key, at the top level only, with no deep merge: a member’s types replaces the package’s rather than adding to it.

Three keys can never be defaults, because they are one node’s identity:

package-level metadata.json must not set `type`: it is one node's identity, not a package default

Keys that no longer exist

If you are reading older node code, the loader names these rather than saying “unknown field”:

The ctx

ctx is everything your node’s code can reach: its inputs, and every service weft provides. The runtime hands it to run, and to a trigger’s setup_trigger.

Every call here returns WeftResult, and your node never names a weft error type. Wrap an outside error with .node_err("what you were doing"), and fail on something you detected yourself with node_bail!. If what you detected is a mistake in the program (a value of the wrong shape, SQL that does not parse), fail with input_bail!("...") instead. A wired _error catches what node_bail! raises but never this: the fix is in the program, so the run fails.

Five rules that save you a debugging session

Calls on a connection go through ctx.open or ctx.client. That is what signs the request and records what it cost. ctx.http() is for everything else. A reqwest client you built yourself skips both.

If your node can pause, keep a state that says where it is. After a pause the body runs again from its first line, and ctx.keep hands it back the state it saved: a once whose field is filled runs nothing, a wait whose field is filled waits for nothing. A port it already sent on sends nothing a second time. For the whole story, go and read surviving a restart.

A file in StorageScope::Run goes with its run, when the run’s record is deleted (its keep time runs out, weft clean, weft rm). Right for what one run makes, wrong for something a project keeps using: store that in StorageScope::Project.

ctx.stop_tagged returns when the stop is queued, not when the other runs are gone. Do not write a node whose next step assumes they stopped.

ctx.register_signal is once per node per setup. A second call is a loud error rather than a trigger that quietly never fires.

Which firing am I

Reading inputs

ctx.inputs holds this firing’s inputs, whether they arrived on a wire, were written into the body, or came from a declared default. ctx.wake holds the event payload, and only on the trigger that actually fired. Both are a ValueBag with the same methods.

Never write get(...).unwrap_or(...). It turns a real type error into your default and you will not find out. get_or is the same shape and fails honestly.

Emitting

An ordinary port emits at most once per firing. Whatever you never mention is closed for you when the body returns. A task you spawned with a clone of ctx can emit only while the body is running: an emit from it after the body returned, or after it paused, fails with an error naming the node and the port. A Generator[T] port emits as often as you like until you close it.

NodeOutput is the payload you hand those calls:

Waiting, and surviving a restart

For how the state carries a node through a pause, and through its worker dying, go and read surviving a restart.

If your node waits on a job a provider runs, go and read waiting on a job a service runs, which also covers the cancel call.

Connections

On an opened connection: client(), credential(), value(name), identity(), owner(). On an endpoint handle: url(), host_and_port(), and call(method, path, body), whose path starts with /.

Putting a value into an address

If an id or a search term goes into a URL, build the URL with client::url, so that an id holding /, ? or # stays one piece of the address you meant instead of changing which address you call:

use weft::access::client;

let url = client::url(API, &["files", &id, "copy"])?
    .query("q", &search)
    .query("pageSize", 50)
    .query_opt("pageToken", page_token.as_deref());
let answer = client::get_json(&http, url.as_str(), "copy the file").await?;

Every path segment, and both halves of every query pair, are percent-encoded: anything but letters, digits and -_.~ (a space becomes %20). The base is taken as written, with a trailing / dropped, so it has to be a constant of your node or an address weft handed you, never a value. A segment that is empty, . or .. fails with an input error, because an address reads even the encoded %2E%2E as .., so a wired id of .. would climb to another address; that is why url returns a Result. .segment(s)? adds one more segment, before the first query pair only (after one, it panics). If a value’s / must stay, like an object store key (photos/2024/a.jpg), add it with .key_path(key)?, which encodes each part between the / and refuses a . or .. part. .query_opt adds the pair only when the value is Some, for an optional input. Read the result with .as_str(), format!("{url}") or String::from(url).

For an endpoint, start from its address, client::url(endpoint.url(), &["media", &id])?, or build only the path for call with client::url("", &["media", &id])?, which gives /media/<id>.

Secrets

If your node hands out a value the run’s record must never show, like a session key a voice app gets for a few minutes, make it a secret. What flows on the wire is a marker naming it. For what the record keeps and for how long, go and read secrets.

let session = ctx.secret(&key)?;
ctx.pulse_downstream(NodeOutput::new().set("session", session)).await

Declare that output as Secret[String] in your metadata.json. A node that needs the value declares a Secret[String] input and asks for it:

let session: weft::secret::Secret = ctx.inputs.get("session")?;
let key: String = ctx.reveal(&session).await?;

A secret this run made, or revealed already, comes back from the worker’s memory. Any other comes from its sealed copy, which any run of the same project can read: the same run picked up after a pause, a seeded run, a marker your program stored somewhere and reads back later. A run with recorded off writes nothing down, so only that run reveals its secrets.

If a value holds a secret its type does not declare (a token inside a JsonDict), reveal_in and reveal_input fail rather than hand it on as its marker, saying where the secret is and that the program should declare the type, like { token: Secret[String] }. If you emit a revealed value on a plain output, the record holds it like any other value. For which types fit a secret, go and read what fits into what.

Sharing something between runs

If your node builds something on every run that is slow to build, let the worker’s runs share it instead. There are two calls for that:

• if each run needs one to itself for a while (a database connection a run may hold a transaction on, a process that runs one script at a time), take one from a pool with ctx.pool;
• if runs can all use the same one at once (a client, a cache, a pool library you already use), ask for it with ctx.shared.

One each, from a pool

use std::time::Duration;

let mut conn = ctx
    .pool(&access, |opened| async move { connect(&opened).await })
    .max(20)
    .idle_close(Duration::from_secs(5))
    .check(|c| !c.is_closed())
    .reset(|c| async move { clear_session(&c).await.map(|()| c) })
    .take()
    .await?;

You write only how to make one (connect here is your own function), and weft does the rest. take hands you the newest idle one that is still fresh and passes your check, letting go of every one that fails on the way, and calls your closure to make a new one when none is left. What comes back is a weft::shared::pool::Lease<T>: it derefs to the item, and goes back to the pool when you drop it.

The first argument is the key, the same as for ctx.shared: a connection (your closure gets it opened, and the pool is built again once the connection’s values change) or a name of your own (your closure gets ()).

Every ask of one pool has to give the same max and the same idle_close. An ask that gives others fails with the pool '<key>' is asked for with max .. and idle close .., and it is held with max .. and idle close ..: every ask of one pool says the same, so keep the settings in one function your nodes call, the way the Postgres nodes do.

If an item is no good for the next run (a process that stopped answering, a connection whose state your run cannot vouch for), call lease.discard() and weft lets it go instead of giving it back. weft does the same on its own for a lease dropped while its run is cancelled, since whatever the run was doing may still be under way on it. A make that fails takes no place under max.

One for everybody

let client = ctx.shared(&access, |opened| async move { Client::new(&opened) }).await?;

The closure is async and its result is a WeftResult of the thing (Client here is your own type, whose new returns a WeftResult<Client>).

The first argument is the key weft keeps the thing under. If you pass a connection (&access), the closure gets the opened connection, and once one of its values changes (a new password), the next run that asks gets your thing built again from the new values. To notice the change, weft opens the connection every time a run calls ctx.shared (or ctx.pool). For a connection a person made or an infra node published, the worker answers that open from memory, so a reused thing costs no extra call. A connection set to Use ours (weft’s own key) costs one network call to weft each time.

If you pass a name of your own instead, the closure gets ():

let python = ctx.shared("exec_python", |()| async { Ok(Interpreters::new()) }).await?;

On one worker, every node that asks under the same name for the same Rust type gets the same thing, so pick a name that is your node’s own, the way ExecPython uses "exec_python". A worker serves one project, so nothing another project builds can collide with yours.

ctx.shared hands back a weft::shared::SharedHandle<T>, which derefs to the thing. If two runs ask at the same moment, it is built only once. A build that fails keeps nothing, so the next run tries again.

If the thing can only serve so many runs at once, say so with with_limit:

let client = ctx.shared(&access, |opened| async move { Client::new(&opened) }).with_limit(100).await?;

Then at most that many handles to it exist at once on one worker, and the next run that calls ctx.shared waits until one is dropped. A run that asks again while it still holds a handle can end up waiting on itself once the limit is reached, so keep one handle per run. Every call for one shared thing has to pass the same limit: a call that passes another, or none, fails, naming both. The limit counts the handles to one thing on one worker: two workers can go past it between them, and so can the old thing and the new one for a moment after a connection’s values change, while runs still hold handles to the old one.

If a task you spawn needs the thing after your run returns, move the handle into the task: it keeps its place under with_limit until the task drops it. If your task should not count against the limit, take handle.arc() instead: the Arc keeps the value alive but holds no place under with_limit, and weft can let go of the thing while you hold it, so the next run may build a new one beside yours.

How long weft keeps them

By default, weft lets go of a shared thing (a pool is one too) about five minutes after the last run asked for it or dropped its handle, once no handle is left. Your thing’s Drop runs once weft has let go of it and the last handle and Arc are gone, which is when a pool closes its connections. When the worker stops, it lets go of every shared thing as soon as its last run has ended, used recently or not, so a pool’s connections go back to the database while the worker is still writing its last records.

If you want a quiet stretch not to cost a rebuild, raise the five minutes with weft workers set --shared-idle-seconds <n> (or lower it to let go sooner). It is one setting for the whole project, covering every shared thing on its workers. The change applies from the next run: weft starts workers with the new value (a new revision on Cloud Run), and the old ones finish what they are running and stop.

When the other end only serves so many

max and with_limit only cap what one worker takes, so that its runs never leave its sibling workers without a connection. They cannot keep a database under its connection limit, because they cannot see how many workers there are. If your node talks to something that only serves so much (a database with a fixed number of connections, an API with a rate limit), assume any number of workers run your node at once: Cloud Run starts copies up to the project’s --max-instances (set with weft workers set), and a change of program or worker settings runs the old copies beside the new ones for a while. Two things follow:

• Hold nothing you are not using. Close an idle connection within seconds, because one a copy keeps between requests is one no other copy can have. On Cloud Run a copy has no CPU between requests (unless the project turned on weft workers set --cpu-always-allocated true), so a timer that closes it may not fire for minutes, which is why idle_close also refuses to hand out an item idle for longer. The Postgres nodes use an idle_close of 5 seconds and a max of 20.
• Let the other end do the counting. It is the one place that sees every copy, so that is where a client past the limit should wait its turn, or be refused with a clear answer. Your node then waits, or fails with a message that says why. A PostgresDatabase does this with a pooler in front of Postgres, where a client that finds every connection busy waits for one, and Postgres closes a session that sat idle for a minute. If your node keeps a connection idle on purpose (one that LISTENs), lift that limit for its own session when it connects, the way PostgresWatchQuery sends SELECT set_config('idle_session_timeout', '0', false) FROM pg_settings WHERE name = 'idle_session_timeout' (the FROM pg_settings part makes it do nothing on a Postgres that has no such setting, instead of failing).

Storage

ctx.storage(scope) gives you a handle. The scope decides where new files go, how long they live, and what list sees; get, delete, keep and the links act on whatever scope the key itself belongs to. Any run of any project in your account can read any stored file it holds a reference to, for as long as the file exists.

For every scope, go and read Storage.

keep takes KeepTtl::Default (30 days, pushed back each time the file is read), Secs { secs }, or Never (no deadline), in every scope but Asset. For what it means in each scope, go and read how long a file lives.

What comes out of externalize is no longer a value of that type, because the links expire. Hand it to whoever asked and do not store it.

Streams and buses

On the bus handle:

For how a bus ends and what a reader does about it, go and read streams and buses in Rust.

Read a stream input like any other value: ctx.inputs.get::<Generator<Row>>("rows")?.

Live callers

Logging, tags, cancelling

StopSelf::Keep only reaches runs that took the tag before this one did, so two runs racing to stop each other leave the later one alive. StopSelf::Include ends this run too.

When the run is cancelled

You do not have to watch for a cancel around weft’s own calls. When the run is cancelled, each of these ends at once with the cancelled error, even in the middle of waiting on a slow server:

• a request sent through a client from ctx.http(), ctx.client(..) or an opened connection, and the read of its answer’s body;
• an endpoint handle’s call;
• a provider socket’s send and recv;
• a storage read, and a write of bytes or a stream (the calls listed in Storage; put_from_url and copy are not among them);
• a bus reader’s read.

Pass that error up with ? and the node ends cancelled instead of failed.

If your node waits on something of its own (a child process, a timer, a library with its own client), wrap it in race, which hands back the work’s own output, or the cancelled error the moment the run is cancelled:

let status = ctx.cancellation().race(child.wait()).await?.node_err("wait for the script")?;

The work is dropped where it stands, so a child process you spawned with kill_on_drop(true) is killed with it.

If you turn a request’s error into a weft error yourself, check weft::cancellation::is_cancel(&e) first: .node_err makes any outside error a failure, a cancel included. client::send(req, what) keeps a cancel a cancel and hands back any status, for a node whose answer is the status itself. checked_send does the same and also refuses a non-success status, quoting the provider, and get_json and post_json add the parse. client::body_error(what, e) does it for a failed read of a body.

Your project, and the owner’s other projects

A node can do from code what a person does with the CLI: build and run a project, write its files, turn its triggers on, start its infra, read its runs. The runtime carries each call out on behalf of this run, with the same parameters and the same refusals the CLI gets. Each call is numbered within the firing; for what a body that runs again gets back from one, go and read the ctx helpers that wait.

The calls below act on this run’s own project. If you want the same call on another project of the same owner, put ctx.project(id) in front of it, id being the project’s id (the one in its weft.toml): ctx.project(shop_id).infra("bridge").start(&mut state).await. A project of another owner is answered as if it did not exist. ctx.projects().list() lists the owner’s projects. If you want a new, empty one, call ctx.projects().declare("shop") and take its id from the answer (the id comes from the call’s number in the firing, so if the worker dies after the declare and before the node’s next save, the body run again finds the project the first call made; every other time the body runs again, the declare is a new call and makes a new project, so put it in a state.once or keep the id in your state), then write its files: at least a weft.toml naming it and carrying that id, and nodes/base_catalog/ too if it uses the standard library, since a build only sees the files the project holds. If you want to copy files the owner already holds, such as the standard library of this run’s own project, read their hashes with state() and name each one with edit().blob(path, hash): nothing is downloaded or stored again, so the copy is one read and one write however many files it holds.

let shop = ctx.projects().declare("shop").await?;
let shop_id: uuid::Uuid = shop.id.parse().node_err("read the new project's id")?;
let weft_toml = format!("[package]\nname = \"shop\"\nid = \"{shop_id}\"\n");
let source = "# your program here\n";
let own = ctx.code().state().await?;
let mut edit = ctx.project(shop_id).code().edit()
    .text("weft.toml", weft_toml)
    .text("src/main.weft", source);
for (path, hash) in own.working.iter().filter(|(path, _)| path.starts_with("nodes/base_catalog/")) {
    edit = edit.blob(path.clone(), hash)?;
}
edit.apply().await?;

Three things a program cannot do to its own project, each refused with the reason:

If you want to hand out a token, mint an instance token with tokens().mint_for_instance, which hands the value to the run alone. Only a person can mint a signal token or a frontend’s new token, because its value would sit in the journal.

The project’s infra, triggers, instances and settings

Most of these take an optional .instance(id), which picks that instance’s copy instead of the shared one; values(), connections() and tokens().instance(..) always name an instance.

take_down is a TakeDownChoice and stop_self a StopSelf. For what each one can say, with an example, go and read taking something down from a run.

If you want status(), cancel_build(), get(), tree(), running_source(), prune(), working_copies(), forget_working_copy() or set_run_example() on this run’s own project, go through ctx.own_project() (for example ctx.own_project().status()), because ctx has no short form for them.

One run, by its id

ctx.run_by_id(run) reaches any run of the owner’s, this one included (ctx.run_id), and a run whose project was removed since.

ctx.resolve_run("3f2a") finds the one run whose id starts that way, the way weft logs 3f2a does.

A project’s code

ctx.project(id).code() reads and writes a project’s files and builds and runs them, the way you do from a folder. A program writes into a working copy (for what that is, go and read your folder is a copy). If you name none, it writes into the project’s most recently changed folder: on an install on that person’s machine the files land on their disk right away, and on a cloud install at their next command that syncs. When the project has no folder, it writes into the program copy. If you want a particular working copy, ctx.project(id).working_copies() lists them, each with its id, and ctx.project(id).code().working_copy(copy) acts on that one. If a prune is refused because of a copy’s head, move it with .code().working_copy(copy).switch_to(version) to a version outside that history, or call ctx.project(id).forget_working_copy(copy), which records the copy’s files as a version (named in saved, None when it held no file) and removes the copy, as weft forget-copy does. A folder that still exists registers again at its next command that syncs it.

let shop = ctx.project(shop_id).code();
shop.write_text("prompts/tone.txt", "Answer in two sentences.").await?;
let started = shop.run().example("angry-customer").start(&mut state).await?;
ctx.log(LogLevel::Info, format!("run {} on version {}", started.run_id, started.version)).await?;

If you want a project’s version tree, ctx.project(id).tree() answers what weft tree --json prints, without workingCopy (the CLI adds that to say which folder it ran in). If you want what the project runs, .running_source() answers the version of its build and that build’s files by path and hash.

.prune(version, frozen, plan_only) is weft prune. In frozen, pass the frozenFrom.version of every examples/*.json in the project (read each with read_text): the prune is refused if it would delete a version a frozen example came from, or an ancestor of one, and an origin you leave out has no such protection. Set plan_only to see what it would remove without removing anything. If you froze a run as an example yourself, .set_run_example(run, Some(name)) records it the way weft freeze does, and None forgets it.

What is not here

ContextHandle, the trait underneath, is the seam the runtime implements. Your node only ever sees the RunContext wrappers on this page.

Reading inputs, emitting outputs

What the methods are is on the ctx. This page is what happens around them: how a value gets into your bag, and what the runtime does with what you send.

Where an input’s value comes from

Wired data and design-time settings live in one bag, under the port’s name. Three things can fill a port, in this order:

Four rules sit around that.

A closed wire kills the default. If a wire closes without carrying a value (weft calls that a closure: upstream finished without sending on that port, or failed), the default does not fill in, because that would hide that something did not happen.

A delivered null is a value only where the type allows it. On a port whose type admits Null, null is data. Anywhere else, a null arriving on a wire fails the run, unless the program marked that input optional (x?: T where it uses your node): then it reads as nothing arrived, and the default fills.

A wrong type fails the run, required or not, and the program cannot catch it (which failures a program can handle). It is never dropped so the default can take over.

A number outside its number widget’s min and max fails the run too (widget), and so does a fraction where the widget’s step is whole: a poll interval of 0 on a port with "min": 1 fails rather than becoming the port’s default. So does a value that is not one of a select widget’s options, unless the widget sets freeText.

An input your metadata leaves optional can be empty when your body runs: nobody wired it and it has no default, or the program wrote ? on it and its wire closed. Read such an input with opt or get_or (reading inputs). Whether your node runs at all then is up to the program. For how a program decides, go and read optional and required inputs.

Two ports get special handling before your code sees them. A connection input arrives as a full Access value carrying the service, rather than the id the editor stored. And the gate ports are stripped out entirely, so your node never finds a _should_flow it did not declare.

A trigger is different again: on a real firing, its ports replay the values that were frozen when the trigger was set up, and written literals fill whatever is left.

Emitting

ctx.pulse_downstream is the only way out.

Once per port, per firing. Emitting or closing the same port twice is an error naming it:

node 'reply' touched port 'text' twice in one firing. Each output port can be
emitted or closed AT MOST ONCE per firing

If your node emits, pauses on a wait, and its body runs again from the top when the answer comes, the emit made again does not count as a second one: it does nothing, and the first value stands. For why the body runs again, go and read surviving a restart.

Several calls are fine if they touch different ports. That is how you release a bus marker early and a done flag at the end. If any port in one call collides, nothing in that call is recorded, so a failed call is a clean no-op rather than half an emission.

A stream port is the exception. A Generator[T] output takes as many emissions as you like, one per item, until you close it. After the close, nothing can follow.

Anything you never mention is closed for you when the body returns. That closure is the signal everything downstream is waiting for. A node that decides it has nothing to say does not need to do anything special: it just returns, and the branch behind it skips.

A node that fails closes whatever it had not already sent. What it did send stays sent. weft cannot unsend a message your node already put on Slack.

An undeclared port is caught first, before the once-only rule, so a typo reads as the real problem:

node 'reply' tried to emit on undeclared output port 'txet'. Declare it in
metadata.json's outputs list, or correct the port name in the node body.

A value that does not fit its port’s type fails the call, naming the port, the type and what did not fit. The type is the one in your metadata, after the program filled in any type variable. If your metadata marks the output narrowable (outputs), it is the type the program declared on it, like -> (response: Verdict). If the type is an open record, extra keys are dropped instead of failing the call (records that take extra keys). A refused call sends nothing and leaves the port open, so if your code handles the Err instead of returning it with ?, it can emit on that port again with something else.

A value over 100 KB fails the call, naming the port. The weight is the value written as JSON, checked on what you emit, so a node one hop later cannot trim it for you. There are two ways out, and the refusal names both: put the data in storage and send the stored file, whose value weighs a few hundred bytes whatever the file holds, or send less. Sending less means sending one page of it along with where the next page starts, or cutting it short and saying so in another output.

If you want to bound a value yourself, weft::storage measures it the way the wire does, against MAX_WIRE_VALUE_BYTES:

FetchPage uses cap_text this way: a maxChars input, and a truncated output that tells the program the page was cut.

Waiting for the value to be taken

pulse_downstream sends and carries on. yield_downstream waits until the value was actually taken, which is what you want when you are producing faster than the consumer reads.

It fails rather than waiting forever when delivery becomes impossible, for instance because the consumer skipped or the run finished. An unwired port counts as delivered immediately.

Building the output

NodeOutput::new()
    .set("count", words.len() as f64)
    .set("longest", longest)

set takes anything that turns into JSON. If you already have a Value, it passes through rather than being wrapped again.

For a dynamic object whose keys should land on same-named ports, ctx.fan_declared(&value) matches them against the ports your node actually declares and skips the rest. That matters after a paid call: an extra key in a provider’s response should not fail your node when you already spent the money.

NodeOutput::stored_file(stored) fills the four ports a stored file travels as: file, filename, mimeType and sizeBytes.

Errors

Those, plus ? on anything the ctx returns, cover every failure except a mistake in the program itself, which you return as Err(WeftError::Input(..)) (see which failures a program can handle).

Write the message as an instruction to whoever is building the program, because that is who reads it. “pick a destination: a channel or a user” beats “invalid configuration”.

Which failures a program can handle

Every node has an _error output, which weft adds when it loads the node. If a program wires it, your node’s failure comes out there and the node counts as done; if nobody wired it, the failure fails the run. For what that looks like from the program, go and read when a node fails. Your body writes no handling for it: it returns its errors with ? as usual.

_error is weft’s, so a body that emits on it or closes it fails. error, without the underscore, is yours to use like any other name.

What your node does decide is which kind of failure it returns. A failure of the work itself can be caught on _error: anything from node_err or node_bail!, a value your node emits that does not fit its port (like a model’s answer in the wrong shape), and a wait that gave up (go and read when the run cannot pause). A mistake in the program (a bad setting, or a value of the wrong type arriving on an input) always fails the run, even when the program wired _error, because the fix is in the program. If your node asks ctx.output_type about a port it does not declare, that fails the run too, and _error never sees it.

So when your node spots a mistake in the program itself (SQL that does not parse or names a table that is not there, an input value of the wrong shape, an empty field it needs), fail with Err(WeftError::Input(..)). If a program could sensibly retry or route around the failure while it runs, use node_bail! instead. If your node talks to a server, decide the same way for each kind of refusal: the Postgres nodes fail the run on a syntax error or a missing table, and put a broken constraint on _error.

If your node produces a stream, its failure stops reaching _error once something went out on a Bus or Generator output. So do the work that can fail before you send the first piece. For a bus, ctx.pending_bus waits to open it until you have the first piece (go and read streams and buses in Rust).

In a test, rig.wire_output("_error") wires _error the way a program would, and outcome.output("_error") reads what came out. Without it the rig wires nothing, so the same node fails loudly.

Custom types

Give a shape a name in a node’s metadata.json, and every node in the project can use it.

"types": {
  "ChatMessage": "{ role: String, content: String }",
  "ChatHistory": "List[ChatMessage]"
}

Then in the ports of any node in the project, including nodes from other packages:

"inputs": [ { "name": "messages", "type": "ChatHistory", "required": true } ]

A named type is only equal to itself. Declare "CustomerId": "String" and a port that wants a CustomerId refuses a plain String unless the program puts a Cast in between, while a CustomerId goes into a port that wants a String with nothing in between. For how names compare and what fits into what, go and read types.

One table for the whole project

Every metadata.json in the project adds its types to one table before any port is read, and the program’s own .weft files can use these names too. If several nodes in a package share a type, declare it once in the package root’s metadata.json.

Two files may declare the same name with the same shape: the two declarations count as one. If two metadata.json files declare it with different shapes, the nodes of both are left out of the catalog, each with an error saying the name is declared twice with different bodies.

A type written in a .weft file is stricter: it may never reuse a name the program can already see, including the names metadata.json files declare, even to declare the same shape.

Records that take extra keys

A record refuses any key it does not declare. If your node’s type describes data that comes from outside and may carry more than you read (a provider’s answer, a webhook’s body), end it with ..:

"types": { "Charge": "{ id: String, amount: Number, .. }" }

Such a record accepts a value with extra keys. weft drops them when your node emits the value and when a Cast produces it, so what flows on carries only id and amount. A missing field or a field of the wrong type still fails.

What travels

The name carries its shape with it. A port typed ChatMessage is stored as ChatMessage={role: String, content: String}, so anything reading a saved project or a journal row understands it with no table to consult, and a run that started yesterday keeps the shape it started with even if you edit the declaration today.

If you write that stored form into a port’s type yourself and its shape differs from the declaration ("type": "ChatMessage={role: String}"), the build fails with named-type-conflict.

Making your node a cast

If your node converts its input into whatever type the program gives its output, the way Cast does, name the two ports here:

"features": { "castPorts": { "input": "value", "output": "value" } }

Where the node is used, the pair of types its two ports end up with has to be a conversion Cast knows (for the table of those, go and read Cast), and any other pair is the cast-not-allowed error when the program compiles:

no cast from JsonDict into Number; a cast parses text, stringifies data, or
validates an object shape against a declared type

Your node does the conversion itself when it runs, the way Cast does:

let target = ctx.output_type("value")?;
let cast = target
    .cast_value(&value)
    .node_err(format!("casting the value into {target}"))?;

Showing something in the graph

Every value on every wire is already in the inspector, so your node never has to send anything just so a person can see it.

Two things go further, and they share a word, so keep them apart.

A file, rendered on the node

Name one port in your metadata and the editor renders its value on the box after each firing.

"display": { "kind": "media", "output": "image" }

Exactly one of input and output, naming the port. The value has to be a file.

Use link for something somebody downloads and media for something they look at or listen to.

A live panel

This is the other one, and it is a different thing: a panel that updates while something runs, rather than a value from a firing.

Two kinds of thing produce one, and only one of them is your job.

An infrastructure node’s container. Your container serves /live, and you opt in by naming the endpoint:

"features": { "liveEndpoint": "api" }

Declaring it is the opt-in. There is no separate flag. The dispatcher proxies the panel to your endpoint, and a node that names none answers 404.

A trigger’s signal kind. Written by weft, inside the listener, not by you. A node that declares a trigger writes no display code at all, and those panels are read-only: the listener refuses to serve one carrying a button rather than show a button that cannot work.

What a panel holds

A list of items, each with a label, and at most one action.

An answer that is not a list of items comes back to the reader as an error naming what you sent, rather than an empty panel. One item it cannot read becomes a line saying so, in its place, and the rest of the panel still draws.

A number outside 0 to 1 on a progress bar is shown as given rather than clamped, because clamping would hide the bug in whatever produced it.

Who can see it

Nobody, by default. A signal token reads no display at all unless it was minted with --display <node> naming that node, or --displays for all of them.

That is on purpose. A panel can be a credential: a bridge showing a QR code to scan, a database showing the password it just minted. So the scope grants nothing until you say which node.

Storage

A value on a wire is capped at 100 KB. Anything bigger goes into storage, and what travels the wire is a small marker saying where it is.

let storage = ctx.storage(StorageScope::Run);
let stored = storage.put(bytes, "image/png", "chart.png", None).await?;
ctx.pulse_downstream(NodeOutput::stored_file(StoredFile::from_value(&stored)?)).await

The five scopes

Any run of any project in your account can read any stored file, whatever its scope, for as long as the file exists. The scope decides only where a new file goes and how long it lives.

The scope governs writes and lists. Reading, deleting, keeping and linking act on whatever scope the key itself belongs to, so a later node, or a later run that kept the reference, can get a file without knowing where it came from. copy is the one that does both, reading from the key’s scope and writing into yours, which is how a file moves to a scope that lives longer.

How long a file lives

A file can also have a deadline. It is deleted when the deadline arrives, whatever its scope, or with its owner (its run, its project) if that comes first. Every read, link or replace pushes the deadline back, so a file something still uses does not vanish underneath it. A file with no deadline lives as long as its scope says.

storage.put(bytes, "image/png", "chart.png", Some(KeepTtl::Default)).await?;

None gives no deadline either. A cache of fetched pages that should go once nobody has read it for a week, say:

ctx.storage(StorageScope::Project)
    .put(page, "text/html", "page.html", Some(KeepTtl::Secs { secs: 7 * 24 * 3600 }))
    .await?;

For a file that already exists, keep(&file, ttl) sets its deadline from now on, and keep(&file, KeepTtl::Never) takes it away. Neither moves the file, so a run file still goes with its run. If you want a file to outlive the run that made it, copy it into the project (the KeepFile node with scope: project does that). An asset lives as long as a version of the project still names it (once none does, it expires on its own), so you cannot give one a deadline.

Storing