B2B Developer Specification

Jamii Sovereign OS
Core Architecture
& Subsystem Maps

A comprehensive technical reference detailing the spatial-semantic databases, cryptographic attestation pipelines, and localized governance loops powering the next generation of connected public safety and enterprise infrastructure.

The Unified Interoperability Stack

Jamii Sovereign OS replaces legacy point-to-point APIs with a three-layer high-assurance runtime stack. This architecture guarantees state persistence, real-time message routing, and strict policy boundary encapsulation.

OS Layer Hierarchy & Control Fabric

This structural map traces data processing from hardware node levels to AI orchestration interfaces.

TIER 3: SYSTEM INGRESS & APPS CNS Resolvers • Sourcing BFF • Mobile Jamii Online • MARS Dispatch Interfaces • Akili AI Agent Console TIER 2: GOVERNANCE & BLUEPRINT ENGINE Dynamic ABAC Scopes • Portfolios (Personal, Community, Org) • FSM Bindings • Access Leases • Policy Sweepers TIER 1: SPACIAL-SEMANTIC PERSISTENCE & CONTROL PLANE SurrealDB Spatial Core • NATS JetStream Event Fabric • Zero-Knowledge Vault Claims • HNSW Vector Indexes

The Fifteen Conceptual Primitives

Jamii Sovereign OS operates using modular primitives. Below is the detailed specification of each system, outlining its core capability and engineering responsibility.

1. Cryptographic Claims

An atomic, cryptographically verifiable unit of information or capability. A Claim represents assertions of truth (identity, certification, age, or physical telemetry right) that are digitally signed, audit-logged, and verified using zero-knowledge computations without disclosing raw data.

  • Verifiable credential format
  • PII-free metadata layers
  • Elliptic curve trust anchors

2. Information Vault (BYOV)

Under our "Bring Your Own Vault" (BYOV) model, each organization maintains absolute possession of their database files. The OS establishes a logical containment boundary, encrypting internal documents and claims, and exposes only specific, dynamic, and strictly scoped capabilities to the federated mesh.

  • Zero-trust database boundaries
  • Dynamic proximity-based access leases
  • Decoupled file/record containment

3. Spatial-Semantic Truth Graph

The structural spatial-semantic spine of the OS. Built as a combined SurrealDB graph and NATS outbox fabric, it maps all resources, actors, and claims as nodes and edges. It supports HNSW vector indexing for instant KNN searches and multi-hop spatial traversals to resolve permissions.

  • Canonical schema-level nodes/edges
  • HNSW vector index integration
  • SurrealQL traversal algorithms

4. Autonomous Service Discovery

Dynamic, decentralized microservice detection. Instead of central registry databases, services register interfaces within the Truth Graph. The OS queries semantic traits to automatically locate, verify, and routing traffic to nearby compatible endpoints in real-time.

  • CNS path resolution
  • Capability-based address binding
  • Automated cell proxy fallback

5. Scope-based Governance

Policy-driven access control. The governance engine enforces Attribute-Based Access Control (ABAC) rules across Personal, Community, and Organization Portfolios. It prevents nesting breaches via strict portfolio barriers and evaluates rules dynamically in millisecond runtimes.

  • ABAC policy evaluation loops
  • is_portfolio boundary validation
  • Temporal lease revocations

6. Interface Contracts

Declarative operational contracts. These guarantee that any connecting device or legacy database complies with the explicit CNS schemas. The OS dynamically enforces contract rules at compilation and ingress, rejecting non-compliant payload structures instantly.

  • Strict JSON Schema verification
  • CNS signature compliance
  • Versioned contract updates

7. Event Feeds

High-throughput telemetry streams powered by NATS JetStream. Feeds deliver structured event paths across the system. It uses an active outbox queue design to process mutations, retry deliveries, and preserve order during network partitioning.

  • Durable pull-consumer queues
  • Telemetry stream synchronization
  • Publish retry/dead-letter rules

8. Cryptographic Data Sets

Curated, signed collections of static or slow-changing information. Data Sets are stored in distributed nodes, signed by organizing authorities, and used by offline systems to verify regulatory boundaries without an active internet path.

  • Signed static snapshot archives
  • Delta sync packet transfer
  • Offline database integrity

9. Cell Manifests

Self-describing configurations that represent cell boundaries. Manifests catalog the cell topology, available subsystems, interface versions, and dynamic network routing paths, giving administrative engines a complete map of the local deployment state.

  • Self-documenting profile structures
  • Local cell mesh routing maps
  • Automated deployment bootstrapping

10. Finite State Machines (FSM)

Long-running workflow engines. FSMs track resource lifecycle stages (e.g. from Emergency Incident Received $\rightarrow$ Unit Assigned $\rightarrow$ Patient Checked $\rightarrow$ Dispatched). State transitions require strict cryptographic proofs and trigger dynamic event outcomes.

  • Persistent resource-state bindings
  • Offline state queue hydration
  • Compliance transition verification

11. Client Verticals

