weft-language

# The weft language One way to say each thing, and the compiler refuses everything else. This page is the whole surface as of this template; when it disagrees with your memory, this page wins. Two words the whole page leans on. A [pulse] is one value emitted on one output port and addressed to one input port of one node; nothing walks the graph, a node fires when every required input holds a [pulse]. A [closed] pulse carries no value and means "nothing will ever arrive here"; a port that never receives anything is closed the same way. ## Declaring a node ````weft name = NodeType name = NodeType { config_field: value } name = NodeType {} ```` `name` is the node id, unique in its scope, snake_case. `NodeType` must exist in the project's `nodes/` catalog; you read its real ports with `weft describe-nodes --node <Type> --compact`, never from memory. ## Connecting ````weft target.input_port = source.output_port ```` Right to left: the value flows from `source.output_port` into `target.input_port`, and the types must be compatible. Every required input gets a wire or a literal; an optional one (`port?`) can stay unwired. This line is the longhand; [the shorthand] (next section) is the same wire inside the target's braces, and the one you write (`answer = Reply { body: work.answer }`, never `answer = Reply` with `answer.body = work.answer` under it). The longhand survives only where the language leaves no choice: a [boundary port], one of the ports a group, a loop, or an `@include` alias declares in its signature. If you want one key of a record value, keep going with dots (`wpm: reader.profile.stats.wpm` in the braces, or `speed.wpm = reader.profile.stats.wpm`). Still one wire; the compiler checks every key against the record type at that level and the wire carries the last key's type. Only a record type has keys to read: a source typed `JsonDict`, a `Dict[String, String]` (a route's `query` or `headers`) or a scalar has none (`deref-path`), and nothing reads one for you. Narrow the source port to the shape it carries (next), or cast it to a record type first. At run time a `?` key found absent (or `null`) closes that wire alone; a required key absent fails the firing. ### Narrowing a port to the shape it carries A port's type is a contract, and you may write a TIGHTER one on the arrow where you use the node. The compiler checks yours against the node's own and refuses a contradiction (`declared type ... incompatible with catalog type`), so a narrowing that compiles is one the node can honour. This is how a loose container becomes a shape you can read keys off, and it costs nothing at run time: the value is already that shape, the port now says so. A port the node already declares takes the tighter type the same way one you add on the arrow does. Here the node's own `rows` port is `List[JsonDict]`, which has no keys to read, and naming the row's shape makes `.title` legal: ````weft type Card = { title: String, seen: Number } rows = PostgresExecuteQuery -> (rows: List[Card]) { account: store.access query: "select title, seen from cards" } ```` A column that can be NULL is declared so in the shape: `{ title: String, extra: JsonDict | Null }`. The declared type judges every row at run time, and a `JsonDict` alone refuses a null, so a day when every row has the column empty fails the node with `emitted a value on port 'rows' that its declared type 'List[Card]' does not accept (got List[Dict[String, String | Null]])`; the fix is the `| Null` on that field, never a looser row type. A cast (a node carrying `features.castPorts`, the catalog's `Cast` being one) is for a value that has to CHANGE type while it travels. A value that already fits needs no node at all, only a port that names the type. If you catch yourself adding a cast to put a shape on a value that already has it, stop and write: "Wait. Narrow the port." Then write the type on the arrow and delete the cast. **Narrow only what you control the shape of.** A port fed by the outside world (a query string, request headers) holds whatever the caller sent, and a record refuses a key it does not declare, at run time, on the real request. Narrowing those compiles and then fails the first time somebody appends a tracking parameter, and a cast to a record is just as strict (an undeclared key fails the cast). So either declare every key the caller may send, optional ones with `?`, or leave the port as the loose type the node declares and read the one key you want with a node. When the opaque value comes from a node that lets you ADD OUTPUT PORTS, name the pieces you want on the arrow instead. Each arrives on its own port under the type you wrote, so there is nothing to unpack and nothing to cast: ```weft look = PostgresExecuteQuery(id: String) -> (title: String, seen: Number) { query: "select title, seen from cards where id = $id" } ``` Declare the type you actually want there, a named one included (`-> (card: Card)`): the value is checked against it when it arrives, so a shape that fits flows and one that does not fails loudly, naming the field. Reach for the record type when the source cannot name the pieces for you, and prefer a NAMED type over an inline one once more than one node speaks it: the name is the contract, and it is written once. ## Config values Typed JSON-ish literals: ````weft t = Text { value: "a string" } n = Range { to: 10, step: 2 } flag = SomeNode { enabled: true } arr = SomeNode { items: [1, 2, 3] } obj = SomeNode { opts: { "k": "v" } } ```` Commas between fields are optional; a field per line with no commas reads the same. `null` is never a literal: omit the field instead (`config-null-literal`). A field with a fixed list of choices (a dropdown in the editor) takes one of them and nothing else: any other written value is `literal-not-an-option`, and the message lists the choices. A list the node marks `free_text` (model ids, voices) only suggests: any value is accepted there. A list or object literal holds plain values only, so `params: [self.chatId, self.pushName]` is refused. When a node needs several values from the graph, each one is its own input port. When a node accepts however many values you give it, declare them in its inline signature: `PostgresExecuteQuery(chat_id: String, push_name: String) { ... }` and the SQL reads `$chat_id`; `Format(user: String) { template: "Hi {{user}}" }`. How a node reads those ports (a query's parameters, a template's slots) is in that node's description. A Python node whose code has no branch, no loop and no call is moving values, not deciding anything, and the language moves values. Read the code you are about to write and apply that test to it. Pulling a field out of a dict is the case you will meet most; the test is what catches the rest. If you catch yourself writing one, stop and write: "Wait. That is plumbing." Then read the key with dots, narrow the port to the shape it carries, declare the ports on the consumer, or wire `_should_flow` (under Reserved keys). Calling a library, parsing what no type describes, reshaping a list in memory: that is processing, and Python is the right answer for it. A branch or a loop that decides what the program does next (whether a step runs, which service is called, a call made once per item) is coordination, and it belongs in the graph, where each step is visible and journaled: a Boolean on `_should_flow` for the branch, a `Loop` for the repetition, one node per call. Building an object out of values you already hold (a reply body, a payload) is the case you will meet most, and it has its own node: wire a value onto each key you want and the object comes out keyed by those names. An object LITERAL cannot hold a wire, which is what used to force a script here. ### Wires in the braces A field whose value is `source.port` is a wire, written inside the node it feeds. This is [the shorthand]: a node's wires sit next to its settings: ````weft reply = TelegramSendMedia { account: telegram.access kind: "photo" chatId: ask.chatId # same as `reply.chatId = ask.chatId` file: picture.image } ```` A `Group` is the exception: its braces hold its children, so the only field it reads there is `_should_flow`, and its [boundary port]s are wired from outside on their own lines. ### A key that CREATES a port Some node types accept extra inputs beyond the ones they declare, and on those a key naming no declared port creates one. A wire types it from the source, a literal from its own type, `null` is an error. `key?:` makes the created port optional, whatever the node's own default is. Which types accept them is the node's to say, not this page's: its wiring view carries a `features` block, and `canAddInputPorts` there means you may add inputs, `canAddOutputPorts` that you may name outputs on the arrow. A node with neither key, or no `features` block at all, takes only the ports it declares. ````weft step = ExecPython -> (out: String) { code: @file("assets/scripts/step.py") text: draft.answer # a String port, from the wire limit: 3 # a Number port, from the literal notes?: review.notes # optional: a closed pulse here does not skip the node } ```` Created ports keep written order, and whether a node reads that order is the node's own business, stated in its description. Two catalog examples: `FirstInOrder` emits its first input that carried a value, so reordering its lines changes which branch wins, and `List` puts its inputs into one list, in port order, and you declare the list's type on its output. An optional port (`name?:`) that got nothing is left out. If you want several wired values as one list (several `LlmTool`s into `LlmInference`'s `tools`), that is `List`, never a Python node that returns `[a, b]`: ````weft tools = List(search: JsonDict, fetch: JsonDict) -> (list: List[JsonDict]) { search: searchTool.tool fetch: fetchTool.tool } ```` Those two are the only ways line order changes what a program does. ### Literals on a connection line ````weft post = SlackSendMessage { channel: "#alerts" } post.text = "deploy finished" ```` Both spellings are one constant, and no port takes one spelling and refuses the other. What a port can refuse is a family: `literal` (a value written in the source, markers included) or `wire` (a value another node produces), through `accepts` in its metadata; absent means both. Wrong family is `input-accepts`, and the message reads the list back ("`params` accepts: wire"). A compiler-read port (a form's `fields`, a switch's `cases`, the access picker) takes an inline typed value only: no wire, no `@file`, no `@asset`. The line also works on a [boundary port]. An output port never takes a value, on any node: `step.out = "lit"` and `out: "lit"` beside a `-> (out: String)` signature are refused, and so is a group's own output written from inside (`self.result = "lit"`). A firing emits on an output; you read it as `node.port`. ### Multi-line strings ````weft step = ExecPython() -> (out: Number) { code: ``` return {'out': 42} ``` } ```` The opening fence goes on the key's line, content starts on the next line, the closing fence on its own line. ## Reserved keys Exactly four, all starting with `_` (any other `_` key is an error): | Key | Effect | |---|---| | `_label: "..."` | display label. A string, set once, never by wire | | `_tags: ["a", "b"]` | tags, used by signal scoping | | `_should_flow: <wire or false>` | decides whether this node runs at all | | `_should_not_flow: <wire>` | the same decision read backwards: runs when what is wired here did NOT arrive | `_should_flow`: leave it out and the node runs. Wire it and the node runs only when what arrives is not `false`; a `false` or a [closed] pulse (whatever decides never spoke) skips the node, closing its outputs, skipping everything behind it. `_should_flow: false` in the braces turns one node off. Groups and Loops take it too, inside the braces or on the container's name from outside. `_should_not_flow` is the mirror image: wire something into it and the node runs when that thing closes instead of when it arrives. It is the only port in the language that can start a node on a closure; every other port does the opposite, skipping its node once an input closes, which is why running on an absence needs a dedicated spelling. Reach for it when the absence is data: a key the caller never sent, an optional input nobody filled in. When the absence is a decision a node of yours already made, put that decision on a second output port and gate on it with `_should_flow` instead; the wire then reads forwards, cause before effect. A FAILURE is not an absence. When the node it watches fails, its ports close too, but that closure carries the error, and the gate reads it: the node stays off (skipped with `what its _should_not_flow watches did not finish ('<node>' failed: <error>)`, naming the node that broke) and the run reports the failure. So a route's "no rows, answer 404" branch never fires over a database that is down; the caller gets the failure instead. A group's or a loop's outputs close the same way when something inside failed, so the rule holds one scope up, and a node that SKIPPED because its input closed on a failure closes its own ports with that failure too (its skip reason names where it started: `the required input 'value' closed because 'query' failed: ...`), so the rule holds any number of skips down the line, and every skip in that chain still names `query`, the node that broke. ### Handling a failure: the `error` output If you want the program to do something when a step that reaches outside fails (mark a row `error` with the reason, answer the caller with a message, try another branch), wire that step's `error` output. A node that declares `catchErrors` among its features gets an `error` output added by weft; read the node's interface to see whether it has one. - Wired: a failure becomes its message on `error`, the run goes on, and the node's other outputs close, so the success branch simply gets nothing. - Unwired: the failure fails the run. A bad setting, a bad input or a type error always fails the run, wired or not: those are the program's own shape, never an outcome to route around. What counts as a failure for a given node (an answer with an error status, say) is in that node's description. A step that could act outside the run is never started again after a crash. If its worker goes away mid-run, a fast run ends cancelled and a durable one fails the step that was running (How a run is kept, below, has both); only a step of a `pure` node that had sent nothing on and read no stream runs again. With `error` wired, that failure goes there like any other, and the log says `the worker running '<node>' went away while it was running` (or `while it was reading a stream`). A run waiting on a timer or a form, with nothing else of it running, survives its worker dying either way, unless its caller is still on the line with `outlivesCaller` off or a bus between its nodes is open: then its wait holds the worker (up to the trigger's `holdSecs`), and it ends with it. ````weft ask = LlmInference { provider: prov.provider, prompt: job.text } mark = PostgresExecuteQuery(reason: String, id: String) { account: db.access query: "update jobs set state = 'error', reason = $reason where id = $id::uuid" reason: ask.error id: job.id } ```` `mark` runs only when `ask` failed: its `reason` input arrives only then. This is how a program records a failure. Never catch it inside Python. A node carries one gate, never both: wiring `_should_flow` and `_should_not_flow` on the same node is a compile error, `two-gates`. The editor draws both as the same triangle, with a small circle marking `_should_not_flow`; right-click the gate to flip which one it is. `_should_flow` is also the ordering wire, and it accepts ANY port: any type, any node, no declaration needed on either side. `typed = ExecPython { _should_flow: typing.done }` means run once `typing` has fired. The value is never read, so you never invent a port to carry it (an `after: typing.done` port the code ignores puts a value on the graph that nothing reads, while `_should_flow` already shows in the graph as a permission wire). The one value that IS read is `false`, so wire a Boolean port here only when its `false` should mean "do not run". That is also how a node with nothing to receive gets its turn. `Close` takes no data at all, so ending a branch early is one wire from any port on it: ````weft bye = Close { status: 204, _should_flow: cleanup.removed } ```` A branch that skipped closes its ports, so whatever hangs off it by `_should_flow` skips with it: the branch that did not run does not act. On a group or an included file the wire means "run what is in here": a route's run takes the whole group along, and everything the group needs (a database wired into it from outside), exactly as it takes a node. ````weft live = Route { path: "live/count", method: "GET" } work = Group(db: Access) { rows = PostgresExecuteQuery { account: self.db, query: "select count(*) from cards" } out = Reply { body: rows.rows } } work.db = db.access work._should_flow = live.fired # the route runs the group; nothing else connects them ```` `Route` and `Socket` have a `fired` output, always `true` when called: gate work on `route.fired`, never on a request port like `method`. A group, and so an included file, starts only once everything the run wires into it has arrived, `_should_flow` included. A closed input counts as arrived: the group still starts and the closure goes inside to whatever reads it. Only a closed or `false` `_should_flow` skips the whole group. A node with no inputs at all inside a group runs when the group starts, so it needs no `_should_flow` to get its turn, and it never runs before the group's slowest input lands. It runs only in a run that takes it along, though: a trigger's run holds what the trigger feeds plus what those nodes read, so it takes the node along when something that run uses reads it, or when the run feeds the group's `_should_flow`, which brings in the whole group. If several routes feed one include, a route that did not fire never holds it up: it is left out of the run, or closes its outputs, which counts as arrived. At the top level of a file, an unconnected node with no inputs runs only on a manual run; a trigger's run never takes it along. ### Running something once, when the program goes live If you want something to happen once before a program serves anything (creating tables, seeding a row, warming a cache), write the node and wire it into the trigger. That is the whole mechanism, and it is worth understanding rather than memorising. Everything UPSTREAM of a trigger is the trigger's setup program, and weft runs that program once, at activation. On a fire the trigger reads none of it: a fired trigger's inputs come from its bake, so nothing upstream runs again. Any wire into the trigger puts the producer there, not only the gate. The gate is just the wire with nothing else to say: ````weft make = PostgresExecuteQuery { account: db.access, query: @file("assets/sql/schema.sql") } live._should_flow = make.count ```` Whatever that setup does, it does again on every activation, so it has to be safe to do twice: doing it a second time must not undo, duplicate or refuse what the first time did. How you write that is the node's business, and the node's own description says how; the language's part is only that it will happen more than once. The same holds for infrastructure: anything upstream of an infra node is that node's setup program and runs when infra starts. Two things follow that surprise people. A `weft run --fire` warns that the wire was not delivered, which is correct and not a problem: that wire's whole job was to run at activation. And when the trigger lives in an included file and the setup node does not, the value has to cross the include's boundary like any other, so the file declares a port for it; there is no shortcut, and keeping the setup node in the same file as its trigger avoids the crossing entirely. That second one has a limit: setup that several triggers SHARE (the schema every included file's tables live in) is written once, in the file that includes them, and each included file takes its result as a port. Every trigger's setup runs at activation as one program, and two nodes that do not depend on each other run at the same time, so two files each carrying their own `create extension if not exists pgcrypto` race each other and one of them fails on a duplicate key. "Safe to do twice" is not "safe to do twice at once". ## Inline port signatures Types that leave ports open declare them in the declaration: ````weft