# openquiver-graph
The graph IR: nodes, pins, wires. Pure data, no I/O, and — the invariant that
actually matters — no dependency on any other **workspace** crate: nothing
here reaches into the parser, the compiler, the runtime or the editor. That
says nothing about ordinary external crates, and this one has several
(`thiserror`, the `unicode-*` pair for identifier normalization). Two of
them, `serde` and `ts-rs`, are there because something outside this crate
needs the IR's shape in a form it did not have to hand-write. Neither lets
this crate reach outward; both only let other things reach in.
## Why it exists
Everything in OpenQuiver — the parser, the compiler, the runtime, the editor —
works against this one representation. The file on disk is a *projection* of
this IR, never the other way around, which is what makes evolving the storage
format a `load → save` with no data migrations.
## Design decisions worth knowing
**A node's identity is its name.** There are no hidden ids. That is what lets a
readable DSL refer to a node as `ask` rather than `01J8X…`. The price is that
renaming is a refactor that rewrites every reference — the same deal any
programming language makes.
**Wires come in two kinds and the distinction is the product.** `EdgeKind::Exec`
is the white wire that orders steps; `EdgeKind::Data` carries values. Separating
them is what lets a workflow say "first A, then B" without inventing a fake data
dependency, which is the thing dataflow builders cannot express.
**Collections are keyed, never positional.** Nodes live in a `BTreeMap` keyed by
name, edges in a `BTreeSet`. Two reasons, both load-bearing:
- *Canonical order.* Nodes sort alphabetically and edges sort exec-block first,
then data — so a saved file is byte-identical regardless of the order things
were created in, and concurrent insertions by two people land in different
parts of the file instead of colliding at the end.
- *Mergeability.* No positional arrays and no insertion-order ids means the
document can later be backed by a CRDT (Automerge, Loro) for live
co-editing without rewriting the editor. Live sync is not being built now;
keeping the door open costs nothing today and a rewrite later.
`EdgeKind`'s variant order and `Edge`'s field order are both load-bearing —
they are what the derived `Ord` uses to produce the canonical edge order.
## Comments live here too
`Trivia` holds ordinary `//` comments keyed by the element they describe, and it
sits beside the IR rather than in the syntax crate for one reason: the keys are
IR identities, so renaming a node has to update the graph and the comment table
in a single operation. A table one layer above the code performing the rename
cannot be kept in step with it.
`///` is different — it is the node's description and its editor tooltip, so it
is a real IR field (`Node::doc`), not trivia.
## Deliberately not here
Resolved pin *types*. Data types are derived by the compiler through wildcard
propagation, so storing them on an edge would create a second source of truth
that can go stale.
## Why `Value` and `DataType` derive `TS`
`openquiver-editor`'s view — what the canvas draws, and what crosses into the
TypeScript frontend as generated bindings — embeds `Value` and `DataType`
directly: a node's configuration literals and a pin's data type are exactly
this crate's `Value` and `DataType`, not a lookalike. Deriving `ts-rs`'s `TS`
here, beside the type it describes, is what lets the frontend see that shape
at all.
The alternative was a second enum in the editor — `ValueView`, say, hand-kept
in sync with `Value`'s variants — purely so that *something* in that crate
could derive `TS` without reaching back into `openquiver-graph`. That is the same
fact told twice: every time `Value` gained or changed a variant, the mirror
would need the same edit made by hand a second time, in a different file, in
a different crate, and nothing would fail loudly the day someone forgot. The
whole reason this project keeps resolved pin types out of the IR (see above)
is to avoid exactly that shape of bug. Deriving `TS` in place costs one
`#[derive(TS)]` and one external dependency; the mirror would have cost a
permanent, silent way for the frontend's idea of `Value` to drift from the
real one. `ts-rs` crosses the crate boundary the same way `serde` already
does — it does not create a new kind of coupling, only a second consumer of
one that was already there.