The primary industry applications deployed on the spine: Jamii Online (Community Portal & Estate Management), MARS (Multi-Agency Emergency Response System), IoT Grid (Smart City Water/Energy), and AfiyaLink (Zero-Knowledge Clinical Health).

  • MARS dispatch & location routing
  • AfiyaLink medical record isolation
  • Jamii Online neighborhood forums

12. Truth Tokenization

Converting verified cryptographic claims into tokenized assets. The OS provides the ability to package attestation chains into quantifiable digital tokens—allowing partners to mint reputation metrics, carbon credits, or auditable compliance points directly.

  • Verifiable reputation metrics
  • Compliance ledger packaging
  • Dynamic value exchanges

13. Cell Federation

Decentralized mesh networks connecting independent operating cells. Each cell runs a dedicated instance of the spatial-semantic database. Cells negotiate peer-to-peer relationships using federated registries, avoiding dangerous distributed SQL locks.

  • Dedicated local database instances
  • P2P proxy route resolution
  • No-lock cross-cell SQL queries

14. HITL Orchestration

Manual override and verification systems. When automated state transition checks fail or dynamic ABAC policies require subjective consensus, the system triggers audits and task callouts, pausing FSM workflows until validated by certified human operators.

  • Dynamic callback sweep registers
  • Human verification callout routing
  • Graceful automated failure recovery

15. Encrypted Queries

Organizations can publish cryptographic queries directly against their data. Third-party auditors or sister agencies execute these queries to prove compliance (e.g. "Does patient X hold a valid medical license?") without exposing raw rows.

  • Cryptographic validation outputs
  • Granular, schema-based data gates
  • Audit trails for third-party queries

Cryptographic Claims & BYOV Attestation Pipeline

Claims represent the atomic operational units of truth in the OS. This sequence diagram illustrates how local tenant data is signed, protected within the Information Vault boundary, and registered as a semantic edge in the Truth Graph.

BYOV Claims Ingress & Verification Pipeline

Tracing payload encryption, ZK tokenization, and Truth Graph node registration.

Tenant Data (BYOV) Attestation Engine Truth Graph Registry 1. Push Raw Claim Payload 2. Encrypt & Generate ZK Token 3. File CNS Node & Edges 4. Dynamic Attestation Confirmed (Spatial Proximity Lease Active)

The Spatial-Semantic Truth Graph Mesh

Everything inside Jamii Sovereign OS maps to nodes and edges. The Truth Graph topology represents a fluid spatial-semantic mesh that connects local resources and maps federated cell-to-cell relationships.

SCPF Spatial-Semantic Graph Topology

A visual map of CNS domain names, HNSW vector networks, and federated peer-cell bridges.

cns://met/temp cns://afiya/chart cns://mars/unit Federated Cell inherits triggers coordinates federates federates

Developer Deep Dives

Understanding the unique Object-Oriented patterns, long-running workflow designs, and self-describing schemas of Jamii Sovereign OS.

Decentralized, OOP-Based Governance

Rather than managing authorization inside a centralized registry, Jamii models its entire governance stack using Object-Oriented Programming (OOP) Primitives. Portfolios and Vaults serve as strict encapsulation contexts, hiding raw relational tables behind standard interface schemas.

By utilizing dynamic containment edges in the Truth Graph, resources dynamically inherit capabilities from parent folders. When a new entity is created, setting its sharing_policy="inherited" automatically propagates permissions downwards using containment triggers. Heterogeneous subsystems (a smart meter, a clinical clinic, or an ambulance) represent polymorphic interfaces. Developers manage capabilities across diverse resources using identical, standardized patterns, ensuring seamless API integrations.

Decoupled FSMs & Self-Describing AI Engines

Real-world systems operate on multi-year, long-running timelines. Our Finite State Machines (FSM) are decoupled from execution threads and saved directly as resource bindings (create_fsm_binding and update_fsm_state). Transitions are driven by NATS outboxes; if a field station is offline, the state is persisted and hydrated asynchronously on reconnection. Periodic sweepers (governance::sweep_platform) evaluate constraints and raise alerts only when compliance thresholds or SLAs are broken.

For AI agent orchestration, the platform is entirely self-describing. Using machine-readable manifests and canonical naming standards (cns://), AI agents like the Akili Engine can introspect, discover CNS interface contracts, and execute secure actions dynamically. They don't need hardcoded integrations; they navigate the Truth Graph autonomously on behalf of users.

Secure User-Published Encrypted Queries

Siloed databases usually force companies to choosing between total isolation or massive, high-risk data integration pipelines. Jamii Sovereign OS provides a unique third way: User-Published Encrypted Queries.

Organizations publish custom, encrypted query schemas to the Truth Graph. Sister agencies or third-party auditors execute these specific queries against the Vault boundary. The Vault runs the query locally and returns a signed cryptographic proof (e.g. validating "License status is ACTIVE" or "Carbon emission is within zone thresholds") without disclosing a single raw relational row to the caller. This ensures complete sovereign audit compliance with zero exposure of proprietary client databases.