feat(nodes): add void, an explicit terminal sink for fire-and-forget branches

CHANGELOG.md

@@ -39,6 +39,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **New node kind: `void`, a terminal sink.** It accepts items on `main`,
+  discards them, and activates nothing — the branch ends there, on purpose. A
+  branch could always dead-end (a node with no outgoing edges terminates), but
+  an unwired port reads exactly like a forgotten one, so there was no way to
+  declare "this is a side effect and nothing waits on it". `spawn → void` is now
+  the explicit spelling of a ticket no `gate` will collect; the abandon
+  semantics are unchanged from leaving it unwired. It adds **no** concurrency:
+  work upstream still runs inline in its own super-step, and only the result is
+  dropped. Its slot is `{items: [], port: null, discarded: N}`, which keeps
+  "never activated" (no slot at all), "activated with nothing to drop" and
+  "dropped N items" distinguishable.
+
+  Validation refuses a `void` with any outgoing edge — including the `error`
+  edge `on_error: "route"` would otherwise demand, which is reported directly
+  rather than as a `MissingErrorRoute` the next rule would then reject — and one
+  with no incoming edge, since a node with no effect and no input declares
+  nothing.
+
+  The scatter-lane dead-end rule is relaxed accordingly: a lane branch ending in
+  a `void` is now legal, making it the one dead end a lane may have. The rule
+  exists to catch *accidental* invisibility (a lane activation never writes the
+  node's top-level slot), and a `void` is the author declaring it. A `scatter`
+  with no `gather` anywhere is still refused, void downstream or not.
+
+  Not included, deliberately: no lint for a `spawn` with neither a `gate` nor a
+  `void` downstream. `validate_all` has no severity tier, and making it a hard
+  error would break the documented "fire-and-forget is legal" contract. A
+  possible future addition if a warning channel ever lands.
+
 - **Configurable agents.** An `agent` node can now be given dynamic context,
   an explicit tool allow-list, a model and provider, a working directory,
   advisory limits, and arbitrary harness metadata — while the agent

README.md

@@ -244,6 +244,7 @@ done
 | `merge`         | Fan-in barrier that combines multiple inputs; waits for all wired predecessors.              |
 | `split_out`     | Fan-out that emits one item per element of a list.                                           |
 | `transform`     | Pure, expression-based data transform / field mapping over the run state.                    |
+| `void`          | Terminal sink: discards its input and runs nothing downstream — the explicit dead end.       |
 
 See the [Node Catalog](../../wiki/Node-Catalog) wiki page for config keys and
 ports.

src/catalog.rs

@@ -33,7 +33,7 @@ use group_03::*;
 
 /// The node kinds, in the canonical order used wherever the DSL is enumerated
 /// (matches [`NodeKind`](crate::model::NodeKind)'s serde discriminators).
-pub const NODE_KINDS: [&str; 20] = [
+pub const NODE_KINDS: [&str; 21] = [
     "trigger",
     "agent",
     "tool_call",
@@ -54,6 +54,7 @@ pub const NODE_KINDS: [&str; 20] = [
     "gate",
     "scatter",
     "gather",
+    "void",
 ];
 
 /// One config field a node of a given kind reads at run time.
@@ -204,6 +205,7 @@ pub fn contract_for(kind: &str) -> Option<NodeKindContract> {
         "gate" => contract_gate(),
         "scatter" => contract_scatter(),
         "gather" => contract_gather(),
+        "void" => contract_void(),
         _ => return None,
     };
     Some(with_fan_out_fields(c))

src/catalog/contracts/group_02.rs

@@ -371,8 +371,9 @@ pub(super) fn contract_spawn() -> NodeKindContract {
                  the same, the concurrency is not. That is a silent performance cliff, so check \
                  the host wires a TaskRunner before relying on overlap."
                 .to_string(),
-            "Fire-and-forget is legal — a spawn no gate ever collects simply runs. If that \
-                 is not what you meant, wire a `gate`."
+            "Fire-and-forget is legal — a spawn no gate ever collects simply runs. Wire the \
+                 spawn into a `void` to say that on purpose; wire it into a `gate` if you \
+                 actually wanted the results."
                 .to_string(),
         ],
     }

src/catalog/contracts/group_03.rs

@@ -115,3 +115,49 @@ pub(super) fn contract_gather() -> NodeKindContract {
         ],
     }
 }
