Architecture Overview¶

Adaptive Sentience is an offline-capable workflow execution substrate designed for distributed field operations where connectivity is unreliable and security is critical.

Core Principles¶

1. Offline-First Operation¶

Problem: Field operations often lack reliable connectivity.

Solution: Store-and-forward architecture with local execution and opportunistic sync.

Requests queue when nodes are offline
Automatic delivery when connectivity returns
No data loss during network outages

2. Zero-Trust Security¶

Problem: Traditional network security fails in dynamic, untrusted environments.

Solution: Capability-based authorization at every layer.

No network-level trust assumptions
Cryptographic node pairing (TOFU or PKI)
Capability tokens enforce least-privilege access
Full execution audit trails

3. Edge-First Execution¶

Problem: Cloud dependencies create latency and availability risks.

Solution: Computation happens at the edge, closest to data sources.

Tools execute on edge nodes (phones, laptops, IoT devices)
Gateway orchestrates without executing
Scales horizontally by adding nodes

System Architecture¶

┌─────────────────────────────────────────────────────────┐
│                   External Clients                       │
│  (LLM Agents, Web Apps, Mobile Apps, API Consumers)     │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/JSON-RPC
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   HTTP Gateway                           │
│  • Request routing & queuing                            │
│  • Policy enforcement                                    │
│  • Multi-node orchestration                             │
└────────────────────┬────────────────────────────────────┘
                     │ Mesh Transport (UDP multicast)
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Edge Nodes                            │
│  (Laptops, Android Devices, Raspberry Pi, Servers)      │
│  • Tool execution                                        │
│  • Capability enforcement                                │
│  • Execution evidence generation                         │
└─────────────────────────────────────────────────────────┘

Key Components¶

Gateway¶

Role: Orchestrator and request router

Responsibilities: - Accept workflow requests via HTTP API - Route requests to appropriate edge nodes - Queue requests when nodes are offline - Aggregate results from multi-node workflows - Provide MCP server for AI assistant integration

Does NOT: - Execute tools (that's the edge nodes' job) - Store sensitive data long-term - Make trust decisions (nodes validate independently)

Edge Nodes¶

Role: Tool execution environment

Responsibilities: - Register available tools with the gateway - Execute tools in sandboxed environment - Validate capability tokens before execution - Generate cryptographic execution evidence - Handle offline operation gracefully

Types: - Desktop/Laptop: Development, field command centers - Mobile (Android): Field data collection, sensors - Raspberry Pi: Fixed sensors, remote monitoring - IoT Devices: Specialized sensors and actuators

Tool Contracts¶

Role: Formal interface definitions

Tools are defined with JSON schemas:

{
  "tool_id": "tool:pii_redact",
  "name": "pii_redact",
  "version": "1.0.0",
  "input_schema": { "type": "object", ... },
  "output_schema": { "type": "object", ... },
  "required_capabilities": ["tool:pii_redact"],
  "deterministic": true
}

Benefits: - Type-safe tool invocation - Version-aware execution - Automatic validation - Clear API contracts

Mesh Transport¶

Role: Node discovery and communication

How it works: 1. Edge nodes broadcast presence via UDP multicast 2. Gateway discovers nodes and caches topology 3. Requests route via HTTP to specific nodes 4. Results return via HTTP response

Features: - Automatic node discovery (no manual configuration) - Graceful handling of node churn - Fallback to manual targeting if multicast unavailable

Request Flow¶

1. Client Submits Workflow¶

POST /v1/tool_call
{
  "target": { "kind": "local" },
  "tool_name": "pii_redact",
  "tool_args": { "text": "Contact john@example.com" },
  "token": { "capabilities": ["tool:pii_redact"] }
}

2. Gateway Routes Request¶

Checks which nodes have the required tool
Selects node(s) based on target criteria
Queues if no suitable nodes online
Sends request via HTTP to chosen node

3. Edge Node Executes¶

Validates capability token
Checks tool exists locally
Validates input schema
Executes tool in sandbox
Generates execution evidence
Returns signed result

4. Gateway Returns Result¶

{
  "ok": true,
  "verified": true,
  "result": {
    "redacted_text": "Contact [REDACTED]",
    "redactions": [{"type": "email", "start": 8, "end": 25}]
  },
  "execution_path": ["local:abc123"],
  "degraded": false
}

Security Model¶

Capability Tokens¶

Instead of "user X can do Y," capabilities say "this token grants permission to do Y."

Example:

token = {
    "capabilities": [
        "tool:pii_redact",
        "tool:summarize"
    ],
    "expires": "2024-12-31T23:59:59Z"  # Optional
}

Edge nodes reject requests lacking required capabilities.

Node Pairing¶

Two modes:

TOFU (Trust On First Use): Automatically trust first contact
Good for development and trusted networks
Simple, zero-config
PKI (Public Key Infrastructure): Explicit key exchange
Good for production and untrusted networks
Requires manual pairing or certificate authority

Execution Evidence¶

Every tool execution generates: - Trace ID: Unique identifier - Execution path: Which nodes handled the request - Signatures: Cryptographic proof from executing nodes - Timestamps: When execution occurred - Result hash: Tamper detection

This evidence supports: - Audit compliance - Debugging failed workflows - Performance analysis - Incident investigation

Deployment Models¶

1. Development¶

Single laptop runs gateway + edge node
Dev token mode (no real auth)
Useful for testing and tool development

2. Small Team¶

One gateway (cloud or on-premise)
Multiple edge nodes (team laptops + mobile)
TOFU pairing for simplicity
Shared capability tokens

3. Enterprise¶

Multiple gateways (HA + geo-distributed)
Hundreds of edge nodes across field sites
PKI-based pairing with certificate authority
Fine-grained capability tokens per role
Full audit logging to SIEM

4. Air-Gapped¶

Gateway runs on isolated network
Edge nodes never touch internet
Synchronization via physical media or one-way data diodes
Maximum security for classified operations

Comparison to Alternatives¶

vs. Traditional RPC (gRPC, HTTP)¶

Feature	Adaptive Sentience	Traditional RPC
Offline support	✅ Store-and-forward	❌ Fails immediately
Discovery	✅ Automatic	❌ Manual config
Authorization	✅ Capability-based	⚠️ User/role-based
Execution evidence	✅ Built-in	❌ Roll your own
Multi-node	✅ Native	❌ Complex orchestration

vs. Message Queues (RabbitMQ, Kafka)¶

Feature	Adaptive Sentience	Message Queues
Tool contracts	✅ Built-in	❌ Manual
Edge execution	✅ Native	❌ Requires workers
Offline nodes	✅ Mailbox per node	⚠️ Requires broker
Mobile support	✅ Android app	❌ Complex setup

vs. FaaS (AWS Lambda, Cloud Functions)¶

Feature	Adaptive Sentience	FaaS
Offline	✅ Edge-first	❌ Cloud-only
Cost	✅ Self-hosted	💰 Per-invocation
Latency	✅ Local execution	⚠️ Network RTT
Data sovereignty	✅ Stay on-premise	❌ Cloud egress

Next Steps¶

Tool Contracts - Define custom tools
Capability Tokens - Authorization deep dive
Trust & Pairing - Secure node communication
Execution Evidence - Audit and compliance
Offline Operation - Store-and-forward details