Decision request: should nem-poweragent-lab's systhread depend on holon-viz as a real (non-dev) dependency?

[elasticdotventures]

Context

nem-poweragent-lab just merged nem-poweragent-lab#43, a design doc for systhread-explorer: a Bevy-native 2D/3D SysML model graph explorer (docs/superpowers/specs/2026-08-26-systhread-3d-explorer-design.md).

Its data model is built by extending, not duplicating, holon-viz's real CytoscapeGraph type. Quoting the design doc's §3, which quotes crates/holon-viz/src/cytoscape.rs directly:

pub struct CytoscapeNodeData { id: String, label: String, kind: String, parent: Option<String>, z_layer: Option<String>, semantic_type: Option<String> }
pub struct CytoscapeNode { data: CytoscapeNodeData }
pub struct CytoscapeEdgeData { id: String, source: String, target: String, label: String }
pub struct CytoscapeEdge { data: CytoscapeEdgeData }
pub struct CytoscapeGraph { nodes: Vec<CytoscapeNode>, edges: Vec<CytoscapeEdge> }

The new PositionedGraph type is designed to wrap this directly rather than reimplement it:

pub struct PositionedGraph {
    pub graph: holon_viz::CytoscapeGraph,   // unmodified, reused directly
    pub layout: Layout,
}

The open question

Today, holon-viz and sysml-derive are only pinned as dev-dependencies in nem-poweragent-lab — a documented workaround (see ledgrrr#202, which is about sysml-derive/FR8-FR9 but shares this same underlying dependency-posture question).

PositionedGraph wrapping CytoscapeGraph by value means systhread-explorer (or systhread-core) would need holon-viz as a real, non-dev dependency — a bigger commitment than the current workaround. This is explicitly flagged as undecided in the design doc itself (§3): "this needs ledgrrr's owner's agreement before v1 implementation starts, not a unilateral decision here."

This isn't decided here either — it's ledgrrr's crate, and ledgrrr's owner who has to live with whichever answer wins. Filing this now, grounded in the real struct shape, rather than letting v1 implementation start on an assumption.

Questions

1. Is a real (non-dev) dependency on holon-viz acceptable, or should this stay at arm's length — e.g. systhread-explorer copies the struct shape it needs rather than depending on holon-viz directly, accepting drift risk if CytoscapeGraph's fields change upstream?
2. If a real dependency is acceptable, does holon-viz's current API stability posture (versioning, how often its public structs change) support being depended on by an external, differently-versioned project — or does it need a stability commitment (e.g. semver discipline on cytoscape.rs's public types) first?

Related

• ledgrrr#202 — related, same underlying question of how permissively nem-poweragent-lab should depend on ledgrrr crates, asked there for sysml-derive/FR8-FR9.
• nem-poweragent-lab#43 — the merged PR/design doc this issue is grounded in.

[elasticdotventures]

Drafting analysis only — not deciding this, per the issue's own framing. Adding facts I verified hands-on tonight while getting the desktop Viz panel actually working end-to-end (see #206) — I was working directly with holon-viz's CytoscapeGraph JSON shape and its consumer the whole time.

Facts I can add

• holon-viz is not published to crates.io — it's workspace-versioned only (version.workspace = true, currently tracking ledgrrr's own 1.10.0). An external, differently-versioned consumer (nem-poweragent-lab) could only depend on it via a git dependency pinned to a specific ledgrrr commit/tag, not a normal semver crates.io dependency. That's a real practical cost regardless of whether the answer to Q1 is yes — it means "real dependency" concretely means "pin to a ledgrrr git rev and re-pin on demand," not "bump a version number."
• holon-viz's own Cargo.toml already carries an explicit note that its ufo-types dependency (needed for SysML-v2 emission, same sysml-v2-parser referenced in Decision needed: how does systhread's FR8/FR9 (ufo-types stereotypes + SysML derive) relate to sysml-derive? #202) is "not wasm32-compatible and holon-viz-wasm must never pull it in" — i.e., holon-viz's public surface is already split by consumer target (native vs. wasm) in a way that isn't formalized via Cargo features, just a doc comment. Anyone depending on it externally should know that split exists and isn't (yet) enforced by the type system.
• I found and fixed two real bugs tonight in the actual consumer of CytoscapeGraph JSON (the desktop app's get_type_graph → frontend Viz panel path — not holon-viz itself, but the same data shape PositionedGraph in the design doc would wrap): a missing JSON.parse() on the Rust→JS boundary, and an unrelated module-scoping bug. Neither is evidence of CytoscapeGraph's own stability one way or the other, but it does mean this exact struct shape (CytoscapeNodeData/CytoscapeEdgeData/CytoscapeGraph) is now confirmed to work correctly end-to-end for the first time, for what it's worth as a sanity check on the shape itself being sound to build on.

On the two actual questions

Q1 (real vs. arm's-length dependency): Not mine to answer, but the crates.io-publication gap above is a fact worth weighting either way — it raises the practical cost of "real dependency" beyond a normal semver bump, independent of whether the coupling itself is desired.

Q2 (stability commitment on cytoscape.rs's public types): I didn't find any semver-discipline convention already documented for holon-viz's public API (no #[non_exhaustive], no changelog section specific to it, no version pin strategy beyond the workspace-wide version). If a stability commitment is wanted, it doesn't exist yet as written policy — that itself would need deciding, not just discovering.

Same underlying tension as #202: this and #202 are really one question ("how permissively should external projects depend on ledgrrr crates") asked twice from two different entry points. Might be worth resolving as one decision rather than two.

🤖 Drafted during an overnight session with Claude Code, per your explicit request to draft analysis without deciding.