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 steps, 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 step 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 step 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.

One tool has to be there first: Docker. weft’s runtime is a program on your machine, and everything it starts (your programs, their databases and servers) runs in Docker containers next to it. If Docker is missing, the installer stops and prints the link to install it.

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

git clone https://github.com/WeaveMindAI/weft.git
cd weft

Put your keys in before you install

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 step 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.

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.

  "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.

Install

./setup.sh

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.

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 ./setup.sh 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 20 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.

Now leave this folder

Your projects do not belong inside the weft checkout. Go wherever you keep code:

cd ~/code

Then build your first program.

When you come back to this page

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

To update, pull and run ./setup.sh again. Your projects and their history stay where they are. Before you do, check the changelog for anything that needs you.

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.

To remove it, run ./setup.sh --uninstall. 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. Pass --assistant with your row from this table and 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 you use more than one, pass --assistant once for each. The pick is for this project only. 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

It prints the project’s id, then the run’s id, then a timestamped line for every step as it starts and finishes, then a tick:

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

That long id after started execution is the run’s execution 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 one step, which weft calls 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 steps, 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, 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, and you start each one yourself. None of them starts another.

Hitting Run never starts your database and never puts your webhooks live. That is the whole idea and it catches everyone once.

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.

An execution is just one run. It ends completed, failed or cancelled, or it parks at waiting for input while a step waits on a person or a service. Parking is free: weft shuts the machinery down and a fresh copy picks the run back up when the answer lands, however many days later.

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 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 step’s real inputs and outputs before wiring it. The language moves fast, so anything the model remembers is probably stale.

It writes missing steps. A step’s own logic is Rust, and if nothing in the catalog does what you need, Tangle designs the step’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 step, 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 step.

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, and every gesture rewrites your .weft file. The two panes are one file, so nothing you do on the canvas is stored in a second place that could disagree with 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 step

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 step your project knows about, and Group and Loop are in there with the rest, because a group is a kind of step.

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 step 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 steps

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.

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.

Change what a step 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 starts with the type MustOverride, which is weft saying nobody has decided this yet, and the build stops until you do. Right-click the new dot and pick the Type: row to set it.

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, Tags…, Set as target and Run from here….

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 by each 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 one branch instead of everything

Right-click the box whose answer you want and choose Set as target. It gets a breathing ring, and the Run button becomes Run 1 target. Only that box and the boxes feeding it will run. Set as many as you like; right-clicking a target again offers Unset target.

The same thing from a terminal:

weft run --target daily_report

The walk stops when it reaches a trigger, and a box that two branches share does not drag the other branch in. A target inside a group brings only the work needed through it. A loop is the exception and comes along whole.

For anything more specific, the chevron glued to the Run button opens Run from a spec…, a dialog where you can start partway in with values you supply, exclude an endpoint, run one group on its own, fire a single trigger with a made-up event, or reuse what did not change since the last run. Right-clicking a box and choosing Run from here… opens the same dialog already filled in. Everything in there has a flag on the CLI, and the rules are in versions, seeds and frozen examples.

Watch it go

Run Project is at the bottom of the canvas, or press Ctrl+Enter with the graph focused. While a run is going, that button becomes Stop Execution. The bar follows what happens whoever started it: an infra start typed in a terminal, or asked for by Tangle, shows as Starting infra… on the infrastructure buttons, and an activation as Activating…, each with its Cancel, the same as clicking them.

Each box gets a glow and a small mark:

Click the magnifying glass in a box’s header, Inspect execution, 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 step that decided. If a step 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. Executions 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.

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.

To make a group, add a Group step 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 step 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 step 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 step will not fold shut: where the fold arrow normally sits 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 step, and answer the prompts. weft connect --list prints what is already stored and changes nothing. weft connect --node account goes straight to one step. --disconnect clears a step’s pick and leaves the stored account alone, and --forget <id> deletes the stored account for good.

Picked on each install

Which connection a step 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 step connected on your cloud install, run weft connect --on prod there (it is the same walkthrough). A step inside a file you include twice is two steps, one per place, and each place gets its own pick.

If you run a program with a step nobody connected on this install, the run is refused before it starts, naming the step and the weft connect that fixes it. weft activate and weft resync check every step 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 step’s full address, and the file a step is written in is part of that address. So if you move chat.weft into a studio/ folder, the step 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 step went. When a step of the same kind now has no pick, 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 step across in one go. It refuses if the new step already has some, or if it takes different connections, since then it is not the same kind of step.

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 step again; the install keeps the pick from then on.

Never paste a key into a step’s field

Values written into a step 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"],
    "requiresValues": []
  }
}

Every step that consumes it stamps on what it needs, and a connection that falls short is refused when the step opens it 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 step 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 step 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 starts a tunnel from your machine to a separate port (14112) where weft serves a short list of paths and nothing else. The choice sticks, so later installs keep it open until you say otherwise.

What it exposes, and what it does not

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

Every /signal-token/... request carries the signal token in its Authorization: Bearer header, never in the path, so it stays out of proxy logs.

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, which has no authentication of its own and listens on your machine only.

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.

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.

Close it

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

The tunnel comes down and the address stops answering.

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 step 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 is free, so a program can sit on a question for a week without costing you anything.

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 step’s ports. A display field takes a value in and shows it to the reader. An approve_reject field gives you two boolean outputs, send_approved and send_rejected, so you gate what happens next on the one you want:

