StateOS — Human Capability Platform

Core Rule: Technology must support human judgment rather than replace it.

StateOS is a privacy-first, calm human capability platform designed to strengthen human agency, attention, and autonomic self-regulation through real-time protocol execution.

Unlike traditional platforms designed to maximize engagement and screen time, StateOS operates under a "Calm Before Stimulation" visual and interaction model. It intercepts physiological stress cascades within the Recovery Window (0.5 to 4 seconds) to prevent external stressors from forcing the user into a reactive survival identity.

---

🏛️ Governance & Standards

StateOS code and data models derive directly from the Engineering Documentation Program (EDP):

• SOS-001: StateOS Constitution & Foundational Charter
• SOS-201: UX & Design System Engineering Manual
• SOS-301: AI & Intelligence Architecture Manual
• SOS-401: Software Engineering & State Engine Manual
• StateOS Domain Model (SDM) & stateos-pydantic-schemas.py

---

⚡ Tech Stack

Layer	Technology
Client Application	React Native (Expo) + TypeScript (Strict Mode)
State & Navigation	Zustand + React Navigation (8-Module Tab Shell + Stack)
Design System	SOS-201 W3C DTCG Tokens (Deep Obsidian #0A0A0B, Sovereign Gold #E2C48D, Coherence Cyan #88C3FF)
Local Database	SQLite via Drizzle ORM (expo-sqlite)
Schema Validation	Zod (client-side enforcement of ADR-MM-0009, 0010, 0011)
Haptic Feedback	expo-haptics

---

🗺️ Information Architecture & Navigation

The platform enforces the 3-Interaction Navigation Invariant (IA-SPEC-001): the user can reach and initiate any primary somatic protocol within at most 2 taps from the Home launchpad.

The 8 primary navigation modules are:

1. Home (/home) — Launchpad, daily state overview, AI recommendations, fast-access CTAs.
2. State (/state) — Real-time 250Hz autonomic telemetry (HRV, respiratory rate) & 6 capability domains.
3. Protocols (/protocols) — Categorized library of guided somatic interventions.
4. Journal (/journal) — Encrypted post-session reflections and observations.
5. Insights (/insights) — Recovery velocity trends and completion efficiency metrics.
6. AI Coach (/coach) — Conversational metacognitive co-pilot.
7. Profile (/profile) — Signature Identity statement, core values, identity anchors.
8. Settings (/settings) — Data encryption, zero-trust sovereignty, and Crypto-Tombstone controls.

---

🧘 Protocol Library & Player

Protocols are structured somatic micro-interventions organized across 8 core categories:

• Attention: e.g., Single-Point Focus Lock
• Recovery: e.g., Resonant Breathing (5.5 bpm pacing, 10.9s cycle per SOS-401 §3.3)
• Transition: e.g., Context Boundary Reset
• Preparation: e.g., Pre-Performance Prime
• Reflection: e.g., Daily State Review
• Learning: e.g., Somatic Concept Anchor
• Identity Reinforcement: e.g., Signature Identity Lock
• Performance: e.g., Peak State Activation

The Protocol Player (ProtocolPlayerScreen.tsx) features an animated visual breathing pacer, haptic cues, step-by-step sequence execution, and post-session reflection logging with 1–5 star efficacy scoring.

---

🔄 Deterministic Session FSM

Every somatic execution instance is governed by a 7-state non-deterministic transition matrix (ADR-MM-0010):

[CREATED] ──► [INITIATED] ──► [ACTIVE] ────► [COMPLETED] ──► [ARCHIVED]
                                │   ▲             │
                                ▼   │             ▼
                            [PAUSED] ───► [TIMED_OUT] ──► [ARCHIVED]

• Monotonic Optimistic Concurrency Control (INV-007): Every transition must increment version_id sequentially ($Version_{n+1} = Version_n + 1$).
• Illegal Transition Interception: Regressive pathways (e.g. COMPLETED → ACTIVE or ARCHIVED → ACTIVE) trigger a typed StateTransitionError.

---

🤖 AI Coach Subsystem & Guardrails

The AI Coach functions as a calm, non-authoritative systems co-pilot adhering strictly to SOS-301:

• 0.7 Confidence Gate: Recommendations with confidence $< 0.7$ automatically degrade to FALLBACK_NEUTRAL_INQUIRY with a null protocol URN.
• Non-Diagnostic Invariant (NDI-001): Intercepts clinical diagnostic terms (anxiety, depression, panic, adhd, clinical, disorder, diagnose).
• Agency Protection: Prohibits authoritative phrasing or automated decision-making on behalf of the user.

---

🔒 Privacy & Crypto-Tombstoning (ADR-MM-0009)

In compliance with zero-trust privacy:

• Personal data payloads are encrypted using AES-256-GCM with per-identity Data Encryption Keys (DEKs).
• Crypto-Tombstoning: Destroying the identity Key Encryption Key (KEK) irreversibly sets encrypted personal attributes to computational NULL while preserving system audit graph topology.

---

🚀 Getting Started

Prerequisites

• Node.js: v18+ (v25.6 tested)
• npm: v9+ (v11.8 tested)

Installation

cd stateos
npm install

Running the App

# Start Expo dev server
npm run start

# Run on Android
npm run android

# Run on iOS (macOS required)
npm run ios

---

🧪 Running Verification Tests

Run the complete engineering invariant test suite (Session FSM, OCC, AI Guardrails, Crypto-Tombstoning):

npx tsx tests/verify-stateos.ts

Expected Output:

--- Initiating StateOS Engineering Verification Suite ---

[1] Testing Session FSM Transition Matrix...
✅ PASS: Valid transition CREATED → INITIATED succeeded
✅ PASS: Valid transition INITIATED → ACTIVE succeeded
✅ PASS: Valid transition ACTIVE → PAUSED succeeded
...
✅ ALL STATEOS SPRINT 1 ENGINEERING INVARIANTS VERIFIED.

---

📜 Repository Compliance

To run the system-wide repository validator across documentation, schemas, and DDLs:

cd ../stateos-v1
$env:PYTHONIOENCODING="utf-8"
python stateos-validator-v2.py

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.