GraphReFly gives developers a reactive graph protocol for flows that stay visible as they change. Every node has a role, every edge carries causality, and every wave leaves material that agents can inspect, review, and improve.
shape
Complex work needs a graph.
Modern software is rarely a straight line from request to response. It is data, state, async work, tools, user actions, retries, failures, and sometimes AI, all changing over time.
GraphReFly gives that work an explicit graph shape. Nodes do focused work. Edges declare dependencies. Waves carry change through the topology. Instead of hiding behavior inside callbacks, queues, or opaque orchestration loops, the system has a structure developers can inspect and reason about.
surface
Topology is a first-class surface.
In GraphReFly, the graph is not an implementation detail. Topology is the shared cognitive anchor.
A flow can describe itself as nodes, edges, status, values, metadata, and mount-aware paths. That makes structure available to developers, tools, docs, visualizers, tests, and AI assistants without asking them to reverse-engineer the code path line by line.
waves
Observability starts at the protocol.
Most systems add observability after the fact. GraphReFly starts with observable protocol behavior.
A change moves as a wave. DIRTY travels before DATA. Fan-in waits for changed dependencies to settle. Message egress can be observed. Profiles can count invokes, emits, resolutions, errors, and duration without thickening the node primitive.
audit
Auditability comes from explicit boundaries.
A flow is easier to audit when its boundaries are real.
GraphReFly keeps node responsibilities local, shared state explicit, and graph structure inspectable. If a node depends on state, that dependency is represented in the graph. If a flow crosses a graph boundary, it does so through an explicit bridge rather than a hidden in-process shortcut.
focus
Smaller units protect agent attention.
Large workflows are hard for any agent to hold at once.
GraphReFly lets agents work at different scales. One agent can reason about the whole graph. Another can focus on one node. Another can review a subgraph, an adapter boundary, or a specific wave behavior. These views stay connected without forcing every agent to carry the entire system at once.
agents
Agents need a shared surface.
GraphReFly is not an AI-only library, but agentic work benefits from the same structure developers do.
Agents need something better than an opaque execution log or a giant context window. They need a shared surface where topology, dependencies, state, messages, and changes can be inspected. Human agents and LLM agents do different kinds of work, but they can operate over the same graph.
risk
Probabilistic steps can be bounded.
Some steps are deterministic. Some are probabilistic.
GraphReFly lets probabilistic work live inside limited nodes instead of spreading across the whole flow. Around that step, developers can add verification nodes, fallback nodes, review gates, retry policies, or deterministic checks. The goal is not to make probability vanish. The goal is to keep it local, surround it with verification, and make the larger flow predictable.
cost
Cost becomes attributable.
LLM cost is hard to control when model calls are hidden inside broad workflows.
GraphReFly encourages probabilistic work to be placed in the smallest useful node. Token usage, latency, retries, fallback paths, decisions, outputs, and verification results can be reported as graph-visible facts around the step that caused them. Cost becomes attributable instead of ambient.
result
Predictability comes from legibility.
GraphReFly does not promise that every flow is automatically correct.
It gives developers the substrate for making complex flows legible: explicit topology, synchronous wave semantics, inspectable messages, graph-local state, checkpointable structure, and adapter boundaries that keep async work outside the sync core. When the system has a visible shape, changes have a path, failures have a location, and higher-level guards or verification steps have somewhere concrete to live.
The narrow waist
Developer builds the graph. Agents collaborate through the graph.