Guarantees

What your team can rely on.

A plain-language view of the promises behind GraphReFly: visible relationships, coherent updates, honest missing data, and clear boundaries for outside work.

Topology Stays Explainable

A GraphReFly program should be understandable as named inputs, derived reductions, and boundary effects, not only as line-by-line control flow.

What it means

The graph shape is part of the public mental model. Developers should be able to inspect the declared nodes and edges that explain why an output changed.

  • Use the shared site for the cross-language graph shape.
  • Use package docs for exact factories and generated API reference.
  • Avoid hidden side channels that make work happen outside the declared topology.

When it helps

Start by drawing the facts that can change, then place reductions and effects around those facts. When a composition grows, inspectability should improve the explanation instead of becoming an afterthought.

Explore next

Tiny Graph

Async Stays at Boundaries

External work can be asynchronous, but graph mutation re-enters through declared source, pool, or bridge boundaries.

What it means

Inside a graph, updates serialize through the graph's ordered update domain. File IO, network work, workers, remote graphs, and host callbacks belong at package-owned boundaries that re-enter with explicit graph facts.

  • Do async work in sources, pools, adapters, or bridges.
  • Keep ordinary reductions deterministic and inspectable.
  • Do not hide timers or callbacks inside the reactive core.

When it helps

When you connect an external system, pick the package helper for that environment and let it publish explicit facts into the graph. The shared docs describe the boundary discipline; package docs own the runnable integration details.

Explore next

Packages

One Graph, One Ordered Update Domain

Within one graph, related updates settle in a single ordered domain so downstream reducers see a coherent input set.

What it means

A graph is the unit that keeps related propagation ordered. Parallel compute and remote graphs can exist, but their results return through explicit boundaries before they affect this graph.

  • Use one graph for one tightly related update domain.
  • Use pools for compute that must leave the immediate path.
  • Use bridges when separate graphs or runtimes need delayed consistency.

When it helps

If two outputs must settle together, keep their shared cause inside one graph unless there is a real boundary. If there is a boundary, model it explicitly rather than pretending it is an in-process edge.

Explore next

Concepts

Missing Input Is Not a Fake Value

GraphReFly keeps the difference between no value yet and a real domain value such as null, zero, or an empty collection.

What it means

A node should not compute from invented placeholder state. Missing input remains missing until a dependency produces real data, while domain-level empty values remain valid data when your domain allows them.

  • Do not bootstrap joins with fake objects or magic strings.
  • Let first execution wait for real inputs by default.
  • Use package helpers when you intentionally want partial-input behavior.

When it helps

This guarantee keeps forms, loaders, retained views, and multi-input reductions honest. If a value is unknown, model that lifecycle directly instead of smuggling it through as ordinary data.

Explore next

No Placeholder State

Joins Settle Predictably

When one cause fans out and rejoins, the downstream reducer should see the settled result once, not a half-old mix.

What it means

GraphReFly coordinates fan-out and fan-in so a join waits for the changed inputs in the same update to settle before recomputing. That gives developers a stable way to reason about validation summaries, derived views, and other many-input reducers.

  • Declare every branch output the join depends on.
  • Let the graph coordinate the update order.
  • Do not manually trigger the join from each branch.

When it helps

Model joins as reductions over declared dependencies. For a deeper walkthrough, use the composition guide; this page records the public guarantee.

Explore next

Glitch-Free Joins

Languages Match by Behavior

TypeScript, Python, and Rust do not need identical symbol lists to give developers the same core behavior where the protocol matters.

What it means

Cross-language consistency is checked through shared behavior scenarios. Language packages may expose idiomatic helpers, but the important question is whether the same graph situation settles the same way.

  • Expect package APIs to feel native to their language.
  • Expect core behavior to be checked by shared scenarios.
  • Do not use the shared site as a generated API comparison table.

When it helps

Choose the package for your runtime, then rely on the shared guarantees for the common behavior. When you need exact syntax, follow that package's docs.

Explore next

Packages