From ff40f3739c6a3c263a72e85ff48967bdd4d5dc3a Mon Sep 17 00:00:00 2001 From: Markus Maiwald Date: Tue, 3 Feb 2026 12:52:41 +0100 Subject: [PATCH] docs(sdk): add comprehensive Janus SDK documentation Add README.md with: - Architecture overview with diagram - Quick start examples (Identity, QVL, GQL) - Module reference for all public APIs - GQL syntax guide (MATCH, CREATE, DELETE, RETURN) - Design principles (Exit is Voice, Profit=Honesty, etc.) - Testing instructions - Sprint roadmap Covers Sprint 3: Documentation --- janus-sdk/README.md | 373 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 314 insertions(+), 59 deletions(-) diff --git a/janus-sdk/README.md b/janus-sdk/README.md index 93e2931..36fdc9c 100644 --- a/janus-sdk/README.md +++ b/janus-sdk/README.md @@ -2,81 +2,336 @@ > Sovereign; Kinetic; Anti-Fragile. -The Libertaria SDK provides primitives for building sovereign agent networks on top of Janus. +**Version:** 0.2.0-alpha +**Status:** Sprint 2 Complete (GQL Parser + Codegen) +**License:** MIT + Libertaria Commons Clause -**Status:** v0.1.0-alpha (2026-02-03) +--- -## Core Modules +## Overview -| Module | File | Status | Purpose | -|--------|------|--------|---------| -| `identity` | `identity.jan` | ✅ Draft | Cryptographic agent identity with rotation/burn | -| `message` | `message.jan` | ✅ Draft | Signed, content-addressed messages | -| `context` | `context.jan` | ✅ Draft | NCP (Nexus Context Protocol) implementation | -| `memory` | `memory.jan` | ✅ Draft | Vector-backed semantic memory (LanceDB) | -| `lib` | `lib.jan` | ✅ Draft | Unified API export | +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. -## Quick Start +This SDK implements the **L1 Identity Layer** of the Libertaria Stack, featuring: -```janus -import libertaria +- **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) --- Create sovereign agent -let agent = libertaria.create_sovereign_agent() - --- Create identity with rotation capability -let (new_id, old_id) = identity.rotate(agent.identity) - --- Send signed message -let msg = message.create( - from = agent.identity, - content_type = Text, - content = bytes.from_string("Hello Sovereigns!") -) - --- Create hierarchical context -let ctx = context.create({}) -let sub_ctx = context.fork(ctx, reason = "Sub-conversation")? - --- Store in semantic memory -let emb = memory.embed(message.content(msg)) -let vs = memory.store(agent.memory, message.id(msg), emb, "...") -``` - -## Design Principles - -1. **Exit is Voice** — Agents can leave, taking their data cryptographically (`identity.burn`) -2. **Profit = Honesty** — Economic stakes align incentives (staking module planned) -3. **Code is Law** — No central moderation, only protocol rules -4. **Binary APIs** — gRPC/MsgPack/QUIC over REST +--- ## Architecture ``` -┌─────────────────────────────────────────────┐ -│ Libertaria SDK │ -├──────────┬──────────┬──────────┬────────────┤ -│ Identity │ Message │ Context │ Memory │ -│ │ │ (NCP) │ (LanceDB) │ -├──────────┴──────────┴──────────┴────────────┤ -│ Janus Standard Library │ -├─────────────────────────────────────────────┤ -│ Janus Compiler (:service) │ -└─────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────┐ +│ 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) │ +└─────────────────────────────────────────────────────────────┘ ``` -## Next Steps +--- -- [ ] Staking/Economics module (spam prevention) -- [ ] Channel module (QUIC transport) -- [ ] Discovery module (DHT-based agent lookup) -- [ ] Governance module (voting, proposals) -- [ ] Test suite -- [ ] Integration with Janus compiler +## 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 + Libertaria Commons Clause +MIT License + Libertaria Commons Clause + +See LICENSE for details. + +--- *Forge burns bright. The Exit is being built.*