graphforge 0.5.0__tar.gz → 0.5.2__tar.gz

{graphforge-0.5.0 → graphforge-0.5.2}/Cargo.lock

@@ -2018,7 +2018,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-api"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "cucumber",
@@ -2048,7 +2048,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-ast"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "graphforge-core",
  "serde",
@@ -2058,7 +2058,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-bindings-node"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-api",
@@ -2072,7 +2072,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-bindings-py"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "futures",
@@ -2085,7 +2085,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-cli"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "clap",
@@ -2098,7 +2098,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-core"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "serde",
  "serde_yaml_ng",
@@ -2109,7 +2109,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-cypher"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "graphforge-ast",
  "graphforge-core",
@@ -2121,7 +2121,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-exec"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "anyhow",
  "arrow",
@@ -2146,7 +2146,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-io"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "graphforge-core",
  "graphforge-storage",
@@ -2155,7 +2155,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-ir"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-ast",
@@ -2170,7 +2170,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-knowledge"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-core",
@@ -2183,7 +2183,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-ontology"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-core",
@@ -2198,7 +2198,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-plan"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "datafusion",
  "graphforge-core",
@@ -2208,7 +2208,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-provenance"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-core",
@@ -2219,7 +2219,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-rel"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow-data",
  "chrono",
@@ -2239,7 +2239,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-search"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "graphforge-core",
@@ -2254,7 +2254,7 @@ dependencies = [
 
 [[package]]
 name = "graphforge-storage"
-version = "0.5.0"
+version = "0.5.2"
 dependencies = [
  "arrow",
  "async-trait",

{graphforge-0.5.0 → graphforge-0.5.2}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/graphforge-core", "crates/graphforge-ast", "crates/graphforge-cypher", "crates/graphforge-ir", "crates/graphforge-rel", "crates/graphforge-exec", "crates/graphforge-search", "crates/graphforge-storage", "crates/graphforge-provenance", "crates/graphforge-knowledge", "crates/graphforge-ontology", "crates/graphforge-plan", "crates/graphforge-api", "crates/graphforge-bindings-py", "crates/graphforge-cli"]
 
 [workspace.package]
-version = "0.5.0"
+version = "0.5.2"
 edition = "2024"
 license = "Apache-2.0"
 license-file = "LICENSE"

graphforge-0.5.2/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: graphforge
+Version: 0.5.2
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Dist: pyarrow>=14
+Requires-Dist: polars>=0.20 ; extra == 'polars'
+Provides-Extra: polars
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES.md
+Summary: GraphForge native graph engine, bindings, and repository lifecycle CLI
+Keywords: graph,openCypher,Arrow,embedded,database
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://docs.graphforge.sh/
+Project-URL: Homepage, https://docs.graphforge.sh/
+Project-URL: Issues, https://github.com/CurateLabs/graphforge/issues
+Project-URL: Repository, https://github.com/CurateLabs/graphforge
+
+# GraphForge for Python
+
+Native Python bindings for GraphForge — an embedded openCypher graph engine
+with Rust-owned behavior, Arrow results, and a thin repository lifecycle CLI.
+
+## Install
+
+**pip**
+
+```bash
+pip install graphforge
+```
+
+**uv** (recommended)
+
+```bash
+uv add graphforge
+```
+
+## First use
+
+```python
+from graphforge import GraphForge
+
+forge = GraphForge()  # in-memory; pass a directory path for persistence
+
+alice = forge.add_node("Person", name="Alice", age=30)
+bob = forge.add_node("Person", name="Bob", age=25)
+forge.add_edge(alice, "KNOWS", bob, since=2020)
+
+table = forge.execute("""
+    MATCH (p:Person)-[:KNOWS]->(friend:Person)
+    WHERE p.age > 25
+    RETURN p.name AS person, friend.name AS friend
+""")
+print(table.to_pandas())
+```
+
+`execute()` returns an Apache Arrow `Table`. The `graphforge` console entry
+point launches the same Rust-owned repository CLI used by `gf` and
+`npx @curatelabs/graphforge-cli`.
+
+## Documentation
+
+- [Quick start](https://docs.graphforge.sh/guide/quickstart/)
+- [Installation](https://docs.graphforge.sh/guide/installation/)
+- [Repository integration](https://docs.graphforge.sh/guides/repository-integration/)
+- [Full documentation](https://docs.graphforge.sh/)
+

graphforge-0.5.2/README.md

@@ -0,0 +1,48 @@
+# GraphForge for Python
+
+Native Python bindings for GraphForge — an embedded openCypher graph engine
+with Rust-owned behavior, Arrow results, and a thin repository lifecycle CLI.
+
+## Install
+
+**pip**
+
+```bash
+pip install graphforge
+```
+
+**uv** (recommended)
+
+```bash
+uv add graphforge
+```
+
+## First use
+
+```python
+from graphforge import GraphForge
+
+forge = GraphForge()  # in-memory; pass a directory path for persistence
+
+alice = forge.add_node("Person", name="Alice", age=30)
+bob = forge.add_node("Person", name="Bob", age=25)
+forge.add_edge(alice, "KNOWS", bob, since=2020)
+
+table = forge.execute("""
+    MATCH (p:Person)-[:KNOWS]->(friend:Person)
+    WHERE p.age > 25
+    RETURN p.name AS person, friend.name AS friend
+""")
+print(table.to_pandas())
+```
+
+`execute()` returns an Apache Arrow `Table`. The `graphforge` console entry
+point launches the same Rust-owned repository CLI used by `gf` and
+`npx @curatelabs/graphforge-cli`.
+
+## Documentation
+
+- [Quick start](https://docs.graphforge.sh/guide/quickstart/)
+- [Installation](https://docs.graphforge.sh/guide/installation/)
+- [Repository integration](https://docs.graphforge.sh/guides/repository-integration/)
+- [Full documentation](https://docs.graphforge.sh/)

{graphforge-0.5.0 → graphforge-0.5.2}/crates/graphforge-api/Cargo.toml

@@ -8,16 +8,16 @@ license-file = "LICENSE"
 repository.workspace = true
 
 [dependencies]
-graphforge-core = { version = "0.5.0", path = "../graphforge-core" }
-graphforge-ir = { version = "0.5.0", path = "../graphforge-ir" }
-graphforge-ontology = { version = "0.5.0", path = "../graphforge-ontology" }
-graphforge-provenance = { version = "0.5.0", path = "../graphforge-provenance" }
-graphforge-knowledge = { version = "0.5.0", path = "../graphforge-knowledge" }
-graphforge-cypher = { version = "0.5.0", path = "../graphforge-cypher" }
-graphforge-rel = { version = "0.5.0", path = "../graphforge-rel" }
-graphforge-storage = { version = "0.5.0", path = "../graphforge-storage" }
-graphforge-exec = { version = "0.5.0", path = "../graphforge-exec" }
-graphforge-search = { version = "0.5.0", path = "../graphforge-search" }
+graphforge-core = { version = "0.5.2", path = "../graphforge-core" }
+graphforge-ir = { version = "0.5.2", path = "../graphforge-ir" }
+graphforge-ontology = { version = "0.5.2", path = "../graphforge-ontology" }
+graphforge-provenance = { version = "0.5.2", path = "../graphforge-provenance" }
+graphforge-knowledge = { version = "0.5.2", path = "../graphforge-knowledge" }
+graphforge-cypher = { version = "0.5.2", path = "../graphforge-cypher" }
+graphforge-rel = { version = "0.5.2", path = "../graphforge-rel" }
+graphforge-storage = { version = "0.5.2", path = "../graphforge-storage" }
+graphforge-exec = { version = "0.5.2", path = "../graphforge-exec" }
+graphforge-search = { version = "0.5.2", path = "../graphforge-search" }
 arrow = { workspace = true }
 datafusion = { workspace = true }
 futures = { workspace = true }

{graphforge-0.5.0 → graphforge-0.5.2}/crates/graphforge-api/src/algorithm_runs.rs

@@ -749,7 +749,7 @@ fn api_error(code: ApiErrorCode, message: impl Into<String>) -> GfError {
 
 #[cfg(test)]
 mod tests {
-    use std::collections::HashMap;
+    use std::collections::{BTreeMap, HashMap};
     use std::process::{Command, Stdio};
     use std::time::{Duration, Instant};
 
@@ -795,6 +795,102 @@ mod tests {
         (graph, descriptor)
     }
 
+    #[test]
+    fn wave10_request_identity_and_error_translation_guards_are_structured() {
+        let root = tempfile::tempdir().unwrap();
+        let (_, descriptor) = recorded_fixture(&root);
+        let base = RecordedAlgorithmRequest {
+            context: WriteContext {
+                operation_uuid: OperationId(uuid7(20)),
+                actor_uuid: None,
+            },
+            run_uuid: uuid7(21),
+            descriptor,
+            cancellation: None,
+        };
+
+        let mut request = base.clone();
+        request.context.operation_uuid = OperationId(Uuid::nil());
+        assert_eq!(
+            validate_request(&request).unwrap_err().code(),
+            "GF_VALIDATION"
+        );
+        let mut request = base.clone();
+        request.context.actor_uuid = Some(Uuid::nil());
+        assert_eq!(
+            validate_request(&request).unwrap_err().code(),
+            "GF_VALIDATION"
+        );
+        let mut request = base.clone();
+        request.run_uuid = Uuid::nil();
+        assert_eq!(
+            validate_request(&request).unwrap_err().code(),
+            "GF_VALIDATION"
+        );
+        let mut request = base;
+        request.run_uuid = Uuid::from_u128(1);
+        assert_eq!(
+            validate_request(&request).unwrap_err().code(),
+            "GF_VALIDATION"
+        );
+
+        assert_eq!(
+            invocation_error(InvocationError::SchemaMismatch).code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+        assert_eq!(
+            invocation_error(InvocationError::ProjectionChanged).code(),
+            "GF_EXECUTION"
+        );
+        assert_eq!(
+            invocation_error(InvocationError::Graph(GfError::Validation("bad".into()))).code(),
+            "GF_VALIDATION"
+        );
+        let descriptor_error = InvocationDescriptor::new(
+            Algorithm::Rank(RankAlgorithm::Degree),
+            [0; 32],
+            BTreeMap::new(),
+        )
+        .unwrap_err();
+        assert_eq!(
+            invocation_error(InvocationError::Descriptor(descriptor_error)).code(),
+            "GF_VALIDATION"
+        );
+    }
+
+    #[test]
+    fn wave10_existing_run_lifecycle_errors_distinguish_all_terminal_states() {
+        let completed = AlgorithmRunEvent::new(
+            uuid7(30),
+            uuid7(31),
+            AlgorithmRunState::Completed,
+            Some([1; 32]),
+            None,
+            2,
+            uuid7(32),
+        )
+        .unwrap();
+        assert_eq!(
+            existing_lifecycle_error(Some(&completed)).code(),
+            "GF_RESULT_NOT_RETAINED"
+        );
+        let failed = AlgorithmRunEvent::new(
+            uuid7(33),
+            uuid7(31),
+            AlgorithmRunState::Failed,
+            None,
+            Some("GF_TEST".into()),
+            3,
+            uuid7(34),
+        )
+        .unwrap();
+        assert_eq!(
+            existing_lifecycle_error(Some(&failed)).code(),
+            "GF_EXECUTION"
+        );
+        assert_eq!(existing_lifecycle_error(None).code(), "GF_EXECUTION");
+    }
+
     #[test]
     fn recorded_dispatch_commits_start_and_completed_before_return() {
         let root = tempfile::tempdir().unwrap();

{graphforge-0.5.0 → graphforge-0.5.2}/crates/graphforge-api/src/belief_projection.rs

@@ -1393,7 +1393,7 @@ mod tests {
     use std::sync::{Arc, mpsc};
     use std::time::Duration;
 
-    use arrow::array::{FixedSizeBinaryBuilder, ListBuilder, StringBuilder};
+    use arrow::array::{FixedSizeBinaryArray, FixedSizeBinaryBuilder, ListBuilder, StringBuilder};
     use arrow::datatypes::{DataType, Field, Schema};
 
     use super::*;
@@ -1411,6 +1411,226 @@ mod tests {
         Uuid::from_bytes(bytes)
     }
 
+    #[test]
+    fn wave12_attachment_and_projection_helper_errors_are_exact_and_closed() {
+        let duplicate_policy = BeliefProjectionPolicyV1 {
+            included_statuses: vec![AssertionStatus::Supported, AssertionStatus::Supported],
+            statusless: StatuslessPolicyV1::Include,
+            supersession_branches: SupersessionBranchPolicyV1::Reject,
+            hypotheses: HypothesisSelectionPolicyV1::IncludeAllCurrentMembers,
+        };
+        assert_eq!(
+            duplicate_policy.canonical_bytes().unwrap_err().code(),
+            "GF_VALIDATION"
+        );
+        let descriptor = InvocationDescriptor::new(
+            graphforge_core::algorithms::Algorithm::Rank(
+                graphforge_core::algorithms::RankAlgorithm::Degree,
+            ),
+            [0; 32],
+            BTreeMap::from([
+                ("directed".into(), crate::InvocationParameter::Bool(false)),
+                (
+                    "label".into(),
+                    crate::InvocationParameter::Utf8("Person".into()),
+                ),
+                ("via".into(), crate::InvocationParameter::Utf8("*".into())),
+            ]),
+        )
+        .unwrap();
+        let valid = AttachResolvedRunRequest {
+            context: WriteContext {
+                operation_uuid: OperationId(uuid7(1)),
+                actor_uuid: None,
+            },
+            attachment_uuid: uuid7(2),
+            run_uuid: uuid7(3),
+            descriptor,
+        };
+        assert!(validate_attachment_request(&valid).is_ok());
+        for (mut request, message) in [
+            (
+                AttachResolvedRunRequest {
+                    context: WriteContext {
+                        operation_uuid: OperationId(Uuid::nil()),
+                        actor_uuid: None,
+                    },
+                    ..valid.clone()
+                },
+                "operation_uuid must not be nil",
+            ),
+            (
+                AttachResolvedRunRequest {
+                    attachment_uuid: Uuid::nil(),
+                    ..valid.clone()
+                },
+                "attachment_uuid must not be nil",
+            ),
+            (
+                AttachResolvedRunRequest {
+                    run_uuid: Uuid::nil(),
+                    ..valid.clone()
+                },
+                "run_uuid must not be nil",
+            ),
+            (
+                AttachResolvedRunRequest {
+                    context: WriteContext {
+                        operation_uuid: OperationId(uuid7(4)),
+                        actor_uuid: Some(Uuid::nil()),
+                    },
+                    ..valid.clone()
+                },
+                "actor_uuid must not be nil",
+            ),
+            (
+                AttachResolvedRunRequest {
+                    attachment_uuid: Uuid::from_u128(5),
+                    ..valid
+                },
+                "attachment_uuid must be UUIDv7",
+            ),
+        ] {
+            let error = validate_attachment_request(&request).unwrap_err();
+            assert_eq!(error.code(), "GF_VALIDATION");
+            assert_eq!(error.to_string(), format!("validation error: {message}"));
+            request.context.actor_uuid = None;
+        }
+        assert_eq!(schema("bad schema").code(), "GF_SCHEMA_MISMATCH");
+        assert_eq!(ambiguous("two branches").code(), "GF_AMBIGUOUS_PROJECTION");
+        assert_eq!(
+            transaction_conflict("drift").code(),
+            "GF_IDEMPOTENCY_CONFLICT"
+        );
+        assert_eq!(
+            descriptor_fingerprint(b"not a descriptor")
+                .unwrap_err()
+                .code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+
+        let empty = RecordBatch::new_empty(Arc::new(Schema::empty()));
+        assert_eq!(
+            exact_fingerprint(
+                &empty,
+                &FixedSizeBinaryArray::try_from_iter([vec![0; 32]].into_iter()).unwrap(),
+            )
+            .unwrap_err()
+            .code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+        for result in [
+            strings(&empty, "missing").map(|_| ()),
+            fixed(&empty, "missing").map(|_| ()),
+            lists(&empty, "missing").map(|_| ()),
+        ] {
+            assert_eq!(result.unwrap_err().code(), "GF_SCHEMA_MISMATCH");
+        }
+        let no_batches = graphforge_exec::ExecutionResult {
+            schema: Arc::new(Schema::empty()),
+            batches: vec![],
+            stats: graphforge_exec::ExecutionStats::default(),
+            side_effects: None,
+            mutation_receipt: None,
+        };
+        assert_eq!(
+            one_batch(&no_batches, "empty").unwrap_err().code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+        let null_uuid =
+            FixedSizeBinaryArray::try_from_sparse_iter_with_size([None::<Vec<u8>>].into_iter(), 16)
+                .unwrap();
+        assert_eq!(
+            uuid_at(&null_uuid, 0, "assertion_uuid").unwrap_err().code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+        let fingerprints =
+            FixedSizeBinaryArray::try_from_iter([vec![1; 32], vec![2; 32]].into_iter()).unwrap();
+        let fingerprint_batch = RecordBatch::try_new(
+            Arc::new(Schema::new(vec![Field::new(
+                "result_fingerprint",
+                DataType::FixedSizeBinary(32),
+                false,
+            )])),
+            vec![Arc::new(fingerprints.clone())],
+        )
+        .unwrap();
+        assert_eq!(
+            exact_fingerprint(&fingerprint_batch, &fingerprints)
+                .unwrap_err()
+                .code(),
+            "GF_SCHEMA_MISMATCH"
+        );
+    }
+
+    #[test]
+    fn attachment_replay_requires_exact_resolved_content() {
+        let graph = GraphForge::new(None).unwrap();
+        let policy = BeliefProjectionPolicyV1 {
+            included_statuses: vec![AssertionStatus::Supported],
+            statusless: StatuslessPolicyV1::Include,
+            supersession_branches: SupersessionBranchPolicyV1::Reject,
+            hypotheses: HypothesisSelectionPolicyV1::IncludeAllCurrentMembers,
+        };
+        let (policy_bytes, policy_fingerprint) = policy_fingerprint(&policy).unwrap();
+        let descriptor = InvocationDescriptor::new(
+            graphforge_core::algorithms::Algorithm::Rank(
+                graphforge_core::algorithms::RankAlgorithm::Degree,
+            ),
+            [0; 32],
+            BTreeMap::from([
+                ("directed".into(), crate::InvocationParameter::Bool(false)),
+                (
+                    "label".into(),
+                    crate::InvocationParameter::Utf8("Person".into()),
+                ),
+                ("via".into(), crate::InvocationParameter::Utf8("*".into())),
+            ]),
+        )
+        .unwrap();
+        let projection = ResolvedBeliefProjection {
+            graph: Box::new(graph),
+            source_generation_uuid: uuid7(20),
+            transaction_cutoff_micros: 10,
+            valid_time_micros: None,
+            policy_bytes: policy_bytes.clone(),
+            policy_fingerprint,
+            snapshot_fingerprint: [1; 32],
+            valid_time_fingerprint: None,
+            graph_content_fingerprint: [2; 32],
+            source_record_uuids: vec![uuid7(21)],
+        };
+        let request = AttachResolvedRunRequest {
+            context: context(22),
+            attachment_uuid: uuid7(23),
+            run_uuid: uuid7(24),
+            descriptor,
+        };
+        let row = BeliefProjectionAttachment::new(
+            request.attachment_uuid,
+            uuid7(25),
+            projection.source_generation_uuid,
+            projection.transaction_cutoff_micros,
+            projection.valid_time_micros,
+            BELIEF_PROJECTION_POLICY_VERSION,
+            policy_bytes,
+            projection.snapshot_fingerprint,
+            projection.valid_time_fingerprint,
+            projection.graph_content_fingerprint,
+            *request.descriptor.fingerprint(),
+            projection.source_record_uuids.clone(),
+            uuid7(26),
+            11,
+        )
+        .unwrap();
+        assert_eq!(
+            verify_existing_attachment(&row, &projection, &request)
+                .unwrap_err()
+                .code(),
+            "GF_IDEMPOTENCY_CONFLICT"
+        );
+    }
+
     fn context(seed: u8) -> WriteContext {
         WriteContext {
             operation_uuid: OperationId(uuid7(seed)),
@@ -1485,6 +1705,15 @@ mod tests {
                 policy: policy.clone(),
             })
             .unwrap();
+        assert_ne!(projection.source_generation_uuid(), Uuid::nil());
+        assert!(!projection.policy_bytes().is_empty());
+        assert_ne!(projection.policy_fingerprint(), [0; 32]);
+        assert_ne!(projection.snapshot_fingerprint(), [0; 32]);
+        assert_eq!(projection.transaction_cutoff_micros(), i64::MAX);
+        assert_eq!(projection.valid_time_micros(), None);
+        assert_eq!(projection.valid_time_fingerprint(), None);
+        assert_ne!(projection.graph_content_fingerprint(), [0; 32]);
+        assert_eq!(projection.source_record_uuids(), &[uuid7(5)]);
         assert_eq!(
             graphforge_storage::read_nodes(&projection.graph.dir)
                 .unwrap()