Skip to main content

Crate graphrefly_graph

Crate graphrefly_graph 

Source
Expand description

GraphReFly Graph container — sugar layer over graphrefly_core::Core with named namespace, mount/unmount composition, describe() JSON introspection, and observe() sink-style message tap.

§Status (M2 Slice E+ — 2026-05-05)

Read-side introspection + composition slice. Lands the canonical-spec Graph surface for state / derived / dynamic named sugar (§3.9), add / node / name_of / try_resolve namespace (§3.5), mount / mount_new / mount_with / unmount / ancestors composition (§3.4), destroy / signal_invalidate lifecycle (§3.7), describe() JSON form (§3.6 + Appendix B), and observe() / observe_all() default sink-style tap (§3.6.2).

Hard-breaks the M2 starter (Slice D) sugar API: state(name, initial) replaces state(initial), etc. Pre-1.0 — no compat shims (per feedback_no_backward_compat.md).

Out of scope (subsequent slices):

  • Reactive describe() / observe() — Node<GraphDescribeOutput> and Node<ObserveChangeset> modes (§3.6.1 / §3.6.2 reactive variants). Need a Core-level topology-change notification primitive.
  • Async-iterable observe() modes — structured / timeline / causal / derived opts.
  • describe() non-JSON formats — pretty / mermaid / d2 / stage-log.
  • describe({ explain }) / describe({ reachable }) — causal chain + reachability walks.
  • Snapshot / restore + content addressing — V1 lazy CID / V2 schema validation / V3 caps + cross-graph refs (§3.8 + Phase 6).
  • mutate() factory — DS-14 RAII + audit append substrate.
  • Cross-Core (multi-binding) mount — open question 1 in archive/docs/SESSION-rust-port-architecture.md Part 6; post-M6.
  • Meta annotations + versioning fields in describe output — need metadata-storage primitive on Core.

§Crate lints

#![forbid(unsafe_code)] per workspace policy.

Structs§

EdgeDescribe
Edge between two named nodes (or a named node and an anonymous dep, surfaced as _anon_<NodeId>).
Graph
Graph container — Phase 1+ public API.
GraphDescribeOutput
Top-level describe() output (canonical Appendix B JSON schema).
GraphObserveAll
All-nodes observe handle. subscribe multiplexes across every named node in the graph (NOT recursive into mounts — observers wanting recursion compose with child.observe_all() per subgraph).
GraphObserveAllReactive
Reactive variant of GraphObserveAll that auto-subscribes late-added named nodes via Graph namespace-change notifications.
GraphObserveOne
Single-node observe handle. subscribe taps downstream messages from the observed node (same payload shape as a direct graphrefly_core::Core::subscribe, including the [Start, Data?] handshake when a cache is present per R1.2.3 / R1.3.5.a).
GraphPersistSnapshot
Portable snapshot of a graph’s state — survives serialization round-trips (JSON, CBOR, etc.).
GraphRemoveAudit
Result of Graph::unmount (and exposed for future Graph::remove parity, canonical spec §3.2.1 GraphRemoveAudit).
NodeDescribe
Per-node descriptor.
NodeSlice
Per-node state within a snapshot.
ReactiveDescribeHandle
RAII handle for a reactive describe subscription. Dropping it stops the namespace listener and frees the describe-sink.

Enums§

DescribeValue
Per-node cache value in describe output. Surfaced as value: <u64> when produced by Graph::describe (raw handle view), or as value: <T> when produced by Graph::describe_with_debug (binding-rendered view). Serialized uniformly without an enum tag — consumers see either a number or whatever JSON shape the binding emits.
MountError
Errors from mount / mount_new / unmount.
NameError
Errors from name registration.
NodeSnapshotStatus
Lifecycle status stored in a snapshot.
NodeStatus
Canonical Appendix B status enum.
NodeTypeStr
Canonical Appendix B type enum.
PathError
Path resolution errors returned by Graph::try_resolve_checked. Slice V3: introduces typed path errors per porting-deferred.md.
RemoveError
Errors from Graph::remove.
SignalKind
Signal kind for Graph::signal (canonical R3.7.1).
SnapshotError
Errors from Graph::restore and Graph::from_snapshot.

Traits§

DebugBindingBoundary
Render handles into JSON-shaped debug values.

Type Aliases§

DescribeSink
Sink type for reactive describe — receives a fresh GraphDescribeOutput on every namespace change.
NodeFactory
Factory function for auto-hydration mode of Graph::from_snapshot. Given a node name, its snapshot slice, and already-resolved dep NodeIds, returns the NodeId of the reconstructed node registered in the provided Graph.
SnapshotBuilder
Builder function for Graph::from_snapshot builder mode.