Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat(pack): onto_pack / onto_unpack, portable verified knowledge artifacts

FABIOTESS07deec6fb9dc
diff --git a/CLAUDE.md b/CLAUDE.md
index 36d5762c..8e800b6c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -87,6 +87,8 @@ Claude dynamically decides the next tool call based on what the previous tool re
| `onto_align` | To detect alignment candidates (equivalentClass, exactMatch, subClassOf) between two ontologies using 7 weighted signals (6 structural + embedding similarity when embeddings are loaded). Labels are matched with their parsed BCP-47 language tag; with the multilingual embedder loaded, cross-lingual pairs that share no surface tokens (e.g. `Dog`↔`Chien`) are admitted via the embedding signal. Restrict the languages consulted with `[language] preferred = [...]` / `OPEN_ONTOLOGIES_LANGUAGES` (empty = all) |
| `onto_align_feedback` | To accept/reject alignment candidates for self-calibrating confidence weights |
| `onto_communities` | To cluster the entity graph and get a SKELETON per community (size, top members by degree, internal relations, bridges to other communities). Deterministic modularity optimisation, no model involved. Write one report per skeleton, then answer corpus-wide questions ("what are the themes", "summarise this corpus") from the reports instead of traversing from an anchor entity, which such questions do not have. The GraphRAG global-search pattern with the expensive half left to the orchestrator |
+| `onto_pack` | To write the loaded graph and its verification evidence to a portable versioned artifact: sorted N-Triples, a manifest (name, version, counts, timestamp, tool version, sha256) and the lint/enforce results recorded at pack time. What you promote between environments is then a graph that has already passed its checks, with the evidence attached |
+| `onto_unpack` | To load a pack, refusing it if the checksum does not match. `verify_only` inspects the manifest and evidence without loading |
| `onto_lineage` | To view the session's lineage trail (plan → enforce → apply → monitor → drift) |
| `onto_lint_feedback` | To accept/dismiss a lint issue — teaches lint to suppress repeatedly dismissed warnings |
| `onto_enforce_feedback` | To accept/dismiss an enforce violation — teaches enforce to suppress repeatedly dismissed violations |
diff --git a/src/inputs.rs b/src/inputs.rs
index b6184b9a..ae8f6fb1 100644
--- a/src/inputs.rs
+++ b/src/inputs.rs
@@ -1096,3 +1096,23 @@ pub struct OntoCommunitiesInput {
/// How many members, relations and bridges to describe per community (default 8)
pub top_members: Option<usize>,
}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct OntoPackInput {
+ /// Where to write the pack
+ pub path: String,
+ /// Pack name (default: the file stem)
+ pub name: Option<String>,
+ /// Version string (default: "1.0.0")
+ pub version: Option<String>,
+ /// Record lint and enforce results in the manifest as evidence (default true)
+ pub include_evidence: Option<bool>,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct OntoUnpackInput {
+ /// Pack to read
+ pub path: String,
+ /// Verify the checksum and report the manifest without loading (default false)
+ pub verify_only: Option<bool>,
+}
diff --git a/src/lib.rs b/src/lib.rs
index a8910f8d..2ae4c9ca 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -23,6 +23,7 @@ pub mod eval_alignment;
pub mod eval_rag;
pub mod extract_scaffold;
pub mod flora_pipeline;
+pub mod pack;
pub mod policy;
pub mod projection_check;
pub mod shape_combinatorics;
diff --git a/src/pack.rs b/src/pack.rs
new file mode 100644
index 00000000..5ad10618
--- /dev/null
+++ b/src/pack.rs
@@ -0,0 +1,139 @@
+//! Knowledge packs: a verified graph and its evidence in one portable file.
+//!
+//! TrustGraph calls the idea a knowledge core, and it is the right one: what
+//! you promote between environments should be a versioned artifact, not a
+//! pile of loose Turtle whose provenance and checks live somewhere else. The
+//! shape here is deliberately boring so that anything can read it, and the
+//! graph is stored as ordinary N-Triples rather than a proprietary blob.
+//!
+//! A pack carries:
+//!
+//! - the graph itself (N-Triples, sorted, so two packs of the same graph
+//! are byte-identical and diffable);
+//! - a manifest: name, version, counts, creation time, tool version;
+//! - a checksum over the graph, so tampering or truncation is detectable;
+//! - the verification evidence recorded at pack time (lint, enforce), so
+//! the receiving environment can see what the graph passed rather than
+//! take it on trust.
+//!
+//! Unpacking verifies the checksum before loading a single triple.
+
+use crate::graph::GraphStore;
+use sha2::{Digest, Sha256};
+use std::sync::Arc;
+
+pub struct Packer {
+ graph: Arc<GraphStore>,
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+pub struct Manifest {
+ pub name: String,
+ pub version: String,
+ pub created_at: String,
+ pub tool_version: String,
+ pub triples: usize,
+ pub sha256: String,
+ /// What the graph passed at pack time. Absent means not checked, which
+ /// is itself information the receiver should act on.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub evidence: Option<serde_json::Value>,
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+pub struct Pack {
+ pub manifest: Manifest,
+ /// N-Triples, sorted line-wise.
+ pub graph: String,
+}
+
+fn checksum(text: &str) -> String {
+ let mut hasher = Sha256::new();
+ hasher.update(text.as_bytes());
+ format!("{:x}", hasher.finalize())
+}
+
+impl Packer {
+ pub fn new(graph: Arc<GraphStore>) -> Self {
+ Self { graph }
+ }
+
+ /// Write the loaded graph and its evidence to `path` as a pack.
+ pub fn pack(
+ &self,
+ path: &str,
+ name: &str,
+ version: &str,
+ evidence: Option<serde_json::Value>,
+ ) -> anyhow::Result<String> {
+ let nt = self.graph.serialize("ntriples")?;
+
+ // Sorted, so the same graph always produces the same bytes: packs
+ // become diffable and the checksum becomes meaningful across
+ // machines rather than reflecting store iteration order.
+ let mut lines: Vec<&str> = nt.lines().filter(|l| !l.trim().is_empty()).collect();
+ lines.sort_unstable();
+ let graph = lines.join("\n") + "\n";
+
+ let manifest = Manifest {
+ name: name.to_string(),
+ version: version.to_string(),
+ created_at: chrono::Utc::now().to_rfc3339(),
+ tool_version: env!("CARGO_PKG_VERSION").to_string(),
+ triples: lines.len(),
+ sha256: checksum(&graph),
+ evidence,
+ };
+
+ let pack = Pack { manifest, graph };
+ let json = serde_json::to_string_pretty(&pack)?;
+ std::fs::write(path, &json)?;
+
+ Ok(serde_json::json!({
+ "ok": true,
+ "path": path,
+ "name": pack.manifest.name,
+ "version": pack.manifest.version,
+ "triples": pack.manifest.triples,
+ "sha256": pack.manifest.sha256,
+ "has_evidence": pack.manifest.evidence.is_some(),
+ })
+ .to_string())
+ }
+
+ /// Load a pack, refusing it if the checksum does not match.
+ pub fn unpack(&self, path: &str, verify_only: bool) -> anyhow::Result<String> {
+ let raw = std::fs::read_to_string(path)?;
+ let pack: Pack = serde_json::from_str(&raw)?;
+
+ let actual = checksum(&pack.graph);
+ if actual != pack.manifest.sha256 {
+ return Ok(serde_json::json!({
+ "error": "checksum mismatch: the pack was modified or truncated after it was written",
+ "expected": pack.manifest.sha256,
+ "actual": actual,
+ })
+ .to_string());
+ }
+
+ if verify_only {
+ return Ok(serde_json::json!({
+ "ok": true,
+ "verified": true,
+ "loaded": false,
+ "manifest": pack.manifest,
+ })
+ .to_string());
+ }
+
+ let loaded = self.graph.load_ntriples(&pack.graph)?;
+ Ok(serde_json::json!({
+ "ok": true,
+ "verified": true,
+ "loaded": true,
+ "triples_loaded": loaded,
+ "manifest": pack.manifest,
+ })
+ .to_string())
+ }
+}
diff --git a/src/server.rs b/src/server.rs
index bdc4af6e..0c0bef09 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -883,6 +883,45 @@ impl OpenOntologiesServer {
}
}
+ #[tool(name = "onto_pack", description = "Write the loaded graph and its verification evidence to a portable, versioned pack: sorted N-Triples plus a manifest (name, version, counts, timestamp, sha256, and the lint/enforce results recorded at pack time). Use to promote a verified graph between environments as one auditable artifact.")]
+ async fn onto_pack(&self, Parameters(input): Parameters<OntoPackInput>) -> String {
+ use crate::pack::Packer;
+ let name = input.name.unwrap_or_else(|| {
+ std::path::Path::new(&input.path)
+ .file_stem().and_then(|s| s.to_str()).unwrap_or("pack").to_string()
+ });
+ // Evidence is gathered here, at pack time, so the artifact records
+ // what the graph passed rather than asking the receiver to trust it.
+ let evidence = if input.include_evidence.unwrap_or(true) {
+ let lint = self.graph.serialize("turtle").ok()
+ .and_then(|ttl| crate::ontology::OntologyService::lint(&ttl).ok());
+ let enforce = crate::enforce::Enforcer::new(self.db.clone(), self.graph.clone())
+ .enforce("generic").ok();
+ Some(serde_json::json!({
+ "lint": lint.and_then(|l| serde_json::from_str::<serde_json::Value>(l.as_str()).ok()),
+ "enforce_generic": enforce.and_then(|e| serde_json::from_str::<serde_json::Value>(e.as_str()).ok()),
+ }))
+ } else {
+ None
+ };
+ match Packer::new(self.graph.clone()).pack(
+ &input.path, &name,
+ &input.version.unwrap_or_else(|| "1.0.0".into()), evidence,
+ ) {
+ Ok(json) => json,
+ Err(e) => format!(r#"{{"error":"{}"}}"#, e.to_string().replace('"', "'")),
+ }
+ }
+
+ #[tool(name = "onto_unpack", description = "Load a pack written by onto_pack, refusing it if the checksum does not match. Pass verify_only to inspect the manifest and evidence without loading.")]
+ async fn onto_unpack(&self, Parameters(input): Parameters<OntoUnpackInput>) -> String {
+ use crate::pack::Packer;
+ match Packer::new(self.graph.clone()).unpack(&input.path, input.verify_only.unwrap_or(false)) {
+ Ok(json) => json,
+ Err(e) => format!(r#"{{"error":"{}"}}"#, e.to_string().replace('"', "'")),
+ }
+ }
+
#[tool(name = "onto_communities", description = "Detect communities in the loaded entity graph and return a SKELETON per community: size, top members by degree, internal relations, and the bridges connecting it to other communities. Deterministic label propagation, no model involved. Use the skeletons to write one report per community, then answer corpus-wide questions (themes, overview, what is this corpus about) by reasoning over the reports instead of traversing from an anchor entity.")]
async fn onto_communities(&self, Parameters(input): Parameters<OntoCommunitiesInput>) -> String {
use crate::communities::Communities;