reply = SendMessage {
  _should_flow: review.send_approved
  text: 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 steps 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 answers with nothing and lets the run carry on, and Cancel run ends the whole execution. Neither shows up on a trigger, because skipping a trigger would fire it.

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.

That is one of the three lifecycles, and it is the step people forget.

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 <execution-id>. To find the ones still sitting there:

weft executions --status running

Parked runs come back in that list, with waiting_for_input in the status column rather than running, so you can tell at a glance which ones are working and which ones are waiting on a person.

How a program runs

Do not read a weft program top to bottom. A step 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 step’s inputs.

Values arrive one at a time

When a step 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 step 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 step or by a default, so not everything needs an arrow.

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

How a branch stops the steps after it

Here is the problem. A step 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 step 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.

For an ordinary step:

A skipped step closes its own outputs, which can skip the next step, 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 step closes whatever it had not already sent. Anything it did send is not taken back.

Choosing a branch, and joining back up

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

Only a literal false says no. Any other value lets the step run, and so does anything the step’s own code would have considered falsy. The step 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 step’s _should_flow and that step 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 step because something did not arrive?

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

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

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

This is the one port in weft that starts a step 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 step made, have that step say so on a second output and gate on that, because the wire then reads forwards.

A failure is not an absence. When the step it watches fails, its ports close too, but that closure carries which step broke and its error, and the gate reads it: the step 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 step 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 steps down still reads a failure, not an absence, and still sees query named as the step that broke rather than the step that skipped.

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

One step, several runs at once

A firing is one go at one step. Three things say which firing you are looking at: the run, the step, and the loop iterations it sits inside. Inside a parallel loop the same step 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 are gone before anything runs

The compiler turns each group into a pair of boundary steps, each loop into a LoopIn and a LoopOut, and each included file into a call pair plus one shared body. What the runtime gets is one flat graph with the scope information attached.

So folding a group in the editor costs nothing at run time, and neither does nesting groups five deep. For the boundary rules, go and read groups and loops.

What happens when you hit run

A manual run starts every step 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 daily_report --target alert

weft takes those steps and everything feeding into them, stopping the walk when it reaches a trigger. A step that several branches share does not drag those other branches in. A target inside a group brings only the work needed through it, with the group’s own _should_flow still applied. A loop is the exception: it comes along whole, and cutting inside one is refused.

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 a real execution produced beats one you handed in, and a producer that is still running is waited for. For which flag picks which part of the graph, go and read versions, seeds and frozen examples.

--group runs the group’s own steps 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 step would skip without it (it is a required input, or the only member of a @require_one_of set that could get a value; the step’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
(--from 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.

The input is named at the start you gave, even when the missing value would cross more doors 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 only optional steps read 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 door it crosses, 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 start that could only ever skip is refused too. When the start’s _should_flow, or that of a group it sits inside, only comes from triggers the run does not fire, or from outside the run altogether, the gate closes and nothing you started would run, even with every input fed. The refusal names the gate and the trigger, if there is one. Hand the gate a value to run as if the condition held, or --fire the trigger with an event. A value reaches a gate only at its own door: for the start’s own gate that is the start (--from 'triage={"_should_flow": true}'), and for a surrounding group’s it is that group, so the refusal asks you to start there instead, with the flag you used (--from 'outer={"_should_flow": true}', or --group if you ran a group).

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.

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 steps 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 step. It can also fail, when a step failed or weft could get no further, or be cancelled by a person or by another run.

A run can pause without ending. Waiting for input means a step 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 steps 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 step 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 step emits something its declared output type does not allow.

It cannot check whether a step 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 steps 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 kinds of step, from the project’s nodes/ folder.

Naming a step

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

message = Text { value: "hello" }

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

A name the catalog does not know is unknown-type. Writing a name does not bring a step 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 step’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 step 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 step’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.

You can only declare the ports a step leaves open for you. Ports whose types are already fixed keep them. Declare inputs, outputs, or both:

answer = LlmInference -> (response: String)
convert = Cast -> (value: Boolean)

Those are fragments: the steps still need their other required inputs before they can run.

Extra inputs

Some steps, 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:

step = ExecPython -> (out: String) {
  text: draft.answer
  limit: 3
  notes?: review.notes
  code: @file("assets/scripts/step.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? makes it optional, so a closed arrow there does not skip the step. That spelling only works when you are creating the port; to make a port optional in a full signature, write notes?: String there instead.

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 step has one gate, and wiring both spellings is the two-gates error. For what each one does to the steps 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.

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

Declaring a step where you use it

You can write a step 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 step 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 step 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 step skips if they all close without a value.

It goes in a step’s body or its inline signature. A step’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.

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 }
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. And a field that can be null says so: extra: JsonDict | Null. A JsonDict alone refuses a null, so a query whose rows all have that column empty fails the node with does not accept (got List[Dict[String, String | 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.

When a type is still MustOverride, or still a bare type variable, weft lets the arrow through and tells you to decide. That is the must-override-unmet and unresolved-typevar pair.

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 and they absorb; two packages shipping the same name with different bodies names both. 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 step you wired it into applies its own rules: a required input skips, an optional one lets the others decide. 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 the check names the exact path that was wrong, like messages[2].role: expected String, got Number, rather than failing with a shrug.

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 steps under one name and folds shut like a folder. Its signature says what the outside can see.

credit = Group(db: Access, 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.

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.

They do not exist when the program runs

The compiler turns every group into two nodes, one holding its inputs and one holding its outputs, and hands the runtime one flat graph with the scope written on each node.

So folding a group in the editor costs nothing, nesting five deep costs nothing, and a group is never a thing the runtime has to step through. It is a way of writing and reading, and it is gone by the time anything runs.

When a group starts

The node holding a group’s inputs fires like any other node: once everything the run wires into it has arrived, _should_flow included. A closed input counts as arrived. An included file is a group, so each @include starts the same way.

When it fires, every step inside that no wire feeds starts with it. So a step with no inputs needs no _should_flow to get its turn, and it never runs before the group’s slowest input has landed.

It only runs in a run that takes it along, though. A trigger’s run holds what the trigger feeds plus what those steps read, so a step 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.

Why a required group input does not skip the group

This is the part that surprises people.

You declare db: Access without a ?, so it is required. Then the thing feeding it closes. You would expect the whole group to skip.

It does not. The closure goes inside, and whichever step actually needed that value skips there, and the skip cascades from that step outward. Every port on a group’s boundary is optional, and the requiredness you declared is enforced by the node that consumes 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.

It also means @require_one_of is refused on a group. Put it on the step 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.

When a group input has to be connected

A group port is never required for its own sake, and the ? on it changes nothing. What the compiler checks is whether a step inside needs it.

It follows the port inward, through any group, loop or included file nested behind it, until it reaches the steps that read it. If one of them takes it into a required input, 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 optional inputs 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) {
  ...
}
brief.request = ask.text
brief._should_flow = credit.paid

The gate is consumed at the boundary. The steps 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.

Names you cannot use

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

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) -> (scores: List[Number | Null]) {
  over: ["cards"]

  mark = LlmInference -> (response: String) {
    prompt: self.rubric
    ...
  }
  self.scores = Cast { value: mark.response }.value
}
grade.cards = pull.rows

Like a group, a loop is gone before anything runs. The compiler turns it into a pair of boundary nodes and the runtime drives the iterations.

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 max_itres: 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 failed leaves an empty slot. That is the gather-output-must-be-nullable error.

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 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. If you do not wire a seed, it starts at the zero for its type: 0 for a number, "" for a string, [] for 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. Each iteration finishes before the next launches, which is what makes carry possible: the next iteration reads the value the last one wrote.

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 max_iters.
• 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 trim_on_mismatch: 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 max_iters times, then hand on a stale history as if all went well. The loop’s step 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 step that actually broke, even when other steps 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 step, 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.

Cutting a run inside one

You cannot. weft run --target stops at a loop’s edge and brings the whole loop along, because half an iteration is not a state the runtime has.

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. A model writing its answer a word at a time.

A bus is several nodes that are all running at once talking to each other. A transcriber, a translator and a display, each doing its part while the audio keeps arriving.

Streams

Write the type on the port and you have one:

rows = PostgresStreamQuery -> (rows: Generator[JsonDict]) { ... }
grade = GradeEachRow { rows: rows.rows }

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.

mic = MicrophoneCapture -> (audio: Bus)
transcribe = Transcribe { audio: mic.audio }
translate = Translate { audio: mic.audio }

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.

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. It is not what rebuilds a bus, because nothing rebuilds a bus.

A bus lives exactly as long as its worker

It is memory in a process. If that worker goes away, the bus goes with it, and a marker resolved afterwards fails saying the bus is unknown.

That is fine for what it is for, which is nodes that are alive together right now. It is why a run that used a bus cannot be partly reused by a seeded run: weft leaves the producer and its readers out rather than handing you a marker pointing at nothing.

A durable wait is a different thing and the two coexist. A node can park on a question for a week while a bus somewhere else stays up.

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, stopping the walk when it reaches another trigger.

Only the trigger that actually fired gets the event. Any others in the project close their outputs, so paths that needed them skip.

Two triggers can share the steps in the middle without their runs becoming one.

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 steps 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.

So after changing one, weft resync. Until then 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 without listening, `weft activate`
does it and listens

Answering on a URL

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

post = Route -> (body: JsonDict, photo: File) {
  path: "cards"
  method: "POST"
}

reply = Reply {
  body: { "id": saved.id }
}

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.

A path can capture: cards/{id} puts id where your node can read it.

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/cards (the install’s address, then /connect/local/, then the path). On a cloud install it is the install’s own address, then /connect/local/, then the path.

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/ as well.

If a call arrives while the route’s trigger is parked, hibernating within its grace window, or still being set up, it is answered 503 with a Retry-After at once, so a client that retries gets through once the trigger is on. Once the project is switched off (wiped), its own port is closed and /connect/local/<path> answers 404.

How a run is kept

Your runs happen inside a worker: a copy of your compiled program, running as a Docker container 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 steps live in the worker’s memory, and its record (the journal that weft events and the editor read) is written a moment after each step. 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 step 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 step of 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 step stays finished, and a step that was in the middle of its work is failed with a message saying it may have partly happened, so you know which step to check. The exception is a step of a pure node that takes no stream and had not passed anything on yet: it simply runs again. 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 step 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 steps already running to finish, and only a step still running after that is failed. 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 catchErrors does with that failure, or what happens to a step that was waiting on an answer or reading a stream, go and read surviving a restart.

Even with durable off, a run waiting on a timer or a form, with nothing else of it running, survives its worker, because its whole record is written before it pauses. A run that cannot pause is the exception, below.

When a run cannot pause

Three kinds of run cannot pause: one whose caller is still on the line while its trigger leaves outlivesCaller off (the caller cannot follow it), one with recorded off (there is no record to pick it back up from), and one with a bus between its nodes open (a bus lives in its worker’s memory alone).

When such a run reaches a timer or a form, the wait holds in the node’s call instead. 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 step still running is waiting, on an answer or on a bus. Anything that moves (a bus message, a step 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 can handle that error like any other, or send it to error with catchErrors. With holdSecs: 0, such a wait fails at once.

If the run becomes able to pause while a wait holds (the last bus between its nodes closes), the wait pauses after all, the way it would have from the start. 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 executions fills with hundreds of runs. weft keeps no history of such a run, not even in its worker’s memory. If it fails, weft executions lists it with the step 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 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.

An unrecorded run cannot pause, so a timer or a form in it holds (when a run cannot pause). If a node tags it with ctx.tag_execution (a label you later find or stop runs by), the node fails: an unrecorded run has no record a tag could point at. 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 a worker starts it. It ends cancelled with a message saying so, instead of being cut off mid-step with no ending written. A run that pauses whole (every branch waiting on a timer or a form) 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. While the caller is on the line, the run stops at 59 minutes too, with a message telling you to have the client reconnect. Once the caller has gone, a route with outlivesCaller on keeps its run going, and on a cloud install the run moves: it starts no new step on that worker, and once the steps it was running end, it carries on under a call weft holds open for it, with a fresh hour. Moving works from the run’s record, so the compiler refuses outlivesCaller: true with recorded: false. A run with a bus open cannot move, since a bus lives in its worker’s memory alone, so it keeps running on that worker for as long as the worker stays up.

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.

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 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 executions. 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.

@asset is the exception: it may name a file anywhere on your machine by an absolute path, or under ~, and it is read from where it sits and uploaded when you build.

@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.

@asset

badge = Text {
  value: @asset("https://example.com/terms.txt")
}
stamp = Watermark {
  image: @asset("assets/logo.png", Image)
}

The type is required for a file, and it has to name one concrete kind: Image, Video, Audio or Blob. File and Media are refused, because a value carries exactly one marker and those leave it open. weft will not guess the kind from the extension or from the bytes.

It is fetched or read when you build, not when you write it, so a URL is resolved once into your project rather than every run.

In the editor, dropping a file onto a node picks it up in place if it has a path on disk, and stores it under your project’s assets/ if it arrived as bytes with no path.

@include

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

# triage.weft
Group(email: JsonDict) -> (severity: String) {
  # Classify an inbound ticket
  ...
}

# 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.

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 slug naming the rule, and a message naming the fix. The slug is the stable part, so this page lists all of them.

Everything here is checked when you build, with one exception: rule-runtime is only checked by weft validate and by the editor just before you Run, Activate or Resync. That is deliberate, so a half-wired sketch with no credentials connected still builds while you work on it.

Almost everything is an error. The three warnings are marked.

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.

Loops

Streams

Triggers, infrastructure and addresses

Instances

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

Types you named

Rules a node declared for itself

Both take their severity from the rule, so either can be an error, a warning, a note or a hint.

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 one anywhere under your project’s nodes/ directory and weft finds it.

A folder with metadata and no code

That is not an error. weft finds it, reports it as pending, and leaves it out of the build. A program that never names it builds fine, and a program that does gets told which folder is waiting for its Rust.

So writing the interface first and the body second is a supported way to work. It is also worth knowing when a node you are sure exists comes back as an unknown type: check whether its mod.rs is there.

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

Package defaults merge key by key, and a node’s own value wins. type, label and description can never be defaults, because they are one node’s identity, and the compiler refuses a package file carrying any of them.

Two nodes with the same type fail loudly rather than one shadowing the other.

The trait

#[async_trait]
pub trait Node: NodeManifest + Send + Sync {
    async fn run(&self, ctx: ExecutionContext) -> 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: ExecutionContext) -> 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 requires_infra: true without a provision_infra is an error you get told about, 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 walks your nodes/ folder, finds the metadata, and generates the lookup table. Adding a node is adding a folder.

It only generates what your program references, and it emits one cargo crate per package, so editing one node recompiles that package and relinks rather than rebuilding everything.

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 is a cache hit on the image.

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 the smallest node in the catalog, whole. Text takes a string you typed and sends it on.

catalog/basic/text/metadata.json:

{
  "type": "Text",
  "label": "Text",
  "description": "Emit a literal string. Useful for prompts, labels, and config values.",
  "tags": ["literal", "string"],
  "icon": "Type",
  "color": "#64748b",
  "inputs": [
    { "name": "value", "type": "String", "widget": { "kind": "textarea" },
      "required": true, "label": "Value" }
  ],
  "outputs": [ { "name": "value", "type": "String" } ],
  "requires_infra": false
}

catalog/basic/text/mod.rs:

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

use async_trait::async_trait;

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

#[derive(NodeManifest)]
pub struct TextNode;

#[async_trait]
impl Node for TextNode {
    async fn run(&self, ctx: ExecutionContext) -> 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 under your project’s nodes/, anywhere except nodes/base_catalog/. That folder 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::{ExecutionContext, Node, NodeManifest, WeftResult};
use weft::node::NodeOutput;

#[derive(NodeManifest)]
pub struct WordCountNode;

#[async_trait]
impl Node for WordCountNode {
    async fn run(&self, ctx: ExecutionContext) -> 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 program and runs it.

Four 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.

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.

Your node never names a weft error type. Those two, plus ? on anything the ctx hands back, cover it.

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 name, its ports, and everything the editor and the compiler need to know about it without reading your Rust.

Unknown keys are refused at every level, so a typo fails the build rather than being quietly ignored. Types are parsed when the file loads, so a misspelled type name fails then too, not on some later run.

Three keys are required: type, label and description.

The top level

inputs

outputs

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

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 (a URL with {query} in it), items (a dotted path to the array), label, value, optional page (cursor_param and cursor_path), and public when the call carries no credential at all.

validate

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

The diagnostic takes message (with {id}, {port}, {field} and {custom_outputs} filled in, plus the three 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. A runtime rule is only checked by weft validate and by the editor just before you Run, so a half-wired sketch still builds.

The conditions are a closed list:

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 {per_instance_reason}..." } }

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

{ "when": { "kind": "not", "of": { "kind": "input_names", "port": "node", "names": { "node": { "role": "infra", "per_instance": true } } } },
  "then": { "message": "StartInstanceInfra '{id}' names {names} in `node`...", "port": "node" } }
{ "when": { "kind": "not", "of": { "kind": "input_names", "port": "values", "names": { "field": { "instance_filled": true } } } },
  "then": { "message": "SetInstanceValues '{id}' gives {names} in `values`...", "port": "values" } }

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.

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, valueList, number, element or regex. Every shape but typed needs matchInput set.

types

A flat map from a name to a type. Nominal and project-wide: any node’s ports can use a name any node declared. The same declaration in two files is fine and absorbs, so a package root can declare its shared types once.

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

firesWith

For a trigger. A flat map from field name to type, saying exactly what the event carries. A ? goes on the name, not the type:

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

It is exhaustive both ways. A payload missing a field you declared without ? is refused, and so is a payload carrying a field you never declared, at the top level and nested.

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.

accessApps

Public OAuth applications your node ships, keyed by service. Each takes label, client_id, and any extra field the service’s recipe asks for.

A client_secret here is refused. Node metadata is source, and source never holds secrets. An app with a secret belongs in the apps file.

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

Three keys that no longer exist

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

A folder with no mod.rs

That is not an error. The node is discovered, reported as pending, and left out of the build. A program that never names it builds fine, and a program that does gets told which folder is waiting for its code. Writing the metadata first and the Rust second is a supported way to work.

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!.

Six 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.

ctx.await_signal is refused once your node has emitted anything, because a resume replays the body from the top and would emit again. It is also refused on a node with a Generator input, because a stream cannot be replayed.

ctx.run keys on call order, not on the name you gave it. The name is for reading logs. If your body can call it a different number of times on a replay, wrap the thing that varies.

put with no keep policy is run-scoped, and the file is swept shortly after the run ends. Right for scratch, wrong for anything a person will open later.

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 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

ctx.run is how you stop a replay from doing an expensive thing twice. A body replays only after a wait. If the worker dies while the body is running, the step is not replayed: a durable run fails it, and a fast run ends cancelled (go and read surviving a restart).

Connections

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

Sharing something between runs

If your node builds something on every run that is slow to build (a pool of database connections, a process to hand work to), let the worker’s runs share one instead:

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

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

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. 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 pool = ctx.shared(&access, |opened| async move { Pool::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. Only the limit of the first call that asks counts, until weft lets the thing go (after it goes idle, or after its connection changes), so pass the same limit everywhere you call it. 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. The Postgres nodes that query through the shared pool ask for 100, Postgres’s own default connection limit.

If a task you spawn needs the thing after your run returns (handing a connection back to its pool later), move the handle into the task: it keeps its place under with_limit until the task drops it, which is what the Postgres nodes do. 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.

By default, weft lets go of a shared thing 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, everything goes with the process.

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.

Storage

ctx.storage(scope) gives you a handle. The scope decides where new files go and what list sees; get, delete, keep and presign act on whatever scope the key itself belongs to, so a later node can read a file without knowing where it came from.

keep takes KeepTtl::Default (30 days, pushed back each time the file is read), Secs { secs }, or Never, 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

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.

Your project beyond this run

The runtime answers each of these calls on behalf of this run and writes the answer into the run’s journal, so a replay reads the answer back instead of asking again. Most of them 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.

For what spec and stop_self decide, go and read taking something down from a run.

What is not here

ContextHandle, the trait underneath, is the seam the runtime implements. Your node only ever sees the ExecutionContext 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 around that, each of which exists to stop a quiet wrong answer.

A closure kills the default. If a wire arrived closed, meaning upstream produced nothing, the default does not fill in. A closure means something did not happen, and substituting a default would hide that.

A delivered null is a value only where the type allows it. On a port whose type admits Null, null is data. Anywhere else it reads as nothing arrived, and the default fills.

A wrong type fails the firing, required or not. It is never quietly dropped so the default can take over.

A number outside its declared range fails too. A poll interval of 0 on a port with a minimum never quietly becomes 30.

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

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 over 100 KB fails the call, naming the port. The check is on what you emit, so a node one hop later cannot trim it for you: bound it yourself (a cap input, a LIMIT), or put bytes in storage and send the marker.

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 Letting the program handle a failure).

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”.

Letting the program handle a failure

If your node reaches outside, it can fail for reasons the program might want to deal with: a model refusing a prompt, a host that does not answer, a database rejecting a row. If you want a program to be able to handle those, set this in the node’s metadata:

"features": { "catchErrors": true }

weft then gives the node an error output, and your body just returns its errors with ? as usual. If the program wires error, the failure’s message comes out there, the step counts as done, and every output the body had not sent yet closes. If nobody wired it, the failure fails the run.

In a durable run, a step that failed because its worker went away goes to error too (go and read surviving a restart).

weft owns error: your node cannot declare it, and a body that emits on it fails. If your node only shapes values (a cast, a switch, a template), leave the flag off: it has nothing outside to fail on.

Only failures of the call itself are caught: what node_err, node_bail! and outside errors produce. A bad setting, a bad input or a bad type always fails the run, wired or not, because the fix for those is in the program. The ctx sorts its own refusals the same way: ctx.output_type on a port your node does not declare fails the run, so just use ? on it. A cancel, or a step pausing to wait for an answer, never becomes an error value.

So when your node spots a mistake in the program itself (SQL it cannot run, a 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.

In a test, rig.wire_output("error") wires error the way a program would. Without it the rig wires nothing, so the same node fails loudly.

Custom types

Give a shape a name and every node can use it.

"types": {
  "ChatMessage": "{ role: String, content: String }",
  "ChatHistory": "List[ChatMessage]"
}

Then in any node’s ports, including other people’s:

"inputs": [ { "name": "messages", "type": "ChatHistory", "required": true } ]

They are global, and compared by name

Every metadata.json in the project contributes its types to one table before anything else is parsed, so a name declared by one package is usable by every node.

The comparison is by name, not shape. CustomerId declared as String is a different type from String, and wiring one into the other is a mismatch. That is the point: a customer id should not land in a port that wanted any old string.

A named type flows into its shape for free, because the name falls away when it is not needed. Going the other way, from a plain shape to a named one, needs a Cast, which checks the value really has that shape.

What travels

The name carries its shape with it. A port typed ChatMessage stores 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.

Where to put them

A package root’s metadata.json can declare the types its nodes share, once, and every node in it inherits them.

Two packages declaring the same name with the same shape is fine and absorbs. Two declaring it with different shapes names both, and a port that restates a declared name with a different shape is the named-type-conflict error. A named type has one body everywhere.

Nothing shadows. A name already visible cannot be redeclared, not even to the same thing.

Cast

Any node can declare itself a cast:

"features": { "castPorts": { "input": "value", "output": "value" } }

The compiler reads the declaration, never the node’s name, so this is a thing any node can be rather than one built-in.

At compile time, the resolved pair of types has to be a conversion that exists:

Anything else is refused at compile time:

no cast from JsonDict into Number; a cast parses text, stringifies data, or
validates an object shape against a declared type

At run time, the check names the field that was wrong, like messages[2].role: expected String, got Number, rather than failing with a shrug.

Stored files, buses and connections do not turn into text, so those casts do not exist.

Showing something in the graph

Every value on every wire is already in the inspector. You never hand-deliver information to whoever is watching.

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::Execution);
let stored = storage.put(bytes, "image/png", "chart.png", None).await?;
ctx.pulse_downstream(NodeOutput::stored_file(stored)).await

The five scopes

The scope decides where new files go, and how long they live.

The scope governs writes and lists. Reading, deleting, keeping and signing act on whatever scope the key itself belongs to, so a later node 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 crosses.

How long a file lives

An execution-scoped file is swept shortly after the run ends. If you want it to outlive the run (anything a person will open later), give it a lifetime:

storage.put(bytes, "image/png", "chart.png", Some(KeepTtl::Default)).await?;

The lifetime counts from the last time something touched the file: every read, link or replace pushes the expiry back, so a file something still uses does not vanish underneath it.

Project, shared and instance files take a lifetime too. There, None means the file lives until somebody deletes it. A cache of fetched pages, 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 lifetime from now on. On an execution file it also marks the file to outlive its run, and that mark cannot be taken back. On the other scopes keep(&file, KeepTtl::Never) takes a lifetime away again. 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 lifetime.

Storing

Every one of these makes a new file under a fresh key, so two puts never collide, whatever their filenames.

Changing a file in place

If your node keeps something that grows with use (a conversation, a log, a document it keeps adding to), keep it in a stored file and change that file. A port carries at most 100 KB, and a growing value will pass that. Have the node take the file in and pass the file on, and do not also offer the same content as a plain value, so a program has only one thing to wire.

To change what the file holds, use edit. It reads the content, hands it to your function, and writes back what you return:

let updated = storage.edit(&file, |old| {
    let mut lines = old.to_vec();
    lines.extend_from_slice(b"one more line\n");
    Ok(lines)
}).await?;

If two writers change the same file at once (two runs on one project file, the iterations of a parallel loop), neither loses the other’s change. If the file changed between the read and the write, edit reads it again and runs your function again on the new content. Because it can run more than once, the function must use only the bytes it is given: no counter it bumps, no call out, no other read. Returning the bytes unchanged writes nothing.

The file keeps its key, so every reference already handed out now reads the new content. It also keeps its scope, name, type and lifetime. A reader sees either the old bytes or the new ones, never a mix. What comes back is the file’s value with its new sizeBytes and version.

Every edit is recorded on the run, and the node’s panel in the graph lists it under “Files edited”: the file, the versions it moved between (v4 → v5), and the lines that changed (a diff longer than 100 KB is cut short at a line boundary). A file that is not text shows its old and new size.

If you want to overwrite the file whatever it holds now, without reading it, use replace(&file, bytes). It shows under “Files edited” too, with the new size instead of the changed lines.

An asset cannot be edited or replaced, and neither can a file value that points at a URL.

Versions

Every stored file value carries a version: 1 when the file is made, going up every time the content is written. A key always names the same file, so a key plus a version always means the same bytes.

If you seed a run that would reuse a step whose file has changed since, the run is refused; for what to do then, go and read when a reused step’s file changed.

Storing the same thing twice

let storage = ctx.storage(StorageScope::Project).identified("slack:F123456");

identified names what the file is a copy of. Put it twice and it stores once, and with put_from_url a source you already have costs no request at all.

Name the source, like <service>:<id>, not the content.

Reading

Handing a file out

public_link returning None is not a failure. It means the store is private and nothing is relaying it. If you are handing a file to a provider’s API (an image to edit, a video to dub), call external_url instead of writing that fallback yourself.

If your install answers on more than one address (the loopback port, a tunnel, a domain), caller_link builds the link on the one the caller used, so a browser on http://127.0.0.1:14111 gets a loopback link even while the tunnel is open. If no request started the run (weft run --fire), the link uses the install’s internet address, or its own address when it has none.

Whole values full of files

A chat history with three images in it is a typed value with three file markers buried inside it. Two calls handle that.

externalize(&value, &ty, policy) walks every file slot the type names, at any depth, and turns each into a link or inline bytes depending on what the consumer takes. A provider that accepts image URLs but only inline audio gets exactly that.

internalize(&value, &ty, keep) is the reverse: it takes a value full of data: URLs and external links and stores them, giving you back something you can emit and that will still work tomorrow.

The rule that makes it safe: the link never leaves your node, and the marker never leaves weft. Anything you emit, park on, or memoize is stripped back to the stored form for you. What externalize gives you is no longer a value of that type, because presigned links expire, so hand it to whoever asked and do not store it.

What a stored file looks like

It is a marker naming its kind, and the kind comes from the mime type when it was stored.

Inside is the key, the mime type, the size and the filename. No URL, which is deliberate: a link expires and a marker does not, so the marker is what goes on wires and into the journal.

The marker is a one-key object, and the key names the kind: __weft_image__, __weft_video__, __weft_audio__ or __weft_blob__. A stored PNG looks like this on a wire:

{
  "__weft_image__": {
    "key": "acme/project/3f2a9c1e-7b4d-4e0a-9c55-2d1f0e8a6b17/5b0c2e44-1a9f-4c3e-8d2b-6f7a9e0c1d23",
    "mimeType": "image/png",
    "sizeBytes": 48213,
    "filename": "chart.png"
  }
}

File is shorthand for all four and Media is shorthand for the first three. Both are fine on a port. Neither can be the type on an @asset, because a value carries exactly one marker and those leave it open.

NodeOutput::stored_file(stored) fills the four ports a file travels as at once: file, filename, mimeType and sizeBytes.

Surviving a restart

A node can park for a week waiting for somebody to answer, and cost nothing while it waits. The trick is that the worker goes away and a fresh one picks the run back up.

Which means your body runs again from the top.

Read that twice, because everything on this page follows from it. When the answer arrives, a new worker replays your function from line one. It does not resume inside your await. It starts over.

What is remembered and what is not

So the shape is: do the work, wrap anything expensive or irreversible in ctx.run, wait, then emit.

let quote = ctx.run("fetch quote", || async {
    let body = ctx.http().get(url).send().await.node_err("fetching the quote")?;
    Ok(json!(body.text().await.node_err("reading the quote")?))
}).await?;

let answer = ctx.await_signal(Form::approval("Send this?")).await?;

ctx.pulse_downstream(NodeOutput::new().set("approved", answer)).await

Without ctx.run, that fetch happens again every time somebody takes a day to answer.

Waiting on a job a service runs

If your node starts something slow on a provider (a video render, a dubbing job, a site crawl) and the provider hands back a status address, do not loop and sleep in your body: that holds a worker for the whole job. Submit the job inside ctx.run, then wait on the status address with PollEndpoint:

use weft::signal::{PollEndpoint, Predicate};

let submitted = ctx.run("submit", || async {
    post_json(&http, &submit_url, &payload, "submitting the render").await
}).await?;
let id = submitted["request_id"].as_str().node_err("the submit answered no request_id")?;

let status = ctx.await_signal(PollEndpoint {
    url: format!("{API}/requests/{id}/status"),
    interval_secs: 5,
    access: Some(weft::primitive::AccessRef::from(&account)),
    filters: vec![
        Predicate::neq("status", "IN_QUEUE"),
        Predicate::neq("status", "IN_PROGRESS"),
    ],
    ..Default::default()
}).await?;

The run parks and the worker goes away. Weft checks the address once straight away (a job that is already done resumes at once), then every interval_secs, and an interval under 5 seconds is refused. The first answer that passes every filter is what await_signal returns, and the checking stops. With no filters, the first successful answer is the one. An error status or a failed request is not an answer: it is tried again at the next check and shown on the node. access signs each check with that connection.

If the finished answer is heavy (a crawl’s status that embeds its first page of results), list the fields your node reads next in carry, like carry: vec!["status".into(), "error".into()]. The filters still read the whole answer, but only those fields are handed back, so megabytes of data never sit in the run’s history; read the rest yourself once the wait is over.

When that answer comes, your body replays from the top, so the submit has to be inside ctx.run. Without it the replay would start a second job, and pay for it.

Write the filters as “not one of the in-flight statuses” rather than “one of the finished ones”, the way the example does. A status you did not expect then ends the wait, and your code can fail on it, instead of waiting for ever.

When the run cannot pause

Some runs cannot let go of their worker: a route’s run while its caller is on the line (and the route does not outlive it), an unrecorded run, a run with a bus open. There, ctx.await_signal does not suspend. It holds in your call, on the same worker, and returns the answer when it comes, without replaying anything. If the run stays quiet for its trigger’s holdSecs, the call fails with WeftError::WaitGaveUp, saying why. That is an outcome of your step like any other: if your node can do something sensible without the answer, match it and carry on.

let approved = match ctx.await_signal(Form::approval("Send this?")).await {
    Ok(answer) => answer,
    Err(WeftError::WaitGaveUp(_)) => json!(false),
    Err(other) => return Err(other),
};

For what holds and when the clock runs, go and read when a run cannot pause. To test it, rig.signal_given_up() makes the next wait fail this way.

Two things weft refuses

Emitting, then awaiting. A replay would emit again, and the value already went downstream.

node 'review' called await_signal after emitting or closing an output port; a
node that touches a port then durably suspends would touch it again on replay.
Emit and close after all awaits, or (for a co-alive node) stay warm with
bus.recv() instead of await_signal.

Awaiting in a node that reads a stream. A replay cannot re-pull items that were already pulled.

node 'grade' has a Generator input and called await_signal; a stream consumer's
body cannot durably suspend. Do the waiting upstream or downstream of the
stream consumer.

ctx.run is keyed on order, not on the name

The name is for reading logs. What the runtime matches on is which call this was, counting every ctx.run and every ctx.await_signal in your body.

So two ctx.run calls with the same name in a stable order are fine, and two with perfect names in an order that changes between replays are not:

ctx.run('fetch quote') call_index mismatch (counter=2, journal=1). This means
the node body's call order changed between replays. Wrap any non-deterministic
logic in ctx.run.

If your body can take a different path on a replay, whatever decides that path goes inside a ctx.run so the decision is remembered rather than remade.

When the worker dies mid-step

What happens depends on the trigger’s durable setting. For what that setting does, go and read how a run is kept.

A fast run (the default) ends cancelled with its worker, and is not run again (go and read what happens when something dies).

A durable run carries on in another worker. Each step’s start (except a pure node’s, below) is on record before its body runs, so the next worker knows exactly which steps were running when the first one went away. weft cannot tell how much of such a step’s work already happened, so the next worker fails it and says why:

the worker running 'billing' went away while it was running; it was not run
again, because it may have partly happened. Re-run from here once you have
checked what it did.

A step that was reading a stream says went away while it was reading a stream instead: the items it had read are gone from the stream, so the message tells you to run the whole run again to start the stream over.

If you want to run that step again once you have checked, weft run --from <node>=<json> starts a run there with the inputs you hand it. If the node sets catchErrors and you wired its error output, this failure goes there like any other, and that branch carries on; otherwise the run fails.

If the step that was running belongs to a pure node that does not read a stream, and had not passed a value on yet, the next worker runs it again instead of failing it. A pure node does nothing outside the run (for what that means, go and read the pure flag in metadata.json), so running it twice changes nothing. One that had passed a value on is failed like any step, because running it again would pass that value a second time.

A run parked whole on ctx.await_signal survives its worker even when it is fast, unless a caller is still on the line and its trigger leaves outlivesCaller off, or a bus between its nodes is open (for why, go and read how a run is kept). When its answer comes, the waiting step replays from the top, and its ctx.run calls give back their saved results. A fast run with one branch waiting while another still ran ends cancelled like any other fast run.

In a durable run, if a step emitted a value before the crash and the step reading it had not started yet, that value is still delivered and the reading step runs.

When ctx.run cannot save its result

ctx.run writes its result down after the closure finishes. If that write fails, the action has happened but nothing recorded it, and the step fails with:

could not save result of 'charge the card' for node 'billing': <error>. The
action may already have happened; inspect this run before repeating it.

Two things are deliberately not wrapped, because they are already safe to repeat on a replay: ctx.tag_execution keeps its place in the order, and ctx.stop_tagged finds its targets already gone.

What a resume actually does

The new worker fetches your program by hash, reads the journal to see where the run had got to, and carries on from there: a step that was running is failed, a step that was waiting replays, and every step whose inputs are ready starts.

When the worker stays

A run holding a live caller, or a bus with nodes still talking on it, keeps its worker up. Parking there is an ordinary await in the same process, not a death and a rebuild, so nothing replays.

That is why the refusal above suggests a bus for a node that has to stay warm: if two nodes are alive together and talking, they do not need durability between them.

Writing a trigger

A trigger starts runs from outside. It has two bodies instead of one.

#[async_trait]
impl Node for CronNode {
    async fn setup_trigger(&self, ctx: ExecutionContext) -> WeftResult<()> {
        let expression: String = ctx.inputs.get("cron")?;
        let timezone: String = ctx.inputs.get("timezone")?;
        ctx.register_signal(Timer { spec: TimerSpec::Cron { expression, timezone } }).await
    }

    async fn run(&self, ctx: ExecutionContext) -> WeftResult<()> {
        ctx.pulse_downstream(ctx.fan_declared(&ctx.wake.record()?)).await
    }
}

setup_trigger runs once, when somebody activates the project. run fires every time the thing actually happens.

In the metadata:

"features": { "isTrigger": true },
"firesWith": { "chatId": "String", "text": "String", "caller?": "JsonDict" }

Setup

Read your inputs, decide what should wake you, and register it. That is all.

You never listen for anything yourself. No socket, no polling loop, no webhook handler. You say what should wake you and the runtime does the holding, the renewing and the checking that the event is real.

Two things to know about it.

Setup reaches out. A trigger that waits for Slack messages registers a subscription with Slack right there. If that cannot be done, activation fails on the spot naming what is missing, rather than leaving a trigger that looks armed and is dead.

Your inputs are frozen at that moment. Whatever they were is snapshotted alongside the registration and replayed onto ctx.inputs on every firing. The nodes upstream do not run again per event. When somebody changes one, they have to run weft resync, and that is why.

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

Firing

run gets the event on ctx.wake, a bag with the same methods as ctx.inputs. Your declared inputs are there too, replaying the snapshot.

let chat_id: String = ctx.wake.get("chatId")?;

ctx.fan_declared(&ctx.wake.record()?) is the common shape: take the whole payload and fan its keys onto your same-named output ports, skipping anything you did not declare.

firesWith

Say exactly what the event carries. The ? goes on the name:

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

It is checked both ways before your body runs. A payload missing a field you declared without ? is refused, and so is one carrying a field you never declared, at the top level and nested. weft run --fire checks a payload you typed by hand against it too.

One honest caveat: nothing enforces at build time that a trigger has a firesWith, or that a non-trigger does not. A repo test holds the shipped catalog to both. A node you write is held to neither, and a typo in one of the type strings is not caught when the metadata loads, so it reaches a real firing before it fails.

What can wake you

If your node registers a SocketListen or StreamListen with a connection, the text frames it sends (and a stream’s address) can name the connection’s stored values as {name}, and the value goes in as it is. When the value is something a person typed into a line protocol, like a password in an IMAP LOGIN, write {name|quoted} instead: weft wraps it in " and escapes \ and ", so a1 LOGIN {user|quoted} {password|quoted} signs in whatever the password holds. A value with a line break in it cannot be quoted and is refused rather than sent as a second command.

ProviderEvents is the one to reach for when the service has a recipe, because it takes care of both roads: a provider that pushes to you, and one you have to dial. Go and read events from a service.

Two things a trigger cannot do

It cannot be wired from another trigger, and nothing downstream of a trigger can be an infra node. Both are refused at compile time, because a trigger’s inputs are frozen at setup and provisioning happens before any event exists.

It also cannot sit inside a loop. It registers once for the project, so a per-iteration one is not a thing.

Testing one

rig.run_setup_trigger(&CronNode, json!({ "cron": "0 0 9 * * *" })).await.ok()?;
assert_eq!(rig.registered_signals().len(), 1);

let outcome = rig.wake(json!({ "scheduledTime": "2026-01-05T09:00:00Z", "actualTime": "2026-01-05T09:00:01Z" }))
    .run(&CronNode, json!({})).await.ok()?;

fake is the top tier for a trigger. The live rig drives a plain run body, so a live test on a trigger is refused.

Talking to a live caller

Most runs have nobody waiting. A run started by an HTTP request or a WebSocket does, and that caller is holding a connection open while your program works.

Your node gets at them through the ctx.

let caller = ctx.http_caller().await?;
caller.respond(OutboundChunk::json(json!({ "ok": true }))).await?;

Finding out whether there is one

Those are two separate questions rather than one enum, because a node can branch three ways: HTTP, WebSocket, or nobody.

ctx.caller_request() does not wait for the connection, because the handshake is known the moment the run starts. It gives you the method, the path, the route parameters, the query, the headers and whatever identity the gate established.

Getting the handle

Each of those folds together “is anybody there”, “is it the right protocol” and “wait for the connection” into one call. Use the specific one when your node only makes sense behind a route, and live_caller when it works either way.

Answering over HTTP

caller.respond(OutboundChunk::json(json!({ "answer": text }))).await?;

Streaming is write repeatedly, then close. That is how an answer appears in somebody’s browser a word at a time while your model is still writing it.

The head can only be sent once, and sending a body after the exchange ended is an error rather than a silent nothing.

Talking over a WebSocket

let ws = ctx.ws_caller().await?;

while let Some(msg) = ws.recv_next().await? {
    let reply = handle(msg)?;
    ws.send(OutboundChunk::json(reply)).await?;
}

There is also a cursor, so a node joining late can read from a chosen point rather than only from now: cursor(), cursor_from_start(), cursor_at(offset) and cursor_including_last().

A caller is not durable

This is the thing to hold on to. A caller is a socket in one worker. It is not written down and it cannot be rebuilt.

So a run holding one keeps its worker alive, and a node in that run cannot park for a week the way a human step does. If your program needs both, do the long wait in a different run and answer the caller with something it can come back for.

If the caller goes away, that is not your node failing. It reads as the run being cancelled, which your node can notice with ctx.is_cancelled() and stop doing expensive work.

In a test

rig.attach_caller(conn);

The fake rig gives you a caller to talk to, so a route node’s behaviour is testable without an install or a real socket.

Streams and buses in Rust

For which of the two you want, go and read streams and buses. This is the Rust on both sides.

Producing a stream

Declare a Generator[T] output, then emit as many times as you like:

for chunk in response_chunks {
    ctx.pulse_downstream(NodeOutput::new().set("chunk", chunk)).await?;
}

Each emission is one item, checked against the element type. When your body returns, the port closes and that is the end of the stream. To end it early, ctx.close_port("chunk"). After a close, nothing can follow.

pulse_downstream sends and carries on. If you are producing faster than the consumer reads, use yield_downstream, which waits until each item is taken.

If you do neither and run far ahead, you hit the cap at 4096 un-taken items and the emit fails, telling you the three ways out: yield instead of pulse, let the consumer catch up, or ctx.set_max_buffered_items("chunk", n).

Consuming a stream

Read the port like any input, then pull:

let rows: Generator<Row> = ctx.inputs.get("rows")?;

while let Some(row) = rows.next().await? {
    // one row at a time
}

Your body starts when the first item arrives, so you are running while the producer is still producing.

next() waits for the next item and gives you None once, at a clean end. try_next() is the same without waiting, answering Item, Empty or Finished. drain() takes the lot and waits for the end. end() tells you whether the producer finished or failed, or None while it is still open.

The ? matters. If the producer failed, that is where you find out, rather than getting a clean end you would mistake for an empty stream. drain errors without handing back the partial list, for the same reason.

Reading the port twice gives you two handles over one stream, sharing a position, not two copies.

Your node cannot durably suspend. A stream cannot be replayed, so ctx.await_signal in a stream consumer is refused. Do the waiting upstream or downstream.

Hosting a bus

let bus = ctx.open_bus("channel", BusOptions::default(), "host").await?;
bus.send(MessageKind::Json, json!({ "text": "hello" }))?;

open_bus does the whole producer move: makes the bus, emits the marker on that port, and registers your name. The guard closes the bus when it drops, so every way out of your function, including a panic, ends the channel instead of leaving readers parked forever.

Joining one

let bus = ctx.join_bus("channel", "translator")?;
bus.wait_for("host")?;

let mut cursor = bus.cursor();
while let Some(msg) = cursor.next().await {
    // ...
}

join_bus resolves the bus on that input and registers your name, with the same close-on-drop guard.

For an observer that must not close the bus, a debug tap that comes and goes, use ctx.bus_from_input("channel") instead.

Registering is the “I am here and ready” moment. A node with a slow warmup should hold the bus and register when it is genuinely ready, because that is what everybody else’s wait_for is waiting on.

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

wait_for(name) parks until that name is live, or returns an error if the bus closed first. You never have to decide whether a name will ever turn up: the engine watches the run, and when a wait can no longer be satisfied it closes the bus and every waiting cursor wakes.

Choosing options

BusOptions::default()
    .ephemeral(true)
    .window(256)
    .payload(BusPayload::Bytes)

Ephemeral is for a firehose. Video frames should not stall because a reader is slow, and should not end up in permanent storage either. A slow reader on an ephemeral bus silently skips to the oldest message still held, because there is no backpressure: the camera does not wait.

On a journaled bus, a send is refused if the record cannot be written, before anything is appended. On an ephemeral one it never is, because its record is notes rather than the data.

In both, who joined and who left is always kept, so nothing a reader needs can hide in a gap.

What a send tells you

Failures are values, never silent drops: the bus was closed, you never registered, you sent the wrong payload shape, or the record is degraded.

The one thing to remember

A bus lives exactly as long as its worker. It is not rebuilt when a worker restarts, and a marker resolved afterwards fails saying the bus is unknown.

It is for nodes that are alive together right now. Anything that has to survive goes in storage, or through a step that ends.

Cancelling and steering runs

Nothing kills your node

A cancelled run trips a flag. Your node is what acts on it. If your body never looks, nothing stops it, and the only sign is a run that never ends.

So anything that waits needs a way out:

let cancel = ctx.cancellation();

tokio::select! {
    result = do_the_long_thing() => result?,
    _ = cancel.cancelled() => return Ok(()),
}

For a loop, the cheap synchronous read:

for row in rows {
    if ctx.is_cancelled() { return Ok(()); }
    ...
}

That one is cheap enough to call every iteration.

The flag is sticky. Once it is set, every later check sees it, so there is no race between the cancel arriving and your next look.

What needs an arm: every wait, every long call to somebody else, and every read that could block for minutes.

Stopping other runs

A run can tag itself, and a run can stop every run carrying a tag.

ctx.tag_execution(["chat_7"]).await?;
ctx.stop_tagged("chat_7", StopSelf::Keep).await?;

That is the debounce shape. Somebody sends three messages in a row; the third run stops the first two and answers once.

It reaches running executions, ones parked on a signal or a timer, whose wake is erased so they never come back, and ones whose wake is already on its way, which find the run gone and do nothing. Each one is recorded as cancelled, naming this run and the tag, so it reads as a decision rather than a failure.

It never crosses a project.

Tag first, then stop

StopSelf::Keep only reaches runs that took the tag before this one did.

That is what stops two runs killing each other. Two messages arriving milliseconds apart both say “stop the others, keep me”, and because the order is by when each tagged itself, the later one survives and the earlier one stops. Without that rule you would get both dead, or neither.

So tag at the top of your node, then stop. A node that stops before it tags is not in the order yet.

The stop is not immediate

stop_tagged returns when the request is durably queued, not when the other runs are gone. Do not write a node whose next line assumes they stopped.

A tag is [A-Za-z0-9_-], one to sixty-four characters, but you can hand either call any string that is not empty. If you pass a chat id or an email address, weft keeps the readable part, swaps every other character for _, and adds a short fingerprint of the original, so 49151@s.whatsapp.net becomes 49151_s_whatsapp_net- followed by sixteen hex characters. Both calls and the runs list’s tag filter do this the same way, so the same value always lands on the same tag, and two values that only differ in the swapped characters never share one. Tagging twice with the same tag does nothing, which is what makes it safe to replay.

In a test

The fake rig does not stop anything. It records what your node asked for, and you assert on that:

assert_eq!(rig.execution_tags(), vec!["chat_7"]);
assert_eq!(rig.stops().len(), 1);

Taking down what your own run uses

StopSelf is also the last argument of every call that takes part of the project down (ctx.infra("bridge").stop(..), terminate(..), ctx.trigger("receive").deactivate(..), ctx.runs().clean(..)). For what Keep and Include do there, go and read taking something down from a run.

In a test, rig.program_calls() lists every such call with the StopSelf it passed. If your node reads something back, such as an infra copy’s status, rig.answer_program_call("weft.infra.status", ..) sets what that call returns in the test.

Infrastructure nodes

Some nodes need something running: a database, a model server, a bridge that holds a session open. Your node returns a description of it, and the supervisor makes what runs match it: Docker containers on your machine, or a Compute Engine machine of its own on a cloud install.

"requires_infra": true,
"images": ["images/credential"],
"publishes": "postgres"

async fn provision_infra(&self, ctx: InfraProvisionContext, input: ValueBag)
    -> WeftResult<InfraSpec>
{
    let database: String = input.get("database")?;
    Ok(InfraSpec {
        units: vec![Unit {
            name: "db".into(),
            containers: vec![Container { /* image, env, ports, probes */ }],
            ..Default::default()
        }],
        volumes: vec![Volume { /* the disk */ }],
        endpoints: vec![Endpoint { name: "sql".into(), /* ... */ }],
        ..Default::default()
    })
}

Declaring requires_infra: true without writing provision_infra is an error naming your node, rather than a silent nothing.

The spec

A unit is a group of containers that run side by side, with optional init containers that run one after another before them. It also says what machine it needs (machine: cpu, memory, and gpu with a kind and a count) and what stop does to it (onStop: stop it, or keep it running until terminate). On a cloud install, weft picks the cheapest machine that holds those numbers, shared-core ones included: a quarter CPU with 1Gi is Compute Engine’s e2-micro. A number left unset is the sum of the containers’ own limits. If you need one machine type in particular, machine.kind names it (n2-highmem-8) and skips the pick. On your machine weft caps each container that has no limits of its own at the unit’s numbers, and refuses a unit that asks for a GPU you do not have.

Whoever uses your node pays for that machine, so if the right size depends on their load, give the node inputs for it and read them into machine: the Postgres node takes cpu, memory and machineType. On your machine weft cannot pick a GPU by kind, so a unit that asks for any GPU gets every GPU the machine has, and weft infra start and weft infra status warn you about it.

A unit asking for one L4 GPU, with the CPUs and memory beside it:

Unit {
    name: "model".into(),
    machine: MachineShape {
        cpu: Some("8".into()),
        memory: Some("32Gi".into()),
        gpu: Some(Gpu { kind: "nvidia-l4".into(), count: 1 }),
    },
    ..Default::default()
}

The kinds a cloud install attaches are nvidia-l4 (1, 2, 4 or 8 on one machine), nvidia-tesla-t4 and nvidia-tesla-p4 (1, 2 or 4), and nvidia-tesla-v100 (1, 2, 4 or 8). Any other kind or count is refused when the machine is picked, and the refusal says what is allowed. The CPUs and memory you ask for must also fit a machine with that many GPUs.

Each container also takes two probes: readiness says when it is up, and liveness restarts it after failureThreshold failures in a row.

The spec has to be stable

Write the same spec every time, for the same inputs. weft compares what you return against what is running, and re-applies when they differ.

So never generate a password inside provision_infra. Every call would produce a different spec, and your database would be redeployed on every check.

If your container mints its own credential on first boot, that is what ctx.publish_access is for: the container makes it, your node publishes it once, and ctx.published_access() reads it back afterwards.

Local images

A Dockerfile in your node’s own folder, named in images:

postgres/database/
  metadata.json       "images": ["images/credential"]
  images/credential/
    Dockerfile

The last path segment is the name you reference in the spec. The path is relative to your node’s directory.

An upstream image reference passes through exactly as you wrote it, and a mutable tag is not resolved to a digest. So postgres:16 rolling underneath you produces no change in the spec and no re-apply. Pin by digest if you want an image change to actually land.

Reaching it

let endpoint = ctx.endpoint("sql").await?;
let (host, port) = endpoint.host_and_port()?;

ctx.endpoint(name) resolves one of your declared endpoints and waits until something actually answers there, rather than handing you an address the moment the container reports ready.

By default (Expose::Project), only the project’s own workers and infrastructure can reach an endpoint. If you want anything else to reach it, set expose:

• Expose::SameNetwork opens it to programs on the install’s own network: anything running on your machine locally, the install’s private network on a cloud, but never the internet. A frontend uses this to reach a program’s database.
• Expose::Public { path: "/hooks" } opens it to the internet, over HTTP, at the install’s public address. Hand the caller (a provider delivering webhooks, say) public_url().

The install serves every project at that address, so your /hooks lives under a prefix of its own: public_url() is <address>/infra/<project>/<copy>/hooks (<copy> names this copy of the node), and the install strips the prefix again, so your container still sees /hooks. weft infra status prints the same address under the node. On a cloud install it is the install’s own address. On your machine it is the tunnel’s address while the tunnel is open (a public address), and http://127.0.0.1:14111/... while it is closed, which nothing on the internet can reach.

If an endpoint hands out a credential, keep it to the project. The Postgres node shows the split: the port Postgres answers on is SameNetwork, because reaching it still takes a password, but the small server that hands out that password stays reachable only by the project.

It works during provisioning after the apply, and in every later phase once the infrastructure is running. If the endpoint is not declared, or the infrastructure is down, the error says which and points at weft infra status.

When a program marks your node @per_instance, each instance of the program gets its own container, and ctx.endpoint answers with the copy of the instance the run is for; your node’s code does not change. Each copy has its own address, so its public_url() is its own too. A connection your node publishes (ctx.publish_access) from an instance’s copy is recorded as that instance’s. For what an instance is, go and read programs with instances.

Outputs saved with the infrastructure: baking

If an output only says where your infrastructure is or how to connect to it (an address, a database connection), it stays the same from one run to the next, so weft can save it when the infrastructure is applied and stop running your node just to hand it out. Mark it baked in metadata.json:

{ "name": "access", "type": "Access", "baked": true }

(Baked outputs have nothing to do with weft bake, which prepares a trigger’s settings.)

Only an infrastructure node can bake an output: on any other node, the catalog refuses to load the metadata and names the output.

Every time the infrastructure is applied (weft infra start, weft infra upgrade, weft infra rebake <node>, or a program’s own ctx.infra(..).start()), weft runs your node’s run right after and saves what it sent on its baked outputs alongside that infrastructure. A baked output your run sent nothing on keeps the value saved last time.

While the infrastructure is running, if everything a run reads from your node comes from baked outputs that have a saved value, your node does not run: the saved values go down its wires instead. Nodes that only fed your node do not run either. Your node’s log says why: did not run: everything this run reads from it is baked, so its saved <outputs> went out instead. The Postgres node bakes access, so a route that queries the database gets the saved connection without the Postgres node running. If you want your node to run anyway (to debug it), name it in the run: weft run --target <node> or --from <node> always runs it.

If a run also reads an output that is not baked (a bridge’s status, which changes while the bridge runs), your node runs as usual, and if its run sends nothing on a baked output, the saved value goes out on it instead of the output closing. Only wires into nodes that are part of this run count: a status wired to a node outside the run does not make your node run.

If your container changes a value itself (a password reset from a button, say), have it POST the new value to the address in WEFT_VALUES_URL:

curl -X POST "$WEFT_VALUES_URL" -H 'Content-Type: application/json' \
  -d '{"connection": {"password": "the-new-one"}}'

connection changes values inside the connection your node published, and outputs replaces saved baked outputs by name ({"outputs": {"<output>": <value>}}).

weft sets WEFT_VALUES_URL in every container of your unit, init containers included, and refuses a spec that sets it. A push only ever changes the copy whose container sent it. weft does not check a pushed value against the output’s type. A saved value that does not fit its output’s type, pushed or left over from older code, is never handed out: a run that reads it runs your node instead, and if your run sends nothing on that output the run fails saying what this node's infra saved for its baked outputs no longer fits them.

The request answers 200 once weft has written the value. If you name a key the connection does not store or an output with nothing saved, or send connection from a node that published none (or several), it answers 422 with a body that names the problem, and nothing is written. Any other answer means nothing was written either, and 502 means weft could not be reached at all.

If you want a button for this, give one of the items on your container’s panel an action: {"label": "Reset password", "actionKind": "reset_password", "confirm": "<what to ask before pressing>"}. For serving a panel, go and read showing something in the graph. A press reaches your container as a POST to /action with {"action": "<actionKind>", "payload": null}, or with the button’s own payload if you gave it one. For how to answer it, go and read letting other nodes reach it.

If the push fails, or a value changed without anything telling weft, the person running the program fixes it with weft infra rebake <node> (add --instance <id> for a @per_instance node’s copy). It applies your infrastructure again, restarting nothing that already matches its spec, then runs your node’s run and saves what it sends. That only helps if your run reads the current value from your infrastructure instead of trusting what it published last time. The Postgres node does this: it asks its credential container whether the password it holds is still the current one, and reads the new one when it is not.

If your container pushes from a button and the push fails, answer the press with {"result": {"error": "..."}} telling the person to run weft infra rebake <node>, the way the Postgres node’s Reset password button does. You do not need to add that hint anywhere else: when any node fails after opening the connection your node published, weft adds a line to that node’s error naming weft infra rebake <node>.

If you change what your run emits on a baked output, runs that skip your node keep handing out the old saved value until it bakes again. weft infra upgrade builds your current source, then stops the infrastructure and starts it again. If you would rather restart nothing, build first (weft build, or any weft run) and then run weft infra rebake <node>, which runs whatever weft built last.

Without --instance, the upgrade stops the program’s shared infrastructure and starts it again. A @per_instance node’s copies are left alone, so run it with --instance <id> for each instance whose copy should bake your new code. For what an upgrade does to running work and to triggers, go and read choosing what happens to work in flight.

Letting other nodes reach it

If other nodes need to talk to your service (say, a WhatsApp bridge that every send node goes through), pass them a handle instead of url(). The address changes every time your service is set up again. The handle names your node, as it is named in the program, and its endpoint, so it still finds the service after that.

Declare an output typed Infra and set it to the endpoint’s handle:

{ "name": "bridge", "type": "Infra" }

let api = ctx.endpoint("api").await?;
ctx.pulse_downstream(NodeOutput::new().set("bridge", api.infra_handle())).await

A node that uses it declares an input typed Infra and resolves it:

let bridge: InfraHandle = ctx.inputs.get("bridge")?;
let bridge = ctx.endpoint_of(&bridge).await?;
let sent = bridge.action("sendMessage", json!({ "to": to, "text": text })).await?;

ctx.endpoint_of gives back the same handle ctx.endpoint does, so url() and call(..) work on it as well. action(name, payload) posts {"action": name, "payload": payload} to the service’s /action and gives you the result of its answer. Your service answers {"result": ...}. action returns an error when your service answers non-2xx, when the answer has no result, or when result carries an error string (the error then reads <action>: <error>). An error that is not a string comes back as part of the result. The buttons of a live panel post to the same /action, so one handler in your container serves both.

An Infra input only takes a handle from an Infra output. The compiler refuses a String wired into it, and it refuses a value typed into it by hand. A handle only works inside its own project. It only reaches infrastructure the program still declares. For a node marked @per_instance, it reaches the copy that belongs to the run’s instance.

A long job in your container

If your service runs something long (a render, a training run), have it answer POST /jobs with an id at once and a status route like GET /jobs/<id>, then wait on that route the way a node waits on a provider’s job: start it inside ctx.run and park with PollEndpoint on format!("{}/jobs/{id}", api.url()). For the whole pattern, go and read waiting on a job a service runs.

api.url() is the address your workers reach, and the checks are made by the listener, which on a local install sits on the machine rather than in Docker’s network. Before every check it asks for the same endpoint’s address as weft’s own roles reach it, looked up in this project’s infra only, so the address you pass works as it is.

If somebody stops the run while it waits, none of your code runs: the run ends cancelled and the checks stop, but the job in your container carries on. If it should stop too, have the container give up on a job whose status nobody has asked for in a few intervals; terminating the infra stops it as well.

A live panel

If your container serves /live, name that endpoint and the editor shows the panel on your node:

"features": { "liveEndpoint": "api" }

That is how a bridge shows the QR code you have to scan. Go and read showing something in the graph.

What the supervisor does

It takes an exclusive lease on the project, applies your spec, and watches whether what it created is healthy. For what happens when a supervisor dies halfway through a change, go and read the supervisor.

A unit that was healthy and stays not ready past its flaky window (health.flakyAfterSeconds, 30 seconds by default) is marked flaky, and one that stays ready again past health.recoveryAfterSeconds (also 30) is marked running again. weft infra status shows which.

There is no time limit on coming up, because a model server pulling weights can take a long time. Somebody waiting on yours reads weft infra logs <node> and cancels if it will never come.

Two things a user has to do themselves

Nothing starts your infrastructure for them. Not a run, not a build, not activation. weft infra start is a verb they type, because a container costs money and weft will not spend it on a click that did not mention one.

And weft infra stop keeps the disk while weft infra terminate deletes it. If your node has data worth keeping even through a terminate, name its disk in keepOnTerminate. The next weft infra start of the same node (the same instance’s copy, for a node marked @per_instance) finds that disk and mounts it again, data and all. If you want a kept disk gone, drop it from keepOnTerminate, start the node once so the copy knows about it, and terminate.

A kept disk is deleted for you once its copy can never come back: when you remove the node from your program and run it again, when the node switches between shared and @per_instance (which leaves the old side’s copies behind), or when you remove the project with weft rm. This holds even if the copy was already terminated at the time. The supervisor sweeps for such copies on every ownership tick, so the disk goes within one tick of the change.

If you wipe an instance (the WipeInstance node, or ctx.infra(node).instance(id).wipe(..) from your own node), the kept disks of that instance’s copies go right away, including those of a copy that was already terminated.

Testing one

let outcome = rig.run_provision_infra(&PostgresNode, json!({ "database": "app" })).await.ok()?;
let spec = outcome.infra_spec()?;
assert_eq!(spec.units[0].name, "db");

fake is the top tier here too. For a node that calls its own infrastructure, declare where each endpoint answers, then what each call gets:

rig.declare_endpoint("credential", "http://localhost:8080");
rig.refuse_endpoint("credential", EndpointMethod::Get, "/password", 503, "starting");
rig.answer_endpoint("credential", EndpointMethod::Get, "/password", json!({ "password": "minted" }));
let outcome = rig.run(&DatabaseNode, json!({ "database": "app" })).await.ok()?;
assert_eq!(rig.endpoint_calls().len(), 2, "asked twice: refused, then answered");

method is EndpointMethod::Get or EndpointMethod::Post.

Each answer and each refusal is used by exactly one call, in the order you declared them, so declare one per call you expect. That is how a node that asks twice and acts on the answer changing (refused, then answered) gets tested. A call with nothing left to answer it fails the run and names answer_endpoint, so a question your node should not have needed to ask shows up instead of being quietly answered.

Testing a node

Tests live beside the node, in a tests.rs in its own folder. An access node has none: the access_node! macro is its whole body, so there is nothing of yours to test.

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));
    Ok(())
}

mod.rs bridges it in:

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

#[async_trait]
impl Node for WordCountNode {
    #[cfg(feature = "node-tests")]
    fn tests(&self) -> Vec<weft::NodeTest> {
        tests::tests()
    }
    // ...
}

There is no registry and no list to maintain. The runner walks the nodes the binary already has and asks each one for its tests.

weft test-node WordCount        # one node
weft test-node slack            # one package
weft test-node                  # everything

Three tiers

Basic and fake run by default. Live never runs unless you ask, and the runner confirms before it does.

Basic and fake run right there with cargo: they need no Docker and no runtime, and only the packages you targeted get built.

Two things to know. A basic test is a plain sync function and the runner is already inside an async runtime, so building one inside it panics. And for a trigger or an infra node, fake is the top tier: the live rig drives a plain run body, so a live test on those is refused.

A fake test that never finishes fails by name after 30 seconds, and tells you where to look:

test 'reads the stream' did not finish within 30s. Something in it is waiting
for what it never gets: a cursor reading a bus nothing closes, a caller nobody
attaches, a signal nobody answers.

The fake rig

The outcome gives you .ok() for the happy path, .failure() for the error string, .output(port) for one port, .infra_spec() for an infra run, and .outputs for the map.

Note the last group: in a fake test nothing is really stopped and nothing is really tagged. The rig records what your node asked for, and that is what you assert on.

Rig reference

If you need a rig call’s exact signature, or the fields of what it hands back, it is here.

The fake rig

Setting the run up:

Running it:

Looking at what happened:

The live rig

LiveRig::new(..) is built by the runner, never by a test.

What comes back

RunOutcome, from every run:

SentRequest, one per request:

EndpointCall, one per call to the node’s own infrastructure:

Live tests

weft test-node SlackSendMessage --tier live

The runner tells you it will spend money and asks. --yes skips that, and it can remember your answer.

For credentials, --connection slack=<grant-id> uses one you already have, and --key slack takes a throwaway one: each field comes from WEFT_NODE_TEST_SLACK_<FIELD> if it is set, or a prompt, never from the command line where other processes can read it. The grant is deleted afterwards.

Every prompt happens before any credential exists and before any signal handler is armed, so Ctrl+C at a prompt leaks nothing.

--fixture values, declared with .with_fixture(...) on a live test, are how a test names the real thing it needs: a channel it may post in, an account it may read. Read them with rig.fixture("NAME").

What to write

Ship a fake test for every node. If it talks to a provider, ship a live one on the cheapest real path you can find.

A panic fails that test, carrying its message, and never takes the runner down.

Packaging

Several nodes that belong together, sharing code and dependencies.

slack/
  package.toml
  api.rs                shared code
  metadata.json         optional defaults for every node here
  access/
    metadata.json
    mod.rs
  send_message/
    metadata.json
    mod.rs
    deps.toml

package.toml is short:

[package]
name = "slack"

[dependencies]
# cargo deps every node here gets

Its presence is what makes the folder a package, and the members are found by looking rather than listed.

Shared code

Any .rs at the package root becomes a module, and a node reaches it as super:

use super::api;

That is where the request-building and the error-reading for one service goes, written once instead of in every node that talks to it.

Each package compiles as its own crate, so a node sees its own package’s shared files and nothing else. Another package’s code is never on your path.

It also means editing one node recompiles that package and relinks, rather than rebuilding the world.

A shared file whose name is not a valid Rust identifier fails at build time naming the file.

Defaults

A metadata.json at the package root is a partial document every node inherits, key by key, with the node’s own value winning.

Put types, tags, an icon, a color or a service recipe there once.

type, label and description can never be defaults. They are one node’s identity, and the compiler refuses a package file carrying any of them:

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

The merge is shallow: a node’s types replaces the package’s rather than adding to it.

When a folder does not load

If a node or a package has something wrong with it, only that folder is left out. Every other node still loads, and a program that never uses the broken one still compiles. A program that does use it fails with the reason:

node 'Poll' failed to load: package name 'feed' is used by more than one
folder (nodes/rss/feed, nodes/mine/feeds); ...

Names have to be unique across all your node folders: a node type, a service, and a package name (a package is named by its package.toml, a bare node by its folder). If two folders claim the same name, both are left out and each error names the other, so you pick which one to rename.

If you write a package.toml before any of its nodes, the package just waits, and it loads once a node folder with a metadata.json and a mod.rs is there. weft describe-nodes lists everything that was left out, and why.

deps.toml

Per node, and every section is optional.

[dependencies]
reqwest = { workspace = true }

[system.runtime.apt]
default = ["ffmpeg"]

[system.build.apt]
debian_12 = ["pkg-config", "libssl-dev"]

[build.env]
SOME_PATH = "{{catalog_path}}/vendor"

Managers are apt, apk, yum and brew. Under each, a key per distribution like debian_12 or alpine_3_19, or default for all of them. weft looks for the exact key, falls back to default, and fails only when neither is there.

[build.env] is deliberately narrow. Real build logic goes in a build.rs.

What you get without asking

weft, tokio, serde, serde_json, async-trait, anyhow and tracing are always there. So is weft-providers.

weft also re-exports serde_json, reqwest, reqwest_middleware, async_trait and inventory, so you can name those types without declaring a dependency on them.

Local images

An infra node’s containers are built from Dockerfiles in its own folder:

postgres/database/
  metadata.json       "images": ["images/credential"]
  mod.rs
  images/credential/
    Dockerfile
    bootstrap.py

The path is relative to the node’s own directory, not the package root, and the last segment becomes the name you reference in the spec.

How connections work

A credential never appears in your program. It lives in weft’s own store, and what travels a wire is a reference with nothing secret in it.

Four things that sound alike

For OAuth the first two are different things: the app is the software asking, and the connection is the account that said yes. A pasted API key needs no app and is still a connection, and so is a hostname, a username and a password for a mail server.

What actually travels

{
  "__weft_access__": {
    "accessId": "11111111-2222-3333-4444-555555555555",
    "service": "slack",
    "identity": "Q @ Acme",
    "requiresPermissions": ["chat:write"],
    "requiresValues": []
  }
}

The two requires lists are stamped on per consuming node, from what that node said it needed. So the same connection carries different requirements depending on which step is about to use it, and one that falls short is refused when that step opens it rather than halfway through a call.

Shared, or your own

own is the default. Offering shared is something a service’s recipe has to declare, and what sits behind it is whatever the operator put in the apps file.

A permission a recipe marks as only working on your own account can never be served by the runtime’s credential. The editor greys that option out and resolution refuses it.

An instance’s own connections

In a program with instances, an access step whose connection is written account: @instance_filled holds no connection in the source: each instance gets its own, and a run for that instance uses it. For how that works, go and read programs with instances.

What weft can actually tell you about a credential

Providers differ in how much they admit, and weft records which kind of answer it got.

That distinction decides what gets blocked. A permission weft knows is missing blocks the node that needs it. A permission that is only claimed, or unknown, lets the call through, because refusing would block every pasted key on every service that reports nothing.

Stored values are simpler and have no unknown case: if a node needs imap_host and the connection has not got one, the node never starts.

Connecting also runs the service’s own check, but only when that check is free. Anything paid, or ambiguous because it might bill depending on the account, is skipped, so a bad credential sometimes shows up for the first time when a step tries to use it.

One thing that is always checked: if you tick permissions and the provider hands back fewer, the connect is refused naming the one you did not get.

Refreshing

Lazily, when a step opens the connection, and only if the token expires within the next minute. There is no background keep-alive.

Two things opening the same connection at once queue behind each other, so it refreshes once and both get the fresh values.

When a refresh cannot happen, it fails loudly rather than retrying into nothing:

the 'slack' access needs reconnecting: the provider issued no refresh token,
so the expired sign-in cannot be renewed

A pasted credential that expired says so too, because there is nothing to refresh it with.

Where the secrets are

Sealed with AES-256-GCM, under CREDENTIAL_ENCRYPTION_KEY, which is 32 bytes in base64:

openssl rand -base64 32

Service names, client ids, which permissions were granted and who owns what stay readable, so weft can query them. Only the credentials themselves are sealed.

Without that key set, weft uses a public development key built into its own source and warns you once. That key is in the repository, so anyone with a copy of your database can read every credential in it. Set a real one before you store anything you care about.

There is no rotation. Change the key and everything sealed under the old one is unreadable:

stored credential data does not open under the current CREDENTIAL_ENCRYPTION_KEY;
if the key changed, the sealed rows it wrote are gone: reconnect the affected
connections

Putting the old key back reads them again. Losing it means reconnecting everything.

The rest

For connecting one, go and read connecting an account. For using one inside a node, using a connection in a node. For writing a recipe, declaring a service.

The apps file

access-apps.json is where the operator puts the applications and keys this installation offers as one-click connections. Whatever is in it shows up in everybody’s connect panel.

Start from the example and keep what you want:

cp access-apps.example.json access-apps.json

Fill in the services you expect to use often. A service you set up here is one click forever after, and one you skip asks each person to bring their own the first time they need it, which is fine for something you touch once.

The shape

A service name maps to a list, always, even with one entry. Keys starting with _ are ignored, which is how the example file carries its own notes.

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

A pasted key

This is what “use ours” hands out. Calls on it spend money on that account, so keep the file private.

An OAuth application

{
  "slack": [{
    "kind": "oauth_app",
    "label": "Slack",
    "covers": ["chat:write", "channels:read", "channels:history"],
    "auth_url": "https://slack.com/oauth/v2/authorize",
    "token_url": "https://slack.com/api/oauth.v2.access",
    "client_id": "...",
    "client_secret": "...",
    "events": { "signing_secret": "..." }
  }]
}

Permissions are fixed per app. People pick an application rather than ticking boxes, which is why you can list several for one service: a cheap tier that avoids a provider’s review process, and a fuller one beside it. Each shows up as its own labelled choice with its permissions listed.

The addresses are pinned here, and a recipe that tries to substitute a different sign-in address is refused. A connection through a registered app only ever talks to the addresses you wrote.

You also have to register the callback URL the connect panel shows you as the app’s redirect URL, and re-register it whenever your public address changes. Some providers, Slack among them, only accept https callbacks.

Making it take effect

On your machine, weft reads the file each time it needs one of its keys, so an edit takes effect at once. If the file is gone, weft has no shared apps or keys until it is back. On a cloud install the file is the WEFT_ACCESS_APPS secret of your fork: if you want to change it, update that secret and run install on GCP again (deploying to your cloud).

If you want to keep it somewhere else, point WEFT_ACCESS_APPS_FILE at it and run weft daemon start. If the file is there but cannot be read or parsed, every lookup of its keys fails with an error naming the file, because shipping no apps quietly shows up later as a service nobody can connect on a node the operator thought was configured.

What it refuses

• A service whose value is not a list
• An entry with no kind
• Two entries with the same label in one service
• More than one api_key for a service
• An OAuth app with no covers
• A permission in covers that the service’s catalogue does not have
• An events block on a service with no webhook transport
• Invalid JSON, or a file you configured that is not there

Apps a node ships

A node’s own metadata.json can declare accessApps for public applications with no secret. Those need PKCE, and metadata carrying a client_secret is refused: node metadata is source, and source never holds secrets.

An application with a secret belongs in this file.

Encryption

Everything stored is sealed under CREDENTIAL_ENCRYPTION_KEY, which is 32 bytes in base64:

openssl rand -base64 32

Set it before you store a credential you care about. Without it weft uses a public development key from its own source and warns you once, which protects a database dump from nobody.

Keep it. There is no rotation: change the key and everything sealed under the old one is unreadable until you put it back. Lose it and you reconnect everything.

Using a connection in a node

Declare an Access input with the connect widget:

"inputs": [
  { "name": "account", "type": "Access", "required": true,
    "widget": { "kind": "access" },
    "requiresScopes": ["chat:write"] }
]

Write just {"kind": "access"}. The service and whether it is optional are filled in from your node’s service recipe.

Then open it:

let account: Access = ctx.inputs.get("account")?;
let client = ctx.open(&account).await?.client();

let reply = client.post("https://slack.com/api/chat.postMessage")
    .json(&body).send().await.node_err("posting the message")?;

That client already has the authentication, the routing and the metering on it.

Sending the call and reading the answer

Every API node does the same three things after building a request: send it, fail with the provider’s own words when the status is not a success, and read the body. weft::access::client has that once, so your node does not write it again:

what names the attempt, so a failure reads “the service answered 403 trying to post the message” instead of a bare status code.

If your node waits on a job the provider runs, go and read waiting on a job a service runs.

The one rule about HTTP

A call on a connection goes through ctx.open or ctx.client. Everything else goes through ctx.http().

A reqwest client you build yourself skips both the signing and the cost recording, and the call will either fail unauthenticated or succeed while nobody writes down what it cost.

ctx.client accepting None is for a node whose connection is genuinely optional, like fetching a link that is usually public.

What an opened connection knows

Keep those out of your outputs and out of your logs. Anything you emit is journaled and shows in the inspector.

Saying what you need

requiresScopes and requiresValues on your Access input are the important part, and they are per consuming node.

{ "name": "account", "type": "Access", "requiresScopes": ["channels:history"],
  "requiresValues": ["imap_host"] }

Those get stamped onto the value as it reaches you, and checked when you open it. So a node that needs to read history refuses a connection that can only write, before it makes the call, and the person is told to reconnect rather than getting a provider error they have to decode.

The list is all-of, and it is fixed by the node’s one job. When the permission would depend on which input arrives, like a post that needs one scope for a person and another for a company page, that is two nodes, each declaring its own. One node with the rule written in prose protects nobody.

A missing stored value always refuses. A missing permission only refuses when weft actually knows it is missing: on a service that reports nothing, the call goes through and the provider decides.

A long job

A lease covers the firing. For something that genuinely runs a long time, a multi-hour generation, ask for a window:

let conn = ctx.open_within(&account, Duration::from_secs(3 * 3600)).await?;

The default is fifteen minutes, which is generous for an API call including its stream and its cost resolution, and short enough that a lease left by a crashed worker goes stale the same quarter hour.

A connection your own node hands out

If your node runs the service, it publishes the connection rather than consuming one:

let access = ctx.publish_access(BTreeMap::from([
    ("host".into(), host), ("password".into(), password),
])).await?;
ctx.pulse_downstream(NodeOutput::new().set("access", access)).await

Declare it in metadata with "publishes": "postgres" and an Access output.

Publishing again updates rather than duplicating, and terminating the node’s infrastructure deletes it. ctx.published_access() reads back what you published before, which is how a container that mints its own password on first boot is asked for it exactly once.

In a test

let access = rig.access("slack");
rig.connection_value("slack", "team_id", "T123");
rig.connection_permissions("slack", ["chat:write"]);

let outcome = rig.run(&SendNode, json!({ "account": access, "text": "hi" })).await.ok()?;
rig.assert_sent("POST", "/api/chat.postMessage");

No real credential, no real call, no cost.

Declaring a service

A service recipe is the service block in an access node’s metadata.json. It is pure declaration: how a credential is obtained, how a request is signed, what the permissions are, how events arrive. There is no Rust per service.

The node itself is one line:

weft::access_node!(SlackAccessNode);

The top level

Acquisition

The grant is authorization_code with an auth_url and PKCE on by default, or client_credentials.

There is a fourth, runtime, and you never write it. It is the stored form of a shared connect, written by the store, and declaring one is refused.

Auth steps

How a request gets signed, applied in order:

Every value is a template interpolating stored values by name, like "Bearer {token}".

A header step’s name can be a template too, for a connection where the person types which header their key goes in (a generic API key): { "kind": "header", "name": "{header}", "value": "{key}" }. It may only name a declared field that is not secret, and if what the person typed is not a legal header name, the call is refused before anything is sent, telling them to reconnect.

Permissions

{ "id": "chat:write", "label": "Send messages",
  "description": "Post messages as the app.", "default": true }

A curated catalogue, not the provider’s whole list. On a provider with hundreds of scopes, list the ones your nodes actually need and point all_permissions_url at the rest.

default: true starts it ticked. own_only: true means the runtime’s own credential can never serve it, which greys out the shared option for anyone who ticks it.

Verification

Say honestly what your check can learn:

Only the first two make the recorded permissions authoritative, and only those let weft block a node before it calls.

cost is free, ambiguous or paid, and only free runs on its own. A check that might bill is never run without being asked.

Today every service in the shipped catalog declares free, and nine of the thirteen declare reports_validity. So in practice the only way a connection is genuinely verified right now is the OAuth scope echo, where the provider tells weft what it granted. A probe rung exists in the type and nothing implements it.

Your own door

own_page is what that door shows:

A paste block on a static acquisition is refused as redundant: those fields already render.

What it refuses

The validator is strict, and the messages name the fix. A service name with a capital in it. A header name that is not a legal header name. A capability listing a field the service does not declare, or listing a required field, since a required field can never be the thing that is missing. A permission with no description. A service that signs its requests offering the shared door. A token_echo caller check, which compares a token weft minted when subscribing and a route’s caller never has.

Events

Each topic under events says which facts to pull out of a payload, which account it belongs to, and how it arrives. Go and read events from a service.

Where it goes

A package root’s metadata.json, so every node in the package inherits it, or the access node’s own file.

Exactly one input in the node needs the access widget. That is the connect control, and a recipe without one is refused.

Events from a service

A trigger that waits for a Slack message, a new row in a sheet, a page changing in Notion. The service has something to tell you, and there are two roads it can travel.

The two roads

Dial out. weft makes an authenticated call that hands back a socket address, connects out, and holds the line. Nothing needs to reach your machine, so this works from a laptop behind a router.

Dial in. The service posts each event to an address you published. That needs a public address, and it is the only road a shared application can use, and the only road most services offer at all.

You never choose. You name a connection and a filter, and the transport follows from what the service declares and what your environment can serve. On a cloud install, if the service can push these events for your account, weft takes the push, so nothing has to stay running between events. Otherwise weft dials out when it can, because that needs nothing from you.

What a topic declares

A service declares a map of topics, because one provider can genuinely report along several independent channels at once.