Buffer Node

What Buffer is and why it exists

Buffer is the explicit state-staging primitive in NodeFox. It gives you a deterministic place to hold, merge, and release values before branching, model calls, or side effects.

In practice, Buffer is the backbone of three common production patterns:

fan-in convergence from parallel branches
iterative accumulation for loops and item-wise processing
prompt/payload composition for downstream Conversation or Writer nodes

Execution behavior

Buffer behavior is variant-driven:

Default: deterministic relay/staging behavior
Stack: accumulation across cycles
Combine: template-driven merge from multiple inputs to one or more outputs

Because Buffer can hold state over multiple cycles, lifecycle intent must be explicit. If release criteria are unclear, Stack and Combine can silently grow payload size and create late-stage instability.

Variant and field reference

Default variant

Default is a controlled pass-through and staging boundary. It is typically used as:

entry buffer for initial workflow input
branch relay for readability and handoff clarity
deterministic pre-processing boundary before expensive downstream nodes

Optional fields available in some configurations:

Field	What it controls	Practical guidance
`Cache`	Enables temporary content caching for supported model paths	Use only when cache lifecycle is clearly bounded to a run.
`Cache Model`	Model used for cache behavior	Keep model selection explicit by workflow branch, not implicit global defaults.
`System Instruction`	Optional model instruction for cache-aware behavior	Keep instructions deterministic and narrowly scoped.
`Tools` / `MCPs`	Optional tool surfaces when using AI-capable Buffer behavior	Expose only optional tools and keep call budgets bounded.

Stack variant

Stack accumulates incoming values across execution cycles and is best for iterative or fan-out return aggregation.

Field	What it controls	Practical guidance
`Variant = Stack`	Enables accumulation semantics	Pair with bounded iteration and deterministic release criteria.
Upstream `Emit On Complete` (Reader)	End-of-stream signaling for flush conditions	Use when stack release depends on full input completion.
`Keep` / `Optional` flags	Slot-level blocking/persistence behavior	Keep blocking intent explicit so Stack does not flush partial, ambiguous sets.

Stack is commonly used before summarization/reporting, bulk Writer commits, and loop-end QA checks.

Combine variant

Combine merges multiple input slots into deterministic formatted outputs using a combinations list.

Field	What it controls	Practical guidance
`Combinations`	Array of `{ template, output }` rules	Keep each rule single-purpose. Prefer multiple explicit rules over one giant template.
`template`	Input interpolation expression (e.g. `{{0}}`, `{{1}}`)	Treat template text as production contract; version and review it like code.
`output`	Destination output slot for rendered result	Document slot ownership to avoid downstream ambiguity.

Typical use: merge user request, retrieved context, and policy metadata into a canonical prompt envelope.

Production patterns that work

Parallel branches -> Buffer(Stack) -> Decision(ready?) -> Writer(Activated)
Reader + Data -> Buffer(Combine) -> Conversation
Data(For) -> Conversation -> Buffer(Stack) -> Writer
Reader -> Buffer(Default) -> Network(submodule) for stable contract handoffs

For entry buffers, define slot contracts up front (for example, slot 1 = primary payload, slot 2 = policy context, slot 3 = metadata) and keep that mapping stable.

Failure modes and mitigations

Unbounded Stack growth:
- Mitigation: bounded loops, explicit convergence Decision, and fallback branch.
Combine template drift:
- Mitigation: template versioning and replay tests on representative payloads.
Hidden staging logic:
- Mitigation: document slot contracts and release conditions next to Buffer nodes.
Partial fan-in release:
- Mitigation: use blocking slot semantics plus explicit Wait/Decision convergence.

What to monitor in operations

stack size and release cadence
combine render failures by template id
fan-in timeout or late-branch rates
downstream retry spikes after Buffer release (often indicates poor staged payload quality)