graphrefly_graph/lib.rs
1//! `GraphReFly` Graph container — sugar layer over `graphrefly_core::Core`
2//! with named namespace, mount/unmount composition, `describe()` JSON
3//! introspection, and `observe()` sink-style message tap.
4//!
5//! # Status (M2 Slice E+ — 2026-05-05)
6//!
7//! Read-side introspection + composition slice. Lands the canonical-spec
8//! `Graph` surface for `state` / `derived` / `dynamic` named sugar
9//! (§3.9), `add` / `node` / `name_of` / `try_resolve` namespace (§3.5),
10//! `mount` / `mount_new` / `mount_with` / `unmount` / `ancestors`
11//! composition (§3.4), `destroy` / `signal_invalidate` lifecycle (§3.7),
12//! `describe()` JSON form (§3.6 + Appendix B), and `observe()` /
13//! `observe_all()` default sink-style tap (§3.6.2).
14//!
15//! Hard-breaks the M2 starter (Slice D) sugar API: `state(name, initial)`
16//! replaces `state(initial)`, etc. Pre-1.0 — no compat shims (per
17//! `feedback_no_backward_compat.md`).
18//!
19//! Out of scope (subsequent slices):
20//!
21//! - **Reactive `describe()` / `observe()`** — `Node<GraphDescribeOutput>`
22//! and `Node<ObserveChangeset>` modes (§3.6.1 / §3.6.2 reactive
23//! variants). Need a Core-level topology-change notification primitive.
24//! - **Async-iterable `observe()` modes** — `structured` / `timeline` /
25//! `causal` / `derived` opts.
26//! - **`describe()` non-JSON formats** — pretty / mermaid / d2 / stage-log.
27//! - **`describe({ explain })` / `describe({ reachable })`** — causal
28//! chain + reachability walks.
29//! - **Snapshot / restore + content addressing** — V1 lazy CID / V2
30//! schema validation / V3 caps + cross-graph refs (§3.8 + Phase 6).
31//! - **`mutate()` factory** — DS-14 RAII + audit append substrate.
32//! - **Cross-Core (multi-binding) mount** — open question 1 in
33//! `archive/docs/SESSION-rust-port-architecture.md` Part 6; post-M6.
34//! - **Meta annotations + versioning fields** in describe output —
35//! need metadata-storage primitive on Core.
36//!
37//! # Crate lints
38//!
39//! `#![forbid(unsafe_code)]` per workspace policy.
40
41#![forbid(unsafe_code)]
42#![warn(rust_2018_idioms, unreachable_pub)]
43#![warn(clippy::pedantic)]
44#![allow(clippy::module_name_repetitions, clippy::missing_errors_doc)]
45
46mod describe;
47mod graph;
48mod mount;
49mod observe;
50
51pub use describe::{
52 DescribeSink, EdgeDescribe, GraphDescribeOutput, NodeDescribe, NodeStatus, NodeTypeStr,
53 ReactiveDescribeHandle,
54};
55pub use graph::{Graph, NameError, RemoveError, SignalKind};
56pub use mount::{GraphRemoveAudit, MountError};
57pub use observe::{GraphObserveAll, GraphObserveAllReactive, GraphObserveOne};