GraphReFly

GRAPH+RE[ACTIVE]=FLY

Reactive graph protocol for observable systems.

GraphReFly turns complex flows into inspectable, auditable causal graphs, so humans, tools, and AI can build on smaller verified steps.

Choose a package Why it matters
GraphReFly · Reactive Graph Protocol
Core GraphReFly concept: graph waves moving through a declared topology Seven scenes show subscription lifecycle, dirty and data waves, node anatomy, graph roles, graph-level views, orchestration, and an agent loop. upstream downstream fn(…) START DIRTY DATA DIRTY DATA COMPLETE A B · slow fn C · fast fn D · joins B + C fn(…) DIRTY DIRTY DIRTY DIRTY DATA DATA DATA DATA fn(…) cache guard version UP [deps] DOWN [subs] state producer derived effect state producer derived fn(…) effect describe — the topology observe — the data flow batch — many waves, resolve once subgraphs — isolated causal field gate action check action pipeline hub ▌ ▌ static graph · dynamic data agent tool result judge memory ? ? ?
stage 1 · connection lifecycle stage 2 · diamond resolution stage 3 · node anatomy stage 4 · node roles stage 5 · graph level stage 6 · orchestrate · messaging stage 7 · agent loop · memory
START → DIRTY
→ DATA → COMPLETE DIRTY converges
DATA fires once fn · cache
status · deps state · producer
derived · effect describe · observe
batch pipeline + hub
static · dynamic loop · memory
open substrate
describe observe batch

Connection lifecycle. A subscription opens with START, DIRTY marks the downstream node before DATA invokes fn(...), and COMPLETE closes the edge.

Diamond resolution. DIRTY reaches both branches and the join before DATA; the join waits for both branch values and fires once.

Node anatomy. A node carries a fn, cache, status, deps, and up/down message surface as one focused primitive.

Node roles. State and producer feed derived work; derived nodes push visible effects through the same wave protocol.

Graph level. The graph can be described, observed, and batched so topology, data flow, and wave boundaries stay inspectable.

Orchestration. Static topology carries dynamic data through pipelines, hubs, cursors, and consumers.

Agent loop. Agent, tool, result, review, memory, and open extension points can stay inside one inspectable graph.

Wave-based propagation

Diamond patterns resolve as one wave.

A source update marks the reachable diamond dirty first. DATA then moves through each branch at its own pace, and the join emits only after both branch values arrive.

1DIRTY fan-outThe downstream diamond is marked before values move.
2DATA splitSource DATA reaches A and B together.
3Join waitB finishes first; the join holds it until A emits.
4Joined outputThe join emits once both branch values are present.
DIRTY DATA
DIRTY travels before DATA through a diamond graph; the join emits after both branch values arrive SOURCE A B JOIN EFFECT

Runtime guarantees

Protocol guarantees developers can build on.

GraphReFly makes changing systems legible: declared topology, wave-based propagation, glitch-free joins, and read-only inspection surfaces.

#GuaranteeUser benefitPublic terms
01Declared topology

Every source, reduction, join, and effect has a place in the graph, so developers can inspect what depends on what.

node · graph · edge 02Wave-based propagation

One message array is one wave. DIRTY travels before DATA, so downstream nodes observe change before values settle.

DIRTY -> DATA 03Glitch-free joins

Fan-out can rejoin without half-old mixes; a join recomputes once after changed dependencies settle.

fan-out · fan-in 04Read-only inspection

describe, observe, and profile expose structure, message egress, and runtime counters without hidden mutation.

describe · observe · profile

Why observable graphs matter

Complex flows need a visible shape.

Callbacks, queues, scripts, provider logs, and agent transcripts all hide causality in different places. GraphReFly gives the work one inspectable topology.

Flow
Hidden flow

Complex work disappears into callbacks, queues, scripts, and provider logs. The runtime knows what happened, but the system cannot show its shape.

Explicit topology

GraphReFly gives the work a shape: nodes, edges, waves, status, and graph-local state that can be inspected before and after execution.

Cause
Unclear causality

A value changed, an effect fired, or a branch rejoined, but the reason is scattered across runtime behavior and disconnected logs.

Inspectable propagation

GraphReFly exposes how change moves through the graph: dirty state, settled values, completion, errors, and downstream effects.

Scope
Too much shared context

Large workflows force every collaborator to understand everything at once. Small changes become risky because the boundaries are unclear.

Smaller verified steps

Graph boundaries let agents focus on the whole graph, a subgraph, or a single node without losing the causal picture.

Agentic and LLM-backed work

Probabilistic steps need bounded graph structure.

GraphReFly is not AI-only, but agentic systems benefit from its shape: model-backed steps can stay local while verification, fallback, review, and cost signals live around them.

Bounded steps

Keep probabilistic work inside limited nodes.

A model call, classifier, planner, or generator can be represented as one bounded step with explicit inputs, outputs, status, and downstream effects.

Package routes

One shared mental model. Language-local APIs.

Install a package, then open the language-owned docs for API details and examples.

TypeScript@graphrefly/tsnpm install @graphrefly/tsEnter TypeScript docs Pythongraphreflypip install graphreflyEnter Python docs Rustgraphrefly-rscargo add graphrefly-rsEnter Rust docs