Crate graphrefly_graph 

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 _anon_<NodeId>).

Graph

Graph container — the one Core-free namespace + mount-tree handle (canonical §3, D246).

GraphDescribeOutput

Top-level describe() output (canonical Appendix B JSON schema).

GraphInner

Inner namespace + mount-tree state for one graph level. D246: holds no Core — purely the named namespace, the mounted children, and the namespace-change sinks. D246/S2c/D247: single-owner ⇒ Rc<RefCell<GraphInner>> (the prior Arc<Mutex<…>> was shared-Core-era legacy); the shareable-handle + parent-Weak cycle stays, single-threaded.

GraphObserveAll

All-nodes observe handle. Subscriptions are tied to the set of nodes named at subscribe() call time. D246: no RAII Drop — You MUST call Self::detach(core) (owner-invoked) — these Core subscriptions are opened via raw core.subscribe and are NOT OwnedCore-tracked, so dropping the handle without detach leaks them for the Core lifetime.

GraphObserveAllReactive

Reactive observe_all — auto-subscribes late-added named nodes via the owner-side namespace-change listener, and prunes torn-down nodes via the Core topology sub (the prune unsubscribe is MailboxOp::Defer’d since NodeTornDown fires in-wave — D246 r6). D246 rule 3: no RAII Drop; teardown is the owner-invoked Self::detach(core) — owner-invoked, REQUIRED. The ns-sink is collected by graph.destroy(core); the Core topology sub + fan-out subs are opened via raw core.subscribe* and are NOT OwnedCore-tracked, so detach(core) is the only thing that collects them (dropping the handle without it leaks them).

GraphObserveOne

Single-node observe handle (canonical §3.6.2). D246: holds a Core-free Graph; &Core is passed per call.

GraphPersistSnapshot

Portable snapshot of a graph’s state.

GraphRemoveAudit

Result of Graph::unmount / Graph::remove.

NodeDescribe

Per-node descriptor.

NodeSlice

Per-node state within a snapshot.

ObserveSub

Id pair for a single observe subscription. D246: a plain value (no Drop); detach explicitly via Self::detach or let the embedder’s OwnedCore tear down on owner-thread drop.

ReactiveDescribeHandle

Id-bearing handle for a reactive describe subscription.

Enums

DescribeValue

Per-node cache value in describe output. Serialized uniformly without an enum tag.

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.

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.

NodeFactory

Factory for auto-hydration mode. D246: receives the embedder’s &Core + the Core-free Graph handle.

SnapshotBuilder

Builder function for Graph::from_snapshot builder mode (D246: &Core + Core-free Graph).