339 lines
8.9 KiB
Markdown
339 lines
8.9 KiB
Markdown
# Libertaria SDK for Janus
|
||
|
||
> Sovereign; Kinetic; Anti-Fragile.
|
||
|
||
**Version:** 0.2.0-alpha
|
||
**Status:** Sprint 2 Complete (GQL Parser + Codegen)
|
||
**License:** MIT + Libertaria Commons Clause
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
The Libertaria SDK provides primitives for building sovereign agent networks on top of [Janus](https://github.com/janus-lang/janus) — the programming language designed for Carbon-Silicon symbiosis.
|
||
|
||
This SDK implements the **L1 Identity Layer** of the Libertaria Stack, featuring:
|
||
|
||
- **Cryptographic Identity** — Ed25519-based with rotation and burn capabilities
|
||
- **Trust Graph** — QVL (Quasar Vector Lattice) engine with betrayal detection
|
||
- **GQL (Graph Query Language)** — ISO/IEC 39075:2024 compliant query interface
|
||
- **Persistent Storage** — libmdbx backend with Kenya Rule compliance (<10MB)
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Application Layer │
|
||
│ (Your Agent / libertaria.bot) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Libertaria SDK │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Identity │ │ Trust Graph │ │ GQL │ │
|
||
│ │ (identity) │ │ (qvl) │ │ (gql/*.zig) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Message │ │ Context │ │ Memory │ │
|
||
│ │ (message) │ │ (context) │ │ (memory) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Janus Standard Library │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Janus Compiler (:service) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
### 1. Sovereign Identity
|
||
|
||
```janus
|
||
import libertaria.{identity}
|
||
|
||
// Create a new sovereign identity
|
||
let id = identity.create()
|
||
|
||
// Sign a message
|
||
let msg = bytes.from_string("Hello Sovereigns!")
|
||
let sig = identity.sign(id, msg)
|
||
|
||
// Verify signature
|
||
assert identity.verify(id, msg, sig)
|
||
|
||
// Rotate identity (new keys, linked provenance)
|
||
let (new_id, old_id) = identity.rotate(id)
|
||
|
||
// Burn identity (cryptographic deletion)
|
||
let burned = identity.burn(id)
|
||
```
|
||
|
||
### 2. Trust Graph (QVL)
|
||
|
||
```janus
|
||
import libertaria.{qvl}
|
||
|
||
// Create hybrid graph (persistent + in-memory)
|
||
let graph = qvl.HybridGraph.init(&persistent, allocator)
|
||
|
||
// Add trust edges
|
||
graph.addEdge(.{
|
||
from = alice,
|
||
to = bob,
|
||
risk = -0.3, // Negative = trust
|
||
level = 3, // Trust level 1-7
|
||
timestamp = now(),
|
||
expires_at = now() + duration.days(30)
|
||
})
|
||
|
||
// Detect betrayal rings (negative cycles)
|
||
let result = try graph.detectBetrayal(alice)
|
||
if result.betrayal_cycles.items.len > 0 {
|
||
// Handle betrayal
|
||
}
|
||
|
||
// Find trust path
|
||
let path = try graph.findTrustPath(alice, charlie,
|
||
heuristic = qvl.reputationHeuristic,
|
||
heuristic_ctx = &rep_map)
|
||
```
|
||
|
||
### 3. GQL (Graph Query Language)
|
||
|
||
```janus
|
||
import libertaria.{gql}
|
||
|
||
// Parse GQL query
|
||
let query_str = "MATCH (n:Identity)-[t:TRUST]->(m) WHERE n.did = 'alice' RETURN m"
|
||
let query = try gql.parse(allocator, query_str)
|
||
defer query.deinit()
|
||
|
||
// Transpile to Zig code
|
||
let zig_code = try gql.generateZig(allocator, query)
|
||
defer allocator.free(zig_code)
|
||
|
||
// Generated code looks like:
|
||
// pub fn execute(graph: *qvl.HybridGraph) !void {
|
||
// // MATCH statement
|
||
// // Traverse from n
|
||
// var t = try graph.getOutgoing(n);
|
||
// // Filter by type: TRUST
|
||
// var m = t.to;
|
||
// // WHERE n.did == "alice"
|
||
// // RETURN statement
|
||
// var results = std.ArrayList(Result).init(allocator);
|
||
// defer results.deinit();
|
||
// try results.append(m);
|
||
// }
|
||
```
|
||
|
||
---
|
||
|
||
## Module Reference
|
||
|
||
### `libertaria.identity`
|
||
|
||
| Function | Purpose |
|
||
|----------|---------|
|
||
| `create()` | Generate new Ed25519 identity |
|
||
| `rotate(id)` | Rotate keys with provenance chain |
|
||
| `burn(id)` | Cryptographic deletion |
|
||
| `sign(id, msg)` | Sign message |
|
||
| `verify(id, msg, sig)` | Verify signature |
|
||
| `is_valid(id)` | Check not revoked/expired |
|
||
|
||
### `libertaria.qvl`
|
||
|
||
| Type | Purpose |
|
||
|------|---------|
|
||
| `HybridGraph` | Persistent + in-memory graph |
|
||
| `PersistentGraph` | libmdbx-backed storage |
|
||
| `RiskGraph` | In-memory graph for algorithms |
|
||
| `GraphTransaction` | Batch operations |
|
||
|
||
| Function | Purpose |
|
||
|----------|---------|
|
||
| `detectBetrayal(source)` | Bellman-Ford negative cycle detection |
|
||
| `findTrustPath(src, tgt, heuristic)` | A* pathfinding |
|
||
| `addEdge(edge)` | Add trust edge |
|
||
| `getOutgoing(node)` | Get neighbors |
|
||
|
||
### `libertaria.gql`
|
||
|
||
| Function | Purpose |
|
||
|----------|---------|
|
||
| `parse(allocator, query)` | Parse GQL string to AST |
|
||
| `generateZig(allocator, query)` | Transpile to Zig code |
|
||
|
||
---
|
||
|
||
## GQL Syntax
|
||
|
||
### MATCH — Pattern Matching
|
||
|
||
```gql
|
||
-- Simple node
|
||
MATCH (n:Identity)
|
||
|
||
-- Node with properties
|
||
MATCH (n:Identity {did: 'alice', active: true})
|
||
|
||
-- One-hop traversal
|
||
MATCH (a)-[t:TRUST]->(b)
|
||
|
||
-- Variable-length path
|
||
MATCH (a)-[t:TRUST*1..3]->(b)
|
||
|
||
-- With WHERE clause
|
||
MATCH (n:Identity)-[t:TRUST]->(m)
|
||
WHERE n.did = 'alice' AND t.level >= 3
|
||
RETURN m
|
||
```
|
||
|
||
### CREATE — Insert Data
|
||
|
||
```gql
|
||
-- Create node
|
||
CREATE (n:Identity {did: 'alice'})
|
||
|
||
-- Create edge
|
||
CREATE (a)-[t:TRUST {level: 3}]->(b)
|
||
|
||
-- Create pattern
|
||
CREATE (a:Identity)-[t:TRUST]->(b:Identity)
|
||
```
|
||
|
||
### DELETE — Remove Data
|
||
|
||
```gql
|
||
-- Delete nodes
|
||
MATCH (n:Identity)
|
||
WHERE n.did = 'compromised'
|
||
DELETE n
|
||
```
|
||
|
||
### RETURN — Project Results
|
||
|
||
```gql
|
||
-- Return variable
|
||
MATCH (n) RETURN n
|
||
|
||
-- Return multiple
|
||
MATCH (a)-[t]->(b) RETURN a, t, b
|
||
|
||
-- With alias
|
||
MATCH (n) RETURN n.did AS identity
|
||
|
||
-- Aggregations (planned)
|
||
MATCH (n) RETURN count(n) AS total
|
||
```
|
||
|
||
---
|
||
|
||
## Design Principles
|
||
|
||
### 1. Exit is Voice
|
||
|
||
Agents can leave, taking their data cryptographically:
|
||
|
||
```janus
|
||
// Burn identity
|
||
let burned = identity.burn(my_id)
|
||
// After burn: no new signatures possible
|
||
// Verification of historical signatures still works
|
||
```
|
||
|
||
### 2. Profit = Honesty
|
||
|
||
Economic stakes align incentives:
|
||
|
||
- **Posting** requires $SCRAP burn
|
||
- **Identity** requires $STASIS bond
|
||
- **Reputation** decays without verification
|
||
|
||
### 3. Code is Law
|
||
|
||
No central moderation, only protocol rules:
|
||
|
||
- **Betrayal detection** via Bellman-Ford (mathematical, not subjective)
|
||
- **Path verification** via cryptographic proofs
|
||
- **Reputation** via Bayesian updates
|
||
|
||
### 4. Kenya Compliance
|
||
|
||
Resource-constrained environments:
|
||
|
||
- **Binary size:** <200KB for L1
|
||
- **Memory:** <10MB for graph operations
|
||
- **Storage:** Single-file embedded (libmdbx)
|
||
- **No cloud calls:** Fully offline-capable
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
# Run all SDK tests
|
||
zig build test-qvl
|
||
|
||
# Run specific module
|
||
zig build test -- --module lexer
|
||
|
||
# Run with coverage (planned)
|
||
zig build test-qvl-coverage
|
||
```
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
### Sprint 0 ✅ — BDD Specifications
|
||
- 58 Gherkin scenarios for QVL
|
||
|
||
### Sprint 1 ✅ — Storage Layer
|
||
- libmdbx PersistentGraph
|
||
- HybridGraph (disk + memory)
|
||
|
||
### Sprint 2 ✅ — GQL Parser
|
||
- ISO/IEC 39075:2024 compliant
|
||
- Lexer, Parser, AST, Codegen
|
||
|
||
### Sprint 3 🔄 — Documentation
|
||
- API reference (this file)
|
||
- Architecture decision records
|
||
- Tutorial: Building your first agent
|
||
|
||
### Sprint 4 📅 — L4 Feed
|
||
- DuckDB integration
|
||
- LanceDB vector store
|
||
- Social media primitives
|
||
|
||
### Sprint 5 📅 — Production
|
||
- Performance benchmarks
|
||
- Security audit
|
||
- Release v1.0
|
||
|
||
---
|
||
|
||
## Related Projects
|
||
|
||
- [Janus Language](https://github.com/janus-lang/janus) — The foundation
|
||
- [Libertaria Stack](https://git.maiwald.work/Libertaria) — Full protocol implementation
|
||
- [Moltbook](https://moltbook.com) — Agent social network (lessons learned)
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT License + Libertaria Commons Clause
|
||
|
||
See LICENSE for details.
|
||
|
||
---
|
||
|
||
*Forge burns bright. The Exit is being built.*
|
||
|
||
⚡️
|