grc-20 0.4.0

GRC-20 v2 binary property graph format for decentralized knowledge networks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! GRC-20 v2: Binary property graph format for decentralized knowledge networks.
//!
//! This crate provides encoding, decoding, and validation for the GRC-20 v2
//! binary format as specified in the GRC-20 v2 Specification.
//!
//! # Overview
//!
//! GRC-20 is a property graph format designed for:
//! - **Event-sourced data**: All state changes are expressed as operations
//! - **Binary-first**: Optimized for compressed wire size and decode speed
//! - **Pluralistic**: Multiple spaces can hold conflicting views
//!
//! # Quick Start
//!
//! ```rust
//! use std::borrow::Cow;
//! use grc_20::{Edit, Op, CreateEntity, PropertyValue, Value, DataType};
//! use grc_20::codec::{encode_edit, decode_edit};
//! use grc_20::genesis::properties;
//!
//! // Create an edit with an entity
//! let edit = Edit {
//!     id: [1u8; 16],
//!     name: Cow::Owned("My Edit".to_string()),
//!     authors: vec![[2u8; 16]],
//!     created_at: 1234567890,
//!     ops: vec![
//!         Op::CreateEntity(CreateEntity {
//!             id: [3u8; 16],
//!             values: vec![PropertyValue {
//!                 property: properties::name(),
//!                 value: Value::Text {
//!                     value: Cow::Owned("Alice".to_string()),
//!                     language: None,
//!                 },
//!             }],
//!             context: None,
//!         }),
//!     ],
//! };
//!
//! // Encode to binary
//! let bytes = encode_edit(&edit).unwrap();
//!
//! // Decode back (zero-copy for uncompressed data)
//! let decoded = decode_edit(&bytes).unwrap();
//! assert_eq!(edit.id, decoded.id);
//! ```
//!
//! # Modules
//!
//! - [`model`]: Core data types (Entity, Relation, Value, Op, Edit)
//! - [`codec`]: Binary encoding/decoding with compression support
//! - [`validate`]: Semantic validation
//! - [`genesis`]: Well-known IDs from the Genesis Space
//! - [`error`]: Error types
//! - [`limits`]: Security limits for decoding
//!
//! # Security
//!
//! The decoder is designed to safely handle untrusted input:
//! - All allocations are bounded by configurable limits
//! - Varints are limited to prevent overflow
//! - Invalid data is rejected with descriptive errors
//!
//! # Wire Format
//!
//! Edits use a binary format with optional zstd compression:
//! - Uncompressed: `GRC2` magic + version + data
//! - Compressed: `GRC2Z` magic + uncompressed size + zstd data
//!
//! The decoder automatically detects and handles both formats.

pub mod codec;
pub mod error;
pub mod genesis;
pub mod limits;
pub mod model;
pub mod util;
pub mod validate;

// Re-export commonly used types at crate root
pub use codec::{
    decode_edit, decompress, encode_edit, encode_edit_compressed,
    encode_edit_compressed_with_options, encode_edit_profiled, encode_edit_with_options,
    EncodeOptions,
};
pub use error::{DecodeError, EncodeError, ValidationError};
pub use model::{
    CreateEntity, CreateRelation, DataType, DecimalMantissa, DeleteEntity,
    DeleteRelation, DictionaryBuilder, Edit, EditBuilder, EmbeddingSubType, EntityBuilder, Id,
    Op, Property, PropertyValue, RelationBuilder, UnsetLanguage, UnsetRelationField, UnsetValue,
    UpdateEntity, UpdateEntityBuilder, UpdateRelation, Value, WireDictionaries,
};
pub use model::builder::UpdateRelationBuilder;
pub use model::id::{derived_uuid, format_id, parse_id, text_value_id, value_id, NIL_ID};
pub use util::{
    format_date_rfc3339, format_datetime_rfc3339, format_time_rfc3339,
    parse_date_rfc3339, parse_datetime_rfc3339, parse_time_rfc3339, DateTimeParseError,
};
pub use validate::{validate_edit, validate_position, validate_value, SchemaContext};

/// Crate version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// GRC-20 spec version this crate implements.
pub const SPEC_VERSION: &str = "0.17.0";