Semantic Provenance and Attribution Layer for ecoPrimals
v0.7.27 | 1,181 tests | Edition 2024 | scyBorg Triple-Copyleft | Pure Rust | ecoBin compliant | Sovereign types
SweetGrass is the semantic layer that makes ecoPrimals activity visible and queryable. It tracks:
- Provenance: What created this data, how, and when?
- Attribution: Who contributed, and what roles did they play?
- Lineage: Where did this data come from originally?
- Rewards: Fair distribution based on contributions
Standards: W3C PROV-O | JSON-RPC 2.0 | tarpc binary RPC | REST | Pure Rust | No vendor lock-in
# Build the UniBin
cargo build --release
# Start the server (with TCP JSON-RPC on port 9100)
./target/release/sweetgrass server --port 9100
# Health check via REST
curl http://localhost:8080/health
# JSON-RPC over HTTP
curl -X POST http://localhost:8080/jsonrpc \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"health.check","params":{},"id":1}'
# JSON-RPC over TCP (newline-delimited)
echo '{"jsonrpc":"2.0","method":"health.liveness","params":{},"id":1}' | nc localhost 9100
# REST API
curl http://localhost:8080/api/v1/braids Applications (gAIa, sunCloud)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SWEETGRASS (you are here)
Provenance & Attribution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SOIL LINE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
RhizoCrypt (ephemeral network)
LoamSpine (permanent record)
| Crate | Purpose |
|---|---|
sweet-grass-core |
Braid, Agent, Activity, Entity, Contribution, DehydrationSummary, Config, niche.rs self-knowledge |
sweet-grass-store |
BraidStore trait + MemoryStore |
sweet-grass-store-postgres |
PostgreSQL backend |
sweet-grass-store-redb |
Embedded Pure Rust backend (redb, recommended) |
sweet-grass-store-sled |
Embedded Pure Rust backend (sled, deprecated — use redb) |
sweet-grass-factory |
Braid creation + attribution engine |
sweet-grass-query |
Graph traversal, PROV-O export |
sweet-grass-compression |
0/1/Many session compression |
sweet-grass-integration |
Primal discovery + capability clients |
sweet-grass-service |
UniBin server (REST + JSON-RPC + tarpc + UDS) |
| Protocol | Env Var | Latency | Use Case |
|---|---|---|---|
| tarpc | SWEETGRASS_TARPC_ADDRESS |
~50μs | Primal-to-primal binary RPC |
| TCP JSON-RPC | SWEETGRASS_PORT |
~1ms | Composition (--port, UniBin standard) |
| UDS JSON-RPC | SWEETGRASS_SOCKET |
~0.5ms | biomeOS IPC (XDG-compliant) |
| HTTP JSON-RPC | SWEETGRASS_HTTP_ADDRESS |
~10ms | 27 methods, batch, MCP tools |
| REST | SWEETGRASS_HTTP_ADDRESS |
~10ms | Debug, admin (/api/v1/braids) |
- JSON-RPC 2.0: 27 semantic methods (
braid.create,braid.commit,contribution.record,capabilities.list,tools.list,tools.call,health.check, etc.) with batch requests and notification support - MCP tool exposure:
tools.list+tools.callfor Squirrel AI coordination - Capability-domain symlink:
provenance.sock -> sweetgrass.sockfor Tier 3 filesystem discovery
Single binary with subcommands (sweetgrass server, sweetgrass status, sweetgrass capabilities, sweetgrass socket), graceful shutdown, runtime backend selection. The --port flag binds a newline-delimited TCP JSON-RPC listener per UniBin standard v1.1. The capabilities subcommand dumps capability metadata offline; socket prints the resolved UDS path.
- Full W3C PROV-O compliance (JSON-LD)
- Activity, Agent, Entity model
- Derivation chains and dependencies
- Content-addressed braids (URN format)
- ContentCategory, LicenseId, LicenseExpression, AttributionNotice — License and attribution metadata types
- 12 configurable agent roles with weights
- Time-decay models
- Recursive derivation chain propagation
- sunCloud integration ready
CapabilityProvider { capability, message }— Ecosystem-consistent capability provider error variantServiceError::TransportandServiceError::Discovery— IPC error variants for trio partner communication
- CircuitBreaker + RetryPolicy —
with_resilience()async helper for trio partner IPC
- Memory: Testing and development
- PostgreSQL: Production scale with migrations
- redb: Embedded Pure Rust, ACID transactions, actively maintained (recommended)
- Sled: Embedded Pure Rust, legacy (feature-gated,
--features sled) - Runtime selection via environment
- GDPR-inspired 5-level privacy controls
- Data subject rights (access, erasure, portability)
- Retention policies
- Selective disclosure
- Rust 1.87+ (stable, Edition 2024)
- Docker (optional, for PostgreSQL)
cargo build --release# All tests
cargo test --workspace
# Pre-commit checks
./scripts/check.sh
# Coverage
cargo llvm-cov --workspaceSTORAGE_BACKEND=redb # or: memory, postgres, sled (with --features sled)
DATABASE_URL=postgresql://... # for postgres backend
SWEETGRASS_HTTP_ADDRESS=0.0.0.0:8080 # REST + HTTP JSON-RPC endpoint
SWEETGRASS_PORT=9100 # TCP JSON-RPC (UniBin --port)
SWEETGRASS_TARPC_ADDRESS=0.0.0.0:8091 # Binary RPC endpoint
SWEETGRASS_SOCKET=/run/user/1000/biomeos/sweetgrass.sock # UDS JSON-RPCSee DEVELOPMENT.md for all options.
| Doc | Purpose |
|---|---|
| DEVELOPMENT.md | Dev setup, testing, code standards |
| QUICK_COMMANDS.md | Command reference |
| ROADMAP.md | Future plans |
| CHANGELOG.md | Version history |
| specs/ | Technical specifications (11 docs including Content Convergence) |
| docs/guides/ | Zero-copy, Tokio Console guides |
| showcase/ | Interactive demos |
| Metric | Value |
|---|---|
| Version | v0.7.27 |
| Tests | 1,181 passing |
| Coverage | 90.90% region / 89.58% line (llvm-cov, excluding Postgres Docker tests) |
| Edition | 2024 (MSRV 1.87) |
| Unsafe code | 0 (#![forbid(unsafe_code)] workspace-level + all crate roots) |
| Production unwraps | 0 (unwrap_used/expect_used = deny) |
| Clippy | 0 warnings (pedantic + nursery, -D warnings) |
| Max file size | 734 lines (limit: 1000) |
| .rs files | 154 (41,735 LOC) |
| TODOs in source | 0 |
| SPDX + copyright | All 154 .rs files |
| License | scyBorg Triple-Copyleft (AGPL-3.0-or-later + ORC-1.0 + CC-BY-SA-4.0) |
| cargo deny | advisories ok, bans ok, licenses ok, sources ok |
| Benchmarks | 7 criterion groups |
| JSON-RPC methods | 27 (batch + notification + MCP tool exposure) |
| Property-based tests | proptest (11 strategies) |
| Chaos/fault tests | 11 attribution + 17 service scenarios |
- Pure Rust (zero C/C++ dependencies in production)
- Cross-compilation ready (ARM64, musl, RISC-V targets documented)
- Platform-agnostic IPC (JSON-RPC + tarpc + UDS, no gRPC/protobuf)
cargo-denyenforced (tonic, prost, openssl banned)
parking_lot::RwLock throughout (Pure Rust, no poisoning, better perf than std).
ContentHash, BraidId, Did, ActivityId, Braid.mime_type, BraidMetadata.title, BraidMetadata.description, BraidMetadata.tags, EcoPrimalsAttributes.source_primal, EcoPrimalsAttributes.niche, LoamCommitRef.spine_id, BraidFactory.source_primal, and CompressionEngine.source_primal use Arc<str> internally — .clone() is O(1) atomic refcount increment. MIME type and tag indexes (MemoryStore, AgentContributions) share the same Arc<str>, eliminating per-query allocations on hot paths. BraidSignature fields use Cow<'static, str> for zero-allocation static values. BraidContext.imports uses IndexMap for deterministic serialization.
TOML config file support with full hierarchy: CLI args > env vars > config file > defaults. XDG-compliant config search ($SWEETGRASS_CONFIG, $XDG_CONFIG_HOME/sweetgrass/config.toml, ~/.config/sweetgrass/config.toml).
scyBorg Triple-Copyleft: AGPL-3.0-or-later (software), ORC-1.0 (game mechanics), CC-BY-SA-4.0 (creative content/documentation). See LICENSE.
This repo is part of the ecoPrimals sovereign computing ecosystem — a collection of pure Rust binaries that coordinate via JSON-RPC, capability-based routing, and zero compile-time coupling.
See wateringHole for ecosystem documentation, standards, and the primal registry.
Fair attribution. Complete transparency. Human dignity preserved.