grc_20/
lib.rs

1//! GRC-20 v2: Binary property graph format for decentralized knowledge networks.
2//!
3//! This crate provides encoding, decoding, and validation for the GRC-20 v2
4//! binary format as specified in the GRC-20 v2 Specification.
5//!
6//! # Overview
7//!
8//! GRC-20 is a property graph format designed for:
9//! - **Event-sourced data**: All state changes are expressed as operations
10//! - **Binary-first**: Optimized for compressed wire size and decode speed
11//! - **Pluralistic**: Multiple spaces can hold conflicting views
12//!
13//! # Quick Start
14//!
15//! ```rust
16//! use std::borrow::Cow;
17//! use grc_20::{Edit, Op, CreateEntity, PropertyValue, Value, DataType};
18//! use grc_20::codec::{encode_edit, decode_edit};
19//! use grc_20::genesis::properties;
20//!
21//! // Create an edit with an entity
22//! let edit = Edit {
23//!     id: [1u8; 16],
24//!     name: Cow::Owned("My Edit".to_string()),
25//!     authors: vec![[2u8; 16]],
26//!     created_at: 1234567890,
27//!     ops: vec![
28//!         Op::CreateEntity(CreateEntity {
29//!             id: [3u8; 16],
30//!             values: vec![PropertyValue {
31//!                 property: properties::name(),
32//!                 value: Value::Text {
33//!                     value: Cow::Owned("Alice".to_string()),
34//!                     language: None,
35//!                 },
36//!             }],
37//!             context: None,
38//!         }),
39//!     ],
40//! };
41//!
42//! // Encode to binary
43//! let bytes = encode_edit(&edit).unwrap();
44//!
45//! // Decode back (zero-copy for uncompressed data)
46//! let decoded = decode_edit(&bytes).unwrap();
47//! assert_eq!(edit.id, decoded.id);
48//! ```
49//!
50//! # Modules
51//!
52//! - [`model`]: Core data types (Entity, Relation, Value, Op, Edit)
53//! - [`codec`]: Binary encoding/decoding with compression support
54//! - [`validate`]: Semantic validation
55//! - [`genesis`]: Well-known IDs from the Genesis Space
56//! - [`error`]: Error types
57//! - [`limits`]: Security limits for decoding
58//!
59//! # Security
60//!
61//! The decoder is designed to safely handle untrusted input:
62//! - All allocations are bounded by configurable limits
63//! - Varints are limited to prevent overflow
64//! - Invalid data is rejected with descriptive errors
65//!
66//! # Wire Format
67//!
68//! Edits use a binary format with optional zstd compression:
69//! - Uncompressed: `GRC2` magic + version + data
70//! - Compressed: `GRC2Z` magic + uncompressed size + zstd data
71//!
72//! The decoder automatically detects and handles both formats.
73
74pub mod codec;
75pub mod error;
76pub mod genesis;
77pub mod limits;
78pub mod model;
79pub mod util;
80pub mod validate;
81
82// Re-export commonly used types at crate root
83pub use codec::{
84    decode_edit, decompress, encode_edit, encode_edit_compressed,
85    encode_edit_compressed_with_options, encode_edit_profiled, encode_edit_with_options,
86    EncodeOptions,
87};
88pub use error::{DecodeError, EncodeError, ValidationError};
89pub use model::{
90    CreateEntity, CreateRelation, DataType, DecimalMantissa, DeleteEntity,
91    DeleteRelation, DictionaryBuilder, Edit, EditBuilder, EmbeddingSubType, EntityBuilder, Id,
92    Op, Property, PropertyValue, RelationBuilder, UnsetLanguage, UnsetRelationField, UnsetValue,
93    UpdateEntity, UpdateEntityBuilder, UpdateRelation, Value, WireDictionaries,
94};
95pub use model::builder::UpdateRelationBuilder;
96pub use model::id::{derived_uuid, format_id, parse_id, text_value_id, value_id, NIL_ID};
97pub use util::{
98    format_date_rfc3339, format_datetime_rfc3339, format_time_rfc3339,
99    parse_date_rfc3339, parse_datetime_rfc3339, parse_time_rfc3339, DateTimeParseError,
100};
101pub use validate::{validate_edit, validate_position, validate_value, SchemaContext};
102
103/// Crate version.
104pub const VERSION: &str = env!("CARGO_PKG_VERSION");
105
106/// GRC-20 spec version this crate implements.
107pub const SPEC_VERSION: &str = "0.17.0";
grc_20/lib.rs

grc_20/
lib.rs