+
+pub(super) fn contract_void() -> NodeKindContract {
+    NodeKindContract {
+        kind: "void".to_string(),
+        summary: "Terminal sink: accepts items, discards them, and runs nothing downstream."
+            .to_string(),
+        description: "The branch ends here, on purpose. A branch could always dead-end — a \
+                          node with no outgoing edges terminates — but an unwired port reads \
+                          exactly like a forgotten one, so there was no way to SAY \"this is a \
+                          side effect and nothing waits on it\". This node is that sentence. It \
+                          adds no concurrency: the work upstream still runs inline in its own \
+                          super-step, and only the result is dropped. For work that should \
+                          actually overlap, use `spawn`."
+            .to_string(),
+        config_fields: vec![],
+        ports: PortSpec::new(&["main"], &[]),
+        example: json!({
+            "id": "drop", "kind": "void", "name": "Fire and forget: audit log",
+            "config": {}
+        }),
+        notes: vec![
+            "An outgoing edge is a validation error, and so is having no incoming edge. \
+                 `on_error: \"route\"` is refused for the same reason — an `error` edge is an \
+                 outgoing edge; use \"stop\" or \"continue\"."
+                .to_string(),
+            "It writes {items: [], port: null, discarded: N} into its slot. A node that never \
+                 ran has no slot at all, so \"never activated\", \"activated with nothing to \
+                 drop\" (discarded: 0) and \"dropped N items\" stay distinguishable."
+                .to_string(),
+            "`discarded` counts THIS activation, not a running total: inside a loop body the \
+                 last iteration's value is what survives, and inside a scatter lane it lands \
+                 under lanes.<lane> rather than at the top level."
+                .to_string(),
+            "spawn -> void is the explicit spelling of a ticket no `gate` will ever collect. \
+                 Same abandon semantics as leaving it unwired, but said out loud."
+                .to_string(),
+            "It is the one dead end a scatter lane may have. Every other lane branch must \
+                 reach the `gather`, because a stranded lane's output is invisible rather than \
+                 merely uncollected — a void makes that invisibility the contract."
+                .to_string(),
+            "There is no `reason` config. The node's `name` is where the human explanation \
+                 goes, and unlike a config key it is rendered in the graph."
+                .to_string(),
+        ],
+    }
+}

src/catalog_tests.rs

@@ -23,7 +23,7 @@ fn every_node_kind_has_a_contract() {
             }
         }
     }
-    assert_eq!(all_contracts().len(), 20);
+    assert_eq!(all_contracts().len(), 21);
 }
 
 #[test]
@@ -48,8 +48,8 @@ fn unknown_kind_has_no_contract() {
 }
 
 #[test]
-fn node_kinds_has_20_entries_including_the_async_and_lane_pairs() {
-    assert_eq!(NODE_KINDS.len(), 20);
+fn node_kinds_has_21_entries_including_the_async_and_lane_pairs() {
+    assert_eq!(NODE_KINDS.len(), 21);
     assert!(NODE_KINDS.contains(&"shell"));
     assert!(NODE_KINDS.contains(&"memory"));
     assert!(NODE_KINDS.contains(&"dedup"));
@@ -67,6 +67,29 @@ fn node_kinds_has_20_entries_including_the_async_and_lane_pairs() {
     assert_eq!(NODE_KINDS[17], "gate");
     assert_eq!(NODE_KINDS[18], "scatter");
     assert_eq!(NODE_KINDS[19], "gather");
+    assert!(NODE_KINDS.contains(&"void"));
+    assert_eq!(NODE_KINDS[20], "void");
+}
+
+#[test]
+fn void_contract_takes_no_config_and_declares_no_output_port() {
+    // The two claims an authoring tool acts on: there is nothing to configure,
+    // and there is nowhere to draw an edge to. Both are enforced by validation,
+    // so the contract must not suggest otherwise.
+    let c = contract_for("void").expect("void contract exists");
+    assert!(
+        c.config_fields.is_empty(),
+        "void takes no config; the reason goes in the node's name"
+    );
+    assert_eq!(c.ports, PortSpec::new(&["main"], &[]));
+    assert!(
+        c.notes.iter().any(|n| n.contains("outgoing edge")),
+        "the contract must say an outgoing edge is refused"
+    );
+    assert!(
+        c.notes.iter().any(|n| n.contains("spawn -> void")),
+        "the contract must document the ungathered-ticket spelling"
+    );
 }
 
 #[test]

src/fan_out_contract_tests.rs

@@ -24,6 +24,7 @@ fn kinds_that_cannot_map_do_not_advertise_them() {
         "merge",
         "transform",
         "code",
+        "void",
     ] {
         let c = contract_for(kind).expect("contract");
         assert!(

src/model/node_kind.rs

@@ -98,6 +98,23 @@ pub enum NodeKind {
     /// and leave the stragglers, or settle for whatever arrived before its
     /// deadline. See [`crate::nodes::release`].
     Gate,
+    /// Terminal sink: accepts items on `main`, discards them, and activates no
+    /// successors. The branch ends here, on purpose.
+    ///
+    /// Purely declarative. A branch could always dead-end — a node with no
+    /// outgoing edges is lowered straight to the engine's `END` sentinel — but
+    /// an unwired port reads exactly like a forgotten one, so there was no way
+    /// to *say* "this is a side effect and nothing waits on it". This kind is
+    /// that sentence. It adds no concurrency: the work upstream of it still
+    /// runs inline in its own super-step, and only the result is dropped.
+    ///
+    /// Abandon semantics, identical to an ungathered [`NodeKind::Spawn`]
+    /// ticket — nothing is drained or cancelled at run end. `spawn` → `void` is
+    /// the explicit spelling of a ticket no [`NodeKind::Gate`] will collect.
+    ///
+    /// [`crate::validate`] refuses a `void` that has any outgoing edge, or that
+    /// has no incoming edge at all.
+    Void,
 }
 
 /// How a [`NodeKind::Trigger`] node is fired.

src/model/node_kind_tests.rs

@@ -29,6 +29,7 @@ fn node_kind_variants_use_snake_case() {
     assert_wire(&NodeKind::SubWorkflow, "sub_workflow");
     assert_wire(&NodeKind::Memory, "memory");
     assert_wire(&NodeKind::Dedup, "dedup");
+    assert_wire(&NodeKind::Void, "void");
 }
 
 #[test]

src/nodes/control_flow/mod.rs

@@ -1,8 +1,8 @@
 //! Native control-flow node executors: `condition`, `switch`, `merge`,
-//! `split_out`, `transform`, `loop`, and `dedup`. Most of these are pure — they
-//! route and reshape data within the engine and use no host capability. `dedup`
-//! is the one exception: it filters items against durable `StateStore` state
-//! (see [`dedup`] for why it lives here anyway).
+//! `split_out`, `transform`, `loop`, `void`, and `dedup`. Most of these are
+//! pure — they route and reshape data within the engine and use no host
+//! capability. `dedup` is the one exception: it filters items against durable
+//! `StateStore` state (see [`dedup`] for why it lives here anyway).
 //!
 //! One module per node kind so parallel work can edit them without conflicts.
 
@@ -15,6 +15,7 @@ pub mod scatter;
 pub mod split_out;
 pub mod switch;
 pub mod transform;
+pub mod void;
 
 pub use condition::ConditionNode;
 pub use dedup::DedupNode;
@@ -25,3 +26,4 @@ pub use scatter::{MAX_LANES, ScatterNode};
 pub use split_out::SplitOutNode;
 pub use switch::SwitchNode;
 pub use transform::TransformNode;
+pub use void::VoidNode;

src/nodes/control_flow/void.rs

@@ -0,0 +1,102 @@
+//! `void` — the terminal sink.
+//!
+//! A `void` node accepts items on `main`, discards them, and activates nothing.
+//! It is the end of its branch, and that is the whole feature.
+//!
+//! # Why a node for something the graph could already do
+//!
+//! A branch could always dead-end: [`crate::engine`] lowers any node with no
+//! outgoing edges straight to the state-graph's `END` sentinel, and `END` is
+//! filtered out of routing, so it contributes nothing to the next super-step's
+//! active set. Wiring nothing to a port has exactly the same effect.
+//!
+//! What was missing is the *statement*. A port left unwired reads identically
+//! to a port someone forgot to wire, so an author could not declare "this
+//! branch is a side effect; nothing downstream waits on it", and a reviewer
+//! could not tell intent from an accident. A `void` says it in the graph, where
+//! both the reader and [`crate::validate`] can see it.
+//!
+//! One place that ambiguity was resolved *against* the author: a branch inside
+//! a [`scatter`](crate::model::NodeKind::Scatter) lane that dead-ends is a hard
+//! validation error, because a lane activation never writes the node's
+//! top-level slot and so a stranded lane branch produces a wrong answer rather
+//! than a failure. `void` makes that invisibility the contract instead of the
+//! accident, and is therefore the one dead end a lane may have.
+//!
+//! # What it is not
+//!
+//! It adds **no concurrency**. Everything upstream of a `void` still runs
+//! inline in its own super-step; only the *result* is dropped. If you want work
+//! to overlap, that is [`spawn`](crate::model::NodeKind::Spawn) and the
+//! `TaskRunner` capability, not this.
+//!
+//! It performs **no drain and no cancellation** at run end. Abandoning a branch
+//! here is exactly what an ungathered `spawn` ticket already does, which makes
+//! `spawn` → `void` the explicit spelling of "no [`gate`] will ever collect
+//! this, and I meant that".
+//!
+//! [`gate`]: crate::model::NodeKind::Gate
+//!
+//! # Configuration
+//!
+//! None. A `void` node's `name` is where the human reason goes ("Fire and
+//! forget: audit log") — it is already required, and unlike a config key it is
+//! rendered by [`crate::visualization`]. Config is ignored entirely, including
+//! `={{ … }}` expressions, so this node can emit no binding diagnostics.
+//!
+//! # What it leaves behind
+//!
+//! `{ "items": [], "port": null, "discarded": <n> }` in its run-state slot.
+//! Emitting nothing would otherwise be indistinguishable from never having run,
+//! since a node that never ran has no slot at all — so the three cases stay
+//! separable:
+//!
+//! | slot | meaning |
+//! |---|---|
+//! | absent (`null`) | never activated |
+//! | `discarded: 0` | activated, had nothing to drop |
+//! | `discarded: 3` | activated, dropped three items |
+//!
+//! `discarded` counts **this activation's** input, not a running total. Two
+//! consequences worth knowing: inside a `loop` body it is overwritten every
+//! iteration, so the value that survives is the last one; and inside a scatter
+//! lane it lands at `nodes.<id>.lanes.<lane>.discarded` rather than at the top
+//! level, because a lane activation deliberately never writes the top-level
+//! slot. A cumulative counter was considered and rejected for exactly those two
+//! reasons — it would silently mean something different in each context.
+
+use async_trait::async_trait;
+use serde_json::json;
+
+use crate::error::Result;
+use crate::nodes::{NodeContext, NodeExecutor, NodeOutput};
+
+/// Stable `tracing` grep prefix for every log line this node emits.
+const LOG_PREFIX: &str = "[void]";
+
+/// Terminal sink: discards its input and activates no successors.
+///
+/// See the [module docs](self) for why an explicit node beats an unwired port.
+#[derive(Debug, Default, Clone)]
+pub struct VoidNode;
+
+#[async_trait]
+impl NodeExecutor for VoidNode {
+    async fn execute(&self, ctx: NodeContext<'_>) -> Result<NodeOutput> {
+        let discarded = ctx.input.len();
+        tracing::debug!(
+            node = %ctx.node.id,
+            discarded,
+            "{LOG_PREFIX} discarding items; nothing downstream runs"
+        );
+        // No port: emitting on one would imply a successor could match it, and
+        // `validate` guarantees there is none. The `discarded` count is the only
+        // trace the node leaves, and it is what separates "ran on nothing" from
+        // "never ran" (see the module docs).
+        Ok(NodeOutput::empty().with_meta(json!({ "discarded": discarded })))
+    }
+}
+
+#[cfg(test)]
+#[path = "void_tests.rs"]
+mod tests;