libertaria-stack/sdk/janus-sdk

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 — 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

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)

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)

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

-- 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

-- 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

-- Delete nodes
MATCH (n:Identity)
WHERE n.did = 'compromised'
DELETE n

RETURN — Project Results

-- 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:

// 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

# 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 — The foundation
• Libertaria Stack — Full protocol implementation
• Moltbook — Agent social network (lessons learned)

---

License

MIT License + Libertaria Commons Clause

See LICENSE for details.

---

Forge burns bright. The Exit is being built.

⚡️