diff --git a/Cargo.lock b/Cargo.lock index 6b404d3..6188692 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2,6 +2,111 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "norn-eve-plugin" +version = "0.1.0" +dependencies = [ + "norn-rs", + "serde", + "serde_json", +] + [[package]] name = "norn-rs" version = "0.1.0" + +[[package]] +name = "proc-macro2" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "serde" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.150" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "syn" +version = "2.0.118" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "zmij" +version = "1.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" diff --git a/Cargo.toml b/Cargo.toml index 13710f5..c105fa4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,3 +1,3 @@ [workspace] -members = ["crates/norn-rs"] +members = ["crates/norn-rs", "crates/norn-eve-plugin"] resolver = "3" diff --git a/README.md b/README.md index d0febeb..c08d3cd 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,22 @@ tools for note exports, SDK/bridge work, and legacy inspection. They are windows onto the solver, not competing engines. Do not make consumers choose between truths like this repo is a sad little trade show booth. +## Eve Plugin Sidecar + +`crates/norn-eve-plugin` is Norn's runtime-independent Eve plugin boundary. It +accepts one `gamecult.eve.plugin_abi.request.v1` JSON document per UTF-8 stdin +line and emits one response line in request order. The sidecar owns graph +validation, semantic projection, and solver-backed measurement. It does not +own provider state or renderer projection. + +Owner-published discovery and conformance documents live under `plugins/` and +the graph document/layout schemas live under `schemas/`. + +```powershell +Get-Content .\crates\norn-eve-plugin\tests\fixtures\sai-nested-norn.ndjson | + cargo run -q -p norn-eve-plugin +``` + ## Rust Solver ```powershell diff --git a/crates/norn-eve-plugin/Cargo.toml b/crates/norn-eve-plugin/Cargo.toml new file mode 100644 index 0000000..ba705bf --- /dev/null +++ b/crates/norn-eve-plugin/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "norn-eve-plugin" +version = "0.1.0" +edition = "2024" +description = "Norn graph capability sidecar for the Eve plugin ABI." +license = "MIT OR Apache-2.0" +repository = "https://github.com/GameCult/Norn" + +[dependencies] +norn-rs = { path = "../norn-rs" } +serde = { version = "1", features = ["derive"] } +serde_json = "1" + diff --git a/crates/norn-eve-plugin/src/lib.rs b/crates/norn-eve-plugin/src/lib.rs new file mode 100644 index 0000000..ced621f --- /dev/null +++ b/crates/norn-eve-plugin/src/lib.rs @@ -0,0 +1,418 @@ +use std::collections::{HashMap, HashSet}; + +use norn_rs::{Graph, LayoutConfig, layout}; +use serde::{Deserialize, Serialize}; +use serde_json::{Value, json}; + +pub const PLUGIN_ID: &str = "norn.graph"; +pub const REQUEST_SCHEMA: &str = "gamecult.eve.plugin_abi.request.v1"; +pub const RESPONSE_SCHEMA: &str = "gamecult.eve.plugin_abi.response.v1"; +const MAX_NODES: usize = 10_000; +const MAX_EDGES: usize = 50_000; +const MAX_ITERATIONS: usize = 10_000; + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct PluginRequest { + pub schema: String, + pub plugin_id: String, + pub operation: String, + pub request_id: String, + #[serde(default)] + pub input: Value, +} + +#[derive(Debug, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct PluginResponse { + pub schema: &'static str, + pub plugin_id: &'static str, + pub operation: String, + pub request_id: String, + pub status: &'static str, + pub output: Value, + #[serde(skip_serializing_if = "Vec::is_empty")] + pub diagnostics: Vec, +} + +#[derive(Debug, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct Diagnostic { + pub code: &'static str, + pub message: String, +} + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct GraphInput { + #[serde(default)] + nodes: Vec, + #[serde(default)] + edges: Vec, + #[serde(default)] + layout: LayoutInput, +} + +#[derive(Debug, Deserialize)] +struct GraphNodeInput { + id: String, + #[serde(default = "default_weight")] + weight: f32, + #[serde(default = "default_width")] + width: f32, + #[serde(default = "default_height")] + height: f32, +} + +#[derive(Debug, Deserialize, Serialize)] +struct GraphEdgeInput { + source: String, + target: String, +} + +#[derive(Debug, Default, Deserialize)] +#[serde(rename_all = "camelCase")] +struct LayoutInput { + iterations: Option, + rank_gap: Option, + node_gap: Option, + edge_length: Option, +} + +pub fn dispatch(request: PluginRequest) -> PluginResponse { + if request.schema != REQUEST_SCHEMA { + return rejected(&request, "schema", format!("expected {REQUEST_SCHEMA}")); + } + if request.plugin_id != PLUGIN_ID { + return rejected(&request, "plugin-id", format!("expected {PLUGIN_ID}")); + } + + match request.operation.as_str() { + "describe" => accepted(&request, describe()), + "validate" => accepted(&request, validate(&request.input)), + "project" => project(&request), + "measure" => measure(&request), + _ => rejected( + &request, + "unsupported-operation", + format!("Norn does not implement operation {}", request.operation), + ), + } +} + +fn describe() -> Value { + json!({ + "pluginId": PLUGIN_ID, + "ownerRepo": "Norn", + "componentKinds": ["embed.norn"], + "commands": ["graph.node.activate", "graph.focus"], + "capabilities": ["embed.norn", "graph.node.activate"], + "operations": ["describe", "validate", "project", "measure"], + "transports": ["stdio-ndjson"], + "stateAuthority": "proposes-plugin-state-only-provider-accepts" + }) +} + +fn validate(input: &Value) -> Value { + let kinds = input + .get("componentKinds") + .and_then(Value::as_array) + .cloned() + .unwrap_or_default(); + let (accepted_kinds, rejected_kinds): (Vec<_>, Vec<_>) = kinds + .into_iter() + .filter_map(|value| value.as_str().map(str::to_owned)) + .partition(|kind| kind == "embed.norn"); + + json!({ + "acceptedComponentKinds": accepted_kinds, + "rejectedComponentKinds": rejected_kinds, + "requiredCapabilities": ["embed.norn"], + "valid": rejected_kinds.is_empty() + }) +} + +fn project(request: &PluginRequest) -> PluginResponse { + let kind = request + .input + .get("component") + .and_then(|component| component.get("kind")) + .and_then(Value::as_str) + .or_else(|| request.input.get("nodeKind").and_then(Value::as_str)); + if kind != Some("embed.norn") { + return rejected( + request, + "component-kind", + "project requires embed.norn".into(), + ); + } + + accepted( + request, + json!({ + "projectionKind": "embedded-semantic-surface", + "ownedComponentKinds": ["embed.norn"], + "outputSchemas": [ + "norn.graph.document.v1", + "norn.graph.layout_request.v1", + "norn.graph.layout_result.v1" + ], + "semanticOwner": "Norn", + "graph": request.input.get("graph").cloned().unwrap_or_else(|| json!({})) + }), + ) +} + +fn measure(request: &PluginRequest) -> PluginResponse { + let graph_value = request.input.get("graph").unwrap_or(&request.input); + let input: GraphInput = match serde_json::from_value(graph_value.clone()) { + Ok(input) => input, + Err(error) => return rejected(request, "graph-input", error.to_string()), + }; + let prepared = match prepare_graph(&input) { + Ok(prepared) => prepared, + Err(message) => return rejected(request, "graph-input", message), + }; + let result = layout(&prepared.graph, &prepared.config); + let nodes_by_index = input.nodes.iter().collect::>(); + let node_bounds = result + .nodes + .iter() + .map(|node| { + let source = nodes_by_index[node.id.0]; + json!({ + "id": source.id, + "x": node.x - source.width / 2.0, + "y": node.y - source.height / 2.0, + "width": source.width, + "height": source.height, + "rank": node.rank, + "order": node.order + }) + }) + .collect::>(); + let positions = result + .nodes + .iter() + .map(|node| (node.id.0, (node.x, node.y))) + .collect::>(); + let edge_routes = input + .edges + .iter() + .map(|edge| { + let source = prepared.ids[&edge.source]; + let target = prepared.ids[&edge.target]; + let (sx, sy) = positions[&source]; + let (tx, ty) = positions[&target]; + json!({"source": edge.source, "target": edge.target, "points": [[sx, sy], [tx, ty]]}) + }) + .collect::>(); + let viewport = viewport_bounds(&result.nodes, &input.nodes); + + accepted( + request, + json!({ + "measurementKind": "graph-layout-metrics", + "layoutSchema": "norn.graph.layout_result.v1", + "nodeBounds": node_bounds, + "edgeRoutes": edge_routes, + "viewportBounds": viewport, + "preservesProviderAuthority": true + }), + ) +} + +struct PreparedGraph { + graph: Graph, + ids: HashMap, + config: LayoutConfig, +} + +fn prepare_graph(input: &GraphInput) -> Result { + if input.nodes.is_empty() { + return Err("graph must contain at least one node".into()); + } + if input.nodes.len() > MAX_NODES { + return Err(format!("graph exceeds the {MAX_NODES} node limit")); + } + if input.edges.len() > MAX_EDGES { + return Err(format!("graph exceeds the {MAX_EDGES} edge limit")); + } + let mut graph = Graph::with_capacity(input.nodes.len(), input.edges.len()); + let mut ids = HashMap::new(); + for node in &input.nodes { + if node.id.trim().is_empty() || ids.contains_key(&node.id) { + return Err(format!( + "node ids must be non-empty and unique: {}", + node.id + )); + } + if !node.weight.is_finite() || !node.width.is_finite() || !node.height.is_finite() { + return Err(format!( + "node {} contains a non-finite measurement", + node.id + )); + } + if node.width <= 0.0 || node.height <= 0.0 { + return Err(format!("node {} dimensions must be positive", node.id)); + } + ids.insert(node.id.clone(), graph.add_node(node.weight).0); + } + let mut unique_edges = HashSet::new(); + for edge in &input.edges { + let source = ids + .get(&edge.source) + .ok_or_else(|| format!("unknown edge source: {}", edge.source))?; + let target = ids + .get(&edge.target) + .ok_or_else(|| format!("unknown edge target: {}", edge.target))?; + if unique_edges.insert((*source, *target)) { + graph.add_edge(norn_rs::NodeId(*source), norn_rs::NodeId(*target)); + } + } + let mut config = LayoutConfig::default(); + if let Some(value) = input.layout.iterations { + if value == 0 || value > MAX_ITERATIONS { + return Err(format!( + "layout iterations must be between 1 and {MAX_ITERATIONS}" + )); + } + config.iterations = value; + } + if let Some(value) = input.layout.rank_gap { + validate_positive_layout_value("rankGap", value)?; + config.rank_gap = value; + } + if let Some(value) = input.layout.node_gap { + validate_positive_layout_value("nodeGap", value)?; + config.node_gap = value; + } + if let Some(value) = input.layout.edge_length { + validate_positive_layout_value("edgeLength", value)?; + config.edge_length = value; + } + Ok(PreparedGraph { graph, ids, config }) +} + +fn validate_positive_layout_value(name: &str, value: f32) -> Result<(), String> { + if value.is_finite() && value > 0.0 { + Ok(()) + } else { + Err(format!("layout {name} must be finite and positive")) + } +} + +fn viewport_bounds(layout: &[norn_rs::NodeLayout], nodes: &[GraphNodeInput]) -> Value { + let mut min_x = f32::INFINITY; + let mut min_y = f32::INFINITY; + let mut max_x = f32::NEG_INFINITY; + let mut max_y = f32::NEG_INFINITY; + for node in layout { + let source = &nodes[node.id.0]; + min_x = min_x.min(node.x - source.width / 2.0); + min_y = min_y.min(node.y - source.height / 2.0); + max_x = max_x.max(node.x + source.width / 2.0); + max_y = max_y.max(node.y + source.height / 2.0); + } + json!({"x": min_x, "y": min_y, "width": max_x - min_x, "height": max_y - min_y}) +} + +fn accepted(request: &PluginRequest, output: Value) -> PluginResponse { + PluginResponse { + schema: RESPONSE_SCHEMA, + plugin_id: PLUGIN_ID, + operation: request.operation.clone(), + request_id: request.request_id.clone(), + status: "accepted", + output, + diagnostics: Vec::new(), + } +} + +fn rejected(request: &PluginRequest, code: &'static str, message: String) -> PluginResponse { + PluginResponse { + schema: RESPONSE_SCHEMA, + plugin_id: PLUGIN_ID, + operation: request.operation.clone(), + request_id: request.request_id.clone(), + status: "rejected", + output: json!({}), + diagnostics: vec![Diagnostic { code, message }], + } +} + +fn default_weight() -> f32 { + 1.0 +} +fn default_width() -> f32 { + 120.0 +} +fn default_height() -> f32 { + 56.0 +} + +#[cfg(test)] +mod tests { + use super::*; + + fn request(operation: &str, input: Value) -> PluginRequest { + PluginRequest { + schema: REQUEST_SCHEMA.into(), + plugin_id: PLUGIN_ID.into(), + operation: operation.into(), + request_id: format!("test-{operation}"), + input, + } + } + + #[test] + fn describes_norn_owned_capabilities() { + let response = dispatch(request("describe", json!({}))); + assert_eq!(response.status, "accepted"); + assert_eq!(response.output["ownerRepo"], "Norn"); + } + + #[test] + fn measures_graph_with_solver_owned_coordinates() { + let response = dispatch(request( + "measure", + json!({"graph": { + "nodes": [{"id":"a"},{"id":"b"},{"id":"c"}], + "edges": [{"source":"a","target":"b"},{"source":"b","target":"c"}], + "layout": {"iterations": 20} + }}), + )); + assert_eq!(response.status, "accepted"); + assert_eq!(response.output["nodeBounds"].as_array().unwrap().len(), 3); + assert_eq!(response.output["edgeRoutes"].as_array().unwrap().len(), 2); + assert_eq!(response.output["preservesProviderAuthority"], true); + } + + #[test] + fn rejects_edges_that_reference_unknown_nodes() { + let response = dispatch(request( + "measure", + json!({"graph": { + "nodes": [{"id":"a"}], "edges": [{"source":"a","target":"missing"}] + }}), + )); + assert_eq!(response.status, "rejected"); + assert!( + response.diagnostics[0] + .message + .contains("unknown edge target") + ); + } + + #[test] + fn rejects_unbounded_solver_work() { + let response = dispatch(request( + "measure", + json!({"graph": { + "nodes": [{"id":"a"}], "layout": {"iterations": MAX_ITERATIONS + 1} + }}), + )); + assert_eq!(response.status, "rejected"); + assert!(response.diagnostics[0].message.contains("iterations")); + } +} diff --git a/crates/norn-eve-plugin/src/main.rs b/crates/norn-eve-plugin/src/main.rs new file mode 100644 index 0000000..cc9b178 --- /dev/null +++ b/crates/norn-eve-plugin/src/main.rs @@ -0,0 +1,38 @@ +use std::io::{self, BufRead, Write}; + +use norn_eve_plugin::{PLUGIN_ID, PluginRequest, PluginResponse, RESPONSE_SCHEMA, dispatch}; +use serde_json::json; + +fn main() -> io::Result<()> { + let stdin = io::stdin(); + let mut stdout = io::stdout().lock(); + for line in stdin.lock().lines() { + let line = line?; + if line.trim().is_empty() { + continue; + } + let response = match serde_json::from_str::(&line) { + Ok(request) => dispatch(request), + Err(error) => malformed_response(error.to_string()), + }; + serde_json::to_writer(&mut stdout, &response)?; + stdout.write_all(b"\n")?; + stdout.flush()?; + } + Ok(()) +} + +fn malformed_response(message: String) -> PluginResponse { + PluginResponse { + schema: RESPONSE_SCHEMA, + plugin_id: PLUGIN_ID, + operation: "invalid".into(), + request_id: "invalid-request".into(), + status: "rejected", + output: json!({}), + diagnostics: vec![norn_eve_plugin::Diagnostic { + code: "malformed-request", + message, + }], + } +} diff --git a/crates/norn-eve-plugin/tests/fixtures/sai-nested-norn.ndjson b/crates/norn-eve-plugin/tests/fixtures/sai-nested-norn.ndjson new file mode 100644 index 0000000..257c83f --- /dev/null +++ b/crates/norn-eve-plugin/tests/fixtures/sai-nested-norn.ndjson @@ -0,0 +1,3 @@ +{"schema":"gamecult.eve.plugin_abi.request.v1","pluginId":"norn.graph","operation":"project","requestId":"sai-nested-project","input":{"component":{"kind":"embed.norn","props":{"documentId":"sai.whiteboard.graph"}},"graph":{"schema":"norn.graph.document.v1","nodes":[{"id":"arrival"},{"id":"choice"},{"id":"aftermath"}],"edges":[{"source":"arrival","target":"choice"},{"source":"choice","target":"aftermath"}]}}} +{"schema":"gamecult.eve.plugin_abi.request.v1","pluginId":"norn.graph","operation":"measure","requestId":"sai-nested-measure","input":{"graph":{"schema":"norn.graph.document.v1","nodes":[{"id":"arrival"},{"id":"choice"},{"id":"aftermath"}],"edges":[{"source":"arrival","target":"choice"},{"source":"choice","target":"aftermath"}],"layout":{"iterations":40}}}} + diff --git a/crates/norn-rs/src/lib.rs b/crates/norn-rs/src/lib.rs index ba17577..49e1749 100644 --- a/crates/norn-rs/src/lib.rs +++ b/crates/norn-rs/src/lib.rs @@ -2813,6 +2813,11 @@ pub extern "C" fn norn_graph_alloc(len: usize) -> *mut u8 { } /// Release a pointer previously returned by [`norn_graph_alloc`]. +/// +/// # Safety +/// +/// `ptr` must have been returned by [`norn_graph_alloc`] with the same `len` +/// and must not have been released previously. #[unsafe(no_mangle)] pub unsafe extern "C" fn norn_graph_dealloc(ptr: *mut u8, len: usize) { if ptr.is_null() || len == 0 { @@ -2834,6 +2839,11 @@ pub extern "C" fn norn_graph_alloc_f32(count: usize) -> *mut f32 { } /// Release `f32` slots previously returned by [`norn_graph_alloc_f32`]. +/// +/// # Safety +/// +/// `ptr` must have been returned by [`norn_graph_alloc_f32`] with the same +/// `count` and must not have been released previously. #[unsafe(no_mangle)] pub unsafe extern "C" fn norn_graph_dealloc_f32(ptr: *mut f32, count: usize) { if ptr.is_null() || count == 0 { @@ -2855,6 +2865,11 @@ pub extern "C" fn norn_graph_alloc_u32(count: usize) -> *mut u32 { } /// Release `u32` slots previously returned by [`norn_graph_alloc_u32`]. +/// +/// # Safety +/// +/// `ptr` must have been returned by [`norn_graph_alloc_u32`] with the same +/// `count` and must not have been released previously. #[unsafe(no_mangle)] pub unsafe extern "C" fn norn_graph_dealloc_u32(ptr: *mut u32, count: usize) { if ptr.is_null() || count == 0 { @@ -2875,6 +2890,12 @@ pub unsafe extern "C" fn norn_graph_dealloc_u32(ptr: *mut u32, count: usize) { /// /// Output tuple per node is `(x, y, rank, order)` sorted by node index. /// Returns `0` on success and a negative value for malformed input. +/// +/// # Safety +/// +/// Input pointers must address the documented number of readable elements and +/// `output_ptr` must address `node_count * 4` writable `f32` slots. The pointed +/// memory must remain valid and non-overlapping for the duration of the call. #[unsafe(no_mangle)] pub unsafe extern "C" fn norn_graph_layout_2d( node_weights_ptr: *const f32, @@ -2917,11 +2938,13 @@ pub unsafe extern "C" fn norn_graph_layout_2d( graph.add_edge(NodeId(source), NodeId(target)); } - let mut config = LayoutConfig::default(); - config.iterations = iterations.max(1); - config.rank_gap = rank_gap.max(1.0); - config.node_gap = node_gap.max(1.0); - config.edge_length = edge_length.max(1.0); + let config = LayoutConfig { + iterations: iterations.max(1), + rank_gap: rank_gap.max(1.0), + node_gap: node_gap.max(1.0), + edge_length: edge_length.max(1.0), + ..LayoutConfig::default() + }; let result = layout(&graph, &config); for node in result.nodes { diff --git a/plugins/norn-graph.plugin-abi-fixture.json b/plugins/norn-graph.plugin-abi-fixture.json new file mode 100644 index 0000000..373b7b1 --- /dev/null +++ b/plugins/norn-graph.plugin-abi-fixture.json @@ -0,0 +1,66 @@ +{ + "schema": "gamecult.eve.plugin_abi_fixture.v1", + "fixtureId": "norn-graph-owner-sidecar", + "pluginId": "norn.graph", + "ownerRepo": "Norn", + "contract": "gamecult.eve.plugin_abi.v1", + "requestSchema": "gamecult.eve.plugin_abi.request.v1", + "responseSchema": "gamecult.eve.plugin_abi.response.v1", + "sourceFixture": "sai-nested-norn", + "sourceFixtureRole": "optional-nested-placement-evidence", + "authority": "Norn owns graph semantics; the Sai-derived component proves only nested composition.", + "operations": [ + { + "operation": "describe", + "input": {}, + "expect": { + "pluginId": "norn.graph", + "componentKinds": ["embed.norn"], + "commands": ["graph.node.activate", "graph.focus"], + "capabilities": ["embed.norn", "graph.node.activate"] + } + }, + { + "operation": "validate", + "input": { "componentKinds": ["embed.norn", "embed.tex", "vn.stage"] }, + "expect": { + "acceptedComponentKinds": ["embed.norn"], + "rejectedComponentKinds": ["embed.tex", "vn.stage"], + "requiredCapabilities": ["embed.norn"] + } + }, + { + "operation": "project", + "input": { + "component": { "kind": "embed.norn", "props": { "documentId": "sai.whiteboard.graph" } }, + "graph": { + "schema": "norn.graph.document.v1", + "nodes": [{ "id": "arrival" }, { "id": "choice" }, { "id": "aftermath" }], + "edges": [{ "source": "arrival", "target": "choice" }, { "source": "choice", "target": "aftermath" }] + } + }, + "expect": { + "projectionKind": "embedded-semantic-surface", + "ownedComponentKinds": ["embed.norn"], + "semanticOwner": "Norn" + } + }, + { + "operation": "measure", + "input": { + "graph": { + "schema": "norn.graph.document.v1", + "nodes": [{ "id": "arrival" }, { "id": "choice" }, { "id": "aftermath" }], + "edges": [{ "source": "arrival", "target": "choice" }, { "source": "choice", "target": "aftermath" }], + "layout": { "iterations": 40 } + } + }, + "expect": { + "measurementKind": "graph-layout-metrics", + "measurementOutputs": ["nodeBounds", "edgeRoutes", "viewportBounds"], + "preservesProviderAuthority": true + } + } + ] +} + diff --git a/plugins/norn-graph.plugin-advertisement.json b/plugins/norn-graph.plugin-advertisement.json new file mode 100644 index 0000000..28f3aa6 --- /dev/null +++ b/plugins/norn-graph.plugin-advertisement.json @@ -0,0 +1,36 @@ +{ + "schema": "gamecult.eve.plugin_advertisement.v1", + "pluginId": "norn.graph", + "ownerService": "norn", + "version": "0.1.0", + "manifestAddress": "file://plugins/norn-graph.plugin.json", + "runtime": { + "invocationModel": "executable-sidecar", + "contract": "gamecult.eve.plugin_abi.v1", + "transports": ["stdio"], + "authority": ["renderer-independent", "no-provider-state-mutation", "provider-accepts-or-denies-commands"], + "sidecar": { + "processKind": "long-running-daemon", + "protocol": "stdio-ndjson", + "requestSchema": "gamecult.eve.plugin_abi.request.v1", + "responseSchema": "gamecult.eve.plugin_abi.response.v1", + "operations": ["describe", "validate", "project", "measure"], + "commandEnvelope": "gamecult.eve.command.v1", + "receiptSchema": "gamecult.eve.command_receipt.v1", + "stateAuthority": "proposes-plugin-state-only-provider-accepts", + "launch": { "artifact": "cargo:norn-eve-plugin", "command": "norn-eve-plugin" }, + "stdio": { + "encoding": "utf-8", + "framing": "ndjson", + "ordering": "sequential", + "blankLines": "ignored", + "diagnostics": "stderr" + } + } + }, + "schemas": ["norn.graph.document.v1", "norn.graph.layout_request.v1", "norn.graph.layout_result.v1"], + "componentKinds": ["embed.norn"], + "commands": ["graph.node.activate", "graph.focus"], + "fixtures": ["sai-nested-norn"] +} + diff --git a/plugins/norn-graph.plugin.json b/plugins/norn-graph.plugin.json new file mode 100644 index 0000000..5ae826c --- /dev/null +++ b/plugins/norn-graph.plugin.json @@ -0,0 +1,54 @@ +{ + "schema": "gamecult.eve.plugin.v1", + "pluginId": "norn.graph", + "title": "Norn Graph", + "owner": "Norn", + "componentKinds": ["embed.norn"], + "commands": [ + { "command": "graph.node.activate", "schema": "norn.graph.command.v1", "effect": "activate-node" }, + { "command": "graph.focus", "schema": "norn.graph.command.v1", "effect": "focus-graph" } + ], + "runtime": { + "invocationModel": "executable-sidecar", + "contract": "gamecult.eve.plugin_abi.v1", + "transports": ["stdio"], + "authority": ["renderer-independent", "no-provider-state-mutation", "provider-accepts-or-denies-commands"], + "sidecar": { + "processKind": "long-running-daemon", + "protocol": "stdio-ndjson", + "requestSchema": "gamecult.eve.plugin_abi.request.v1", + "responseSchema": "gamecult.eve.plugin_abi.response.v1", + "operations": ["describe", "validate", "project", "measure"], + "commandEnvelope": "gamecult.eve.command.v1", + "receiptSchema": "gamecult.eve.command_receipt.v1", + "stateAuthority": "proposes-plugin-state-only-provider-accepts", + "launch": { + "artifact": "cargo:norn-eve-plugin", + "command": "norn-eve-plugin" + }, + "stdio": { + "encoding": "utf-8", + "framing": "ndjson", + "ordering": "sequential", + "blankLines": "ignored", + "diagnostics": "stderr" + } + } + }, + "stateSchemas": ["norn.graph.document.v1", "norn.graph.layout_request.v1", "norn.graph.layout_result.v1"], + "fixtures": [ + { + "fixtureId": "sai-nested-norn", + "schema": "gamecult.eve.plugin_abi_fixture.v1", + "path": "plugins/norn-graph.plugin-abi-fixture.json", + "role": "optional-nested-placement-evidence", + "authority": "Norn owns graph semantics; Sai supplies only an embed.norn composition slot." + } + ], + "abiFixtures": ["plugins/norn-graph.plugin-abi-fixture.json"], + "capabilities": { + "requires": ["embed.norn"], + "optionalCapabilities": ["graph.node.activate", "graph.pan", "graph.zoom"] + } +} + diff --git a/schemas/norn.graph.document.v1.schema.json b/schemas/norn.graph.document.v1.schema.json new file mode 100644 index 0000000..d35047d --- /dev/null +++ b/schemas/norn.graph.document.v1.schema.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "norn.graph.document.v1", + "type": "object", + "required": ["schema", "nodes", "edges"], + "properties": { + "schema": { "const": "norn.graph.document.v1" }, + "nodes": { + "type": "array", + "items": { + "type": "object", + "required": ["id"], + "properties": { + "id": { "type": "string", "minLength": 1 }, + "weight": { "type": "number", "exclusiveMinimum": 0 }, + "width": { "type": "number", "exclusiveMinimum": 0 }, + "height": { "type": "number", "exclusiveMinimum": 0 } + }, + "additionalProperties": true + } + }, + "edges": { + "type": "array", + "items": { + "type": "object", + "required": ["source", "target"], + "properties": { + "id": { "type": "string", "minLength": 1 }, + "source": { "type": "string", "minLength": 1 }, + "target": { "type": "string", "minLength": 1 } + }, + "additionalProperties": true + } + } + }, + "additionalProperties": true +} + diff --git a/schemas/norn.graph.layout_request.v1.schema.json b/schemas/norn.graph.layout_request.v1.schema.json new file mode 100644 index 0000000..6a6b769 --- /dev/null +++ b/schemas/norn.graph.layout_request.v1.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "norn.graph.layout_request.v1", + "type": "object", + "required": ["schema", "graph"], + "properties": { + "schema": { "const": "norn.graph.layout_request.v1" }, + "graph": { "$ref": "norn.graph.document.v1" }, + "layout": { + "type": "object", + "properties": { + "iterations": { "type": "integer", "minimum": 0, "maximum": 10000 }, + "rankGap": { "type": "number", "exclusiveMinimum": 0 }, + "nodeGap": { "type": "number", "exclusiveMinimum": 0 }, + "edgeLength": { "type": "number", "exclusiveMinimum": 0 } + }, + "additionalProperties": false + } + }, + "additionalProperties": false +} + diff --git a/schemas/norn.graph.layout_result.v1.schema.json b/schemas/norn.graph.layout_result.v1.schema.json new file mode 100644 index 0000000..3e89236 --- /dev/null +++ b/schemas/norn.graph.layout_result.v1.schema.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "norn.graph.layout_result.v1", + "type": "object", + "required": ["schema", "nodeBounds", "edgeRoutes", "viewportBounds"], + "properties": { + "schema": { "const": "norn.graph.layout_result.v1" }, + "nodeBounds": { "type": "array", "items": { "type": "object" } }, + "edgeRoutes": { "type": "array", "items": { "type": "object" } }, + "viewportBounds": { + "type": "object", + "required": ["x", "y", "width", "height"], + "properties": { + "x": { "type": "number" }, "y": { "type": "number" }, + "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 } + } + } + }, + "additionalProperties": true +} + diff --git a/state/map.yaml b/state/map.yaml index 78405be..12e1758 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -14,9 +14,9 @@ objective: architecture graphs, dataflow graphs, and cross-links rendered through React/WASM and C# windows. current: > - Keep Norn coherent as the in-repo Rust graph solver while treating the - React/WASM viewer and root C# generator/MCP server as inspection, bridge, - export, and benchmark surfaces only. + Publish Norn graph semantics through a runtime-independent Eve plugin + sidecar while keeping the Rust solver authoritative and treating renderers + as projections rather than semantic owners. constraints: - Keep persistent state small enough to rehydrate quickly. @@ -35,6 +35,9 @@ invariants: - `state/scratch.md` is disposable task memory. - `notes/fresh-workspace-handoff.md` is the short re-entry packet. - `crates/norn-rs` is the Rust layout solver source and crate authority. + - `crates/norn-eve-plugin` owns Eve plugin ABI dispatch and stdio framing. + - Provider state remains provider-owned; the plugin returns semantic and + measurement results but cannot commit provider commands or receipts. - `web/norn-viewer` is the live React/WASM client package. - The .NET generator and MCP server are peripheral support surfaces for Obsidian exports, legacy inspection, package tooling, and benchmark @@ -59,12 +62,16 @@ data_flow: - treat browser motion as presentation around the solver anchor - render graph partitions, cross-links, labels, selection, and detail panes - measure visual usefulness through benchmark artifacts when tuning + - dispatch typed Eve plugin requests and route graph measurement to the + Rust solver without importing any provider or renderer implementation output: - React `NornViewer` package exports - embedded solver WASM bytes under `web/norn-viewer/src/lib` - demo build artifacts under `web/norn-viewer/dist` - static SVG/JSON generator output under requested output directories - benchmark baselines and review artifacts under `benchmarks/` or `out/` + - Norn-owned plugin advertisements, ABI fixtures, and schemas + - sequential NDJSON plugin responses over stdio active_subgoals: - Keep the React/WASM viewer API stable and coarse. @@ -73,6 +80,8 @@ active_subgoals: - Use benchmark harnesses before claiming visual usefulness or realtime budget improvement. - Keep persistent project state distilled and current. + - Add CultMesh transport as another carrier for the same typed request and + response model when the daemon host contract is ready. accepted_design: - The Rust crate under `crates/norn-rs` is the primary product surface and @@ -85,6 +94,8 @@ accepted_design: second durable graph truth. - Benchmark probes should measure whether rendered graphs improve graph-truth recovery, not whether they look impressive. + - The Eve sidecar is transport and ABI ownership around `norn-rs`; it is not + a Unity, web, Sai, or provider-specific plugin host. rejected_paths: - name: dual_client_surface @@ -107,10 +118,10 @@ rejected_paths: current_status: summary: > - Persistent state machinery now names Norn as the in-repo Rust hybrid graph - layout solver. The React/WASM viewer and C# generator/MCP surface are - explicitly client windows and bridge/export tooling, not the repo's center - of gravity. + Norn owns its first executable Eve graph plugin sidecar. The sidecar + validates and measures graph documents through the Rust solver over a + bounded NDJSON stdio protocol; React/WASM, C#, Unity, and other runtimes + remain consumers that project the result. next_action: > For the next feature or fix, rehydrate from this map, identify the owning surface, then verify against the solver, WASM bridge, viewer, or visible @@ -133,6 +144,9 @@ verification: - command: "cargo test" cwd: "E:\\Projects\\Norn" use_when: "Rust solver source or algorithm changes" + - command: "cargo clippy --workspace --all-targets -- -D warnings" + cwd: "E:\\Projects\\Norn" + use_when: "Rust solver or Eve plugin sidecar changes" - command: "dotnet build E:\\Projects\\Norn\\Norn.csproj" cwd: "E:\\Projects\\Norn" use_when: "Peripheral C# bridge, export, or MCP changes"