NAME

zeughaus-glossary - terms of art used in the zeughaus manual

DESCRIPTION

One entry per term the manual uses in a specific sense, in alphabetical order. Each entry points to the page that covers the term in depth.

TERMS

.zgh

A graph saved as a file: the JSON GraphDocument of zeughaus-core/src/document.rs, written with Ctrl+S and read with Ctrl+O (Cmd+S and Cmd+O on macOS). The store is never written from a file behind the user's back. See zeughaus-files(5).

artifact

A file a job run declares through its artifacts setting (globs relative to cwd), copied under artifacts/ in the run directory when the child exits. See zeughaus-architecture(7).

async work

Work a node hands to its context instead of blocking a pass (an LLM request, a portal capture, the wait for a job). The executor marks the node pending and holds its downstream back until the host delivers the result with deliver_async_result; a pending node is never dispatched twice. See zeughaus-architecture(7).

boundary node

A graph.input or graph.output node directly inside a container. The editor synthesizes the container's pins from its boundary children, named by each child's title, and stores an edge drawn onto such a pin against the boundary child. See zeughaus-architecture(7).

clock

What makes a source produce more than once: a node asks for periodic runs through tick_interval(), and flow.timer is the clock node. Without one upstream, a capture node produces one frame and stops. See zeughaus-nodes(7).

container

A node type with no pins of its own that holds other nodes through their parent column: graph.sub and db.database. Deleting a container deletes its contents; only the editor knows about nesting, the store and the executor see one flat graph. See zeughaus-architecture(7).

converter

A coercion registered per type pair in TypeConverters; the one built-in is Int -> Float. Editor and runner build the same registry from the same plugins, so what may connect and what is coerced agree. See zeughaus-architecture(7).

delta

The terminal rows changed since the sequence number a client holds, sent by the runner's mux on a terminal exchange. A delta is computed per subscriber, so a slow client gets fewer, larger deltas and never a queue. See zeughaus-architecture(7).

derived parameter

A node parameter the editor computes rather than the user typing it: db_path (from the enclosing db.database), relations (from wires between field pins), renamed_from (a table's previous name). The runner applies it like any other params key. See zeughaus-architecture(7).

detached terminal

A runner-owned terminal (a job's) that no pane shows; the workspace snapshot lists it under detached. The palette's "Terminal / Attach" gives it a pane, and closing that pane detaches it again instead of killing it. See zeughaus-architecture(7).

dirty set

The nodes the next pass runs. A changed node marks everything downstream dirty; the nodes of a cycle, and everything downstream of it, are dropped from it with one node error. See zeughaus-architecture(7).

drain

How a runner stops on SIGINT or SIGTERM: it holds itself and exits once no job run is live, logging what it is draining; adopted runs count as live. A runner with no live runs exits at once. See zeughaus-architecture(7).

edge cache

The executor's per-edge record of the last value and a generation counter. InputSet::changed(pin) compares that generation with the one the node saw last, which is how a node acts only on its own trigger. See zeughaus-architecture(7).

editor

zeughaus, the iced application that edits the graph and shows what the runner reports; it never executes a node and does not depend on zeughaus-runtime. Any number of editors may join one session. See zeughaus(1).

endpoint

The pinned root URL of a runner, weida://sha256:<fp>@<host>:<port>/, announced in its runtime row and printed at start. The fingerprint makes the address trustworthy without distributing a certificate; the runner CLI takes it as its endpoint argument. See zeughaus-runner(1).

field pin

A pin with PinDirection::Both, drawn spanning the node, such as a db.table column. A wire between two field pins is a relation, not dataflow. See zeughaus-architecture(7).

frame feed

The stream of frames for one node pin on /samples: a viewer sends one FeedRequest naming the size it draws, and the runner writes the newest frame scaled to a ladder tier until the viewer stops reading. Frames never touch the store. See zeughaus-architecture(7).

graph

A top-level graph.sub node (parent 0) and everything inside it. It names the runner that executes it in its runner column, is what a graph tab shows, and is deleted by closing its last tab. See zeughaus-architecture(7).

group

A coloured, collapsible set of tabs inside a runner's section; groups nest one level only. The locked Triggered group is filled by the runner alone. See zeughaus-keys(7).

hold

The job host's flag: held, a runner starts no new run and lets the live ones finish. Set over /hold by the palette ("Runner / Hold", "Runner / Release") or zeughaus-runner hold. See zeughaus-runner(1).

incarnation

One runner process (RunnerIncarnation). Everything a client cached about a workspace or a terminal belongs to one incarnation; after a SIGUSR1 restart the incarnation is new while terminal and tab ids stay the same. See zeughaus-architecture(7).

job

A job.run node: a process with a beginning and an end, run in a terminal the runner owns, so a failed job is a terminal to attach to. See zeughaus-architecture(7).

ladder tier

One of the heights the runner scales a frame to for a viewer: 240, 360, 480, 720 or 1080 lines. Two viewers of similar size share one scaled result. See zeughaus-architecture(7).

lease

The right to type, resize and move the mouse in a terminal; exactly one client holds it, any client may view. The first client that types acquires an unowned terminal, Ctrl+Shift+T takes it over, and a lease survives a network blink of up to 10 s. See zeughaus-architecture(7).

link

The runner-to-editor protocol over weida (zeughaus-link): /events, /snapshot, /triggers, /samples, /mux, /runs and /hold. It carries everything a pass produces; the store carries none of it. See zeughaus-architecture(7).

mux

The runner's terminal multiplexer: it owns every terminal and serves a canonical screen, as rows and deltas, to every editor over /mux. PTY bytes never leave the runner. See zeughaus-architecture(7).

node error

The message a failing node leaves, published as NodeError and withdrawn as NodeErrorCleared. The node's downstream is held back; everything unrelated runs. See zeughaus-architecture(7).

outbox

The editor's queue of local edits bound for the store, replayed after a reconnect. Settings edits enter it 400 ms after the last keystroke and are flushed on close. See zeughaus-architecture(7).

palette

The command palette, opened with Ctrl+Space (on macOS also Cmd+Shift+P). It acts on the whole window (tabs, panes, terminals, the graph) and holds the keyboard while open. See zeughaus-keys(7).

pane

A leaf of a tab's split tree: a terminal or a graph. Each pane draws its own graph, and the focused pane's graph is where the palette spawns nodes. See zeughaus-keys(7).

pass

One run of GraphExecutor::execute_dirty: the dirty nodes in topological order. A failing node or a cycle does not fail the pass. See zeughaus-architecture(7).

A typed connection point of a node: an input, an output or a field. Inputs are trigger pins or sample pins. See zeughaus-architecture(7).

press

A manual trigger: a flow.button or job.run pressed from an editor, or a zeughaus-runner trigger from a script, sent over /triggers. A press may carry a trigger payload. See zeughaus-runner(1).

profile

A runner-side description of what a terminal starts (the login shell). A client creates terminals only from profiles or attaches ones the runner created for a job; no mux command carries an argv. See zeughaus-architecture(7).

reducer

A function of the SpacetimeDB module (create_node, connect_edge, ...), the only way to change the store's tables. Conflicts are last-writer-wins per row. See zeughaus-architecture(7).

relation

A wire between two field pins: a declared relationship between two nodes that carries nothing and is excluded from execution. Between db.table nodes it becomes a FOREIGN KEY. See zeughaus-architecture(7).

restore file

<state-dir>/restore-<pid>.json, written by an editor on SIGUSR1 before it execs itself; the new process reads and deletes it through ZEUGHAUS_RESTORE. It carries window size, active tab, cameras, selection, palette and terminal scroll-back, not the window position. See zeughaus-files(5).

run

One execution of a job. Run ids continue past whatever is on disk, so a restart never reuses one; a restarted runner adopts runs that have no exit record. See zeughaus-architecture(7).

run directory

<state-dir>/runs/<id>/, holding a run's log, exit, code and artifacts/. The program sees it as ZEUGHAUS_RUN_DIR, and the job node's dir output carries it. See zeughaus-files(5).

runner

zeughaus-runner, the headless process that executes graphs and owns the terminals and job runs of its editors. It executes exactly the graphs that name it and refuses to start without a store. See zeughaus-runner(1).

sample pin

An input declared with PinKind::Sample: state read whenever the node runs, drawn as a circle. See zeughaus-architecture(7).

scheme

A terminal colour scheme: sixteen ANSI colours plus foreground, background, cursor and selection. It is the single source of a theme; WezTerm-format scheme files in <state-dir>/themes/ are offered as themes by file name. See zeughaus-files(5).

scratch graph

The local graph an editor edits without a store: nothing computes it, and it is gone on close unless saved as a .zgh file. Its tabs sit in the Local section. See zeughaus-architecture(7).

section

A part of the tab bar: one per connected runner, labelled with its host and the start of its fingerprint, plus Local or Not running. Tabs never move between sections. See zeughaus-architecture(7).

seeded wire

A newly drawn edge that add_edge fills with the source's last output instead of recomputing the source; only the target's subtree is dirtied. A node with side effects does not fire again because a wire was drawn. See zeughaus-architecture(7).

session

One SpacetimeDB database that editors and runners join with join host[:port]/database; without it, the default session on 127.0.0.1:3000/zeughaus. The runner prints the token others join with. See zeughaus-install(8).

setting

A key the editor configures a node through (SettingDef), of kind Text, Multiline, Title or Fields. The value is always text, stored in the node's params; a node that refuses it returns InvalidParameter and every editor shows the reason. See zeughaus-nodes(7).

shim

The process that holds one terminal's PTY and child on unix: the runner binary started as zeughaus-runner shim <state-dir>/terminals/<id>. It keeps the last 4 MiB of output for the next session and outlives the runner, so shells and job runs survive a restart. See zeughaus-architecture(7).

state directory

Where a process keeps its credentials, runs, terminals and preferences: --state-dir on the runner, else ZEUGHAUS_STATE_DIR, else $XDG_STATE_HOME/zeughaus, else ~/.local/state/zeughaus. One runner per state directory. See zeughaus-files(5).

store

The SpacetimeDB database running zeughaus-module, holding the tables node, edge and runtime: the graph document and who runs it, nothing a pass produces. See zeughaus-architecture(7).

subgraph

A graph.sub container nested inside a graph, with graph.input and graph.output boundary nodes as its pins. Its open button opens its contents in a tab of its own. See zeughaus-nodes(7).

theme

The editor's look (zeughaus-theme): an iced::Theme paired with a terminal colour scheme. Chosen per window from the palette and persisted in <state-dir>/editor.toml. See zeughaus-architecture(7).

trigger payload

Optional text carried by a trigger (TriggerRequest { node_id, payload }) that becomes the node's fire parameter; a bare press sends none. A job's program sees it, or a string arriving on run, as ZEUGHAUS_PAYLOAD. See zeughaus-runner(1).

trigger pin

An input declared with PinKind::Trigger: an event the node acts on when something arrives, drawn as a square. The node checks InputSet::changed(pin) to know that it fired. See zeughaus-architecture(7).

Triggered group

The locked group in a runner's section that holds the terminal tab of every run started by zeughaus-runner trigger. Only the runner fills it and no tab is dragged out of it; a press from an editor leaves its run detached. See zeughaus-runner(1).

type id

The string that names a node type, prefixed by its plugin (transform.sin, job.run); stored in the node table's type_id. See zeughaus-nodes(7).

weida

The QUIC transport with mutual TLS that the link runs on, a sibling repository of zeughaus. It redials a lost peer; zeughaus resyncs on top. See zeughaus-architecture(7).

workspace

A runner's tabs, groups, splits and terminal ids, owned by the runner, shared by every editor as that runner's section, and saved to <state-dir>/workspace.json so a restarted runner restores it. See zeughaus-architecture(7).