INVARIANTS & ASSUMPTIONS — Unified Agent OS

INVARIANTS & ASSUMPTIONS — Unified Agent OS

---

Invariants (Must Never Be Violated)

### INV-1: Tenant Isolation
- Statement: No tenant can access another tenant's data, secrets, sessions, or compute
- Why: Trust is the product. A single leak destroys the business.
- What breaks: Customer trust, legal liability, SOC 2 compliance
- Canary: Cross-tenant query audit log; any query touching tenant_id != session.tenant_id triggers immediate alert

### INV-2: Model Provider Neutrality
- Statement: AgentOS must never hard-depend on a single LLM provider
- Why: Vendor lock-in kills adoption. Users switch models constantly.
- What breaks: Customer freedom, competitive positioning
- Canary: If removing any single provider's SDK breaks more than one subsystem, invariant is violated

### INV-3: API-First Surface
- Statement: Every user-facing feature must be accessible via API before (or simultaneously with) any UI
- Why: API-first ensures composability, testability, and third-party integration
- What breaks: Automation users can't access UI-only features; testing becomes browser-dependent
- Canary: UI PR without corresponding API endpoint = blocked

### INV-4: Session Cost Accountability
- Statement: Every token consumed must be attributed to a specific session, tenant, and budget
- Why: Cost transparency is a core value prop. Untracked spend erodes trust.
- What breaks: Billing accuracy, budget enforcement, cost optimization
- Canary: If `sum(session_costs)` diverges from `provider_invoice` by >2

### INV-5: Graceful Degradation
- Statement: Failure of any single subsystem (Pulse, Heartbeat, Dreams) must not crash the platform
- Why: Agents run 24/7; cascading failures are unacceptable
- What breaks: Platform uptime, customer operations
- Canary: Circuit breaker open for >5 minutes on any subsystem = P1 alert

### INV-6: Idempotent Operations
- Statement: All API mutations must be idempotent — retrying the same request produces the same result
- Why: Distributed systems lose messages; clients retry. Double-execution is data corruption.
- What breaks: Session duplication, double billing, state corruption
- Canary: Replay any API call 3x; assert identical state

### INV-7: Secrets Never in Logs
- Statement: API keys, tokens, credentials must never appear in logs, events, or error messages
- Why: Log aggregators are attack surfaces
- What breaks: Security posture, compliance
- Canary: Regex scan all log output for key patterns (sk-, api_, Bearer, etc.)

---

Assumptions (Could Be False)

### ASM-1: Multi-Model is Standard
- Statement: Most customers will use 2+ LLM providers simultaneously
- Breaks if false: Model routing layer is over-engineered; simplify to single-provider mode
- Detection: Usage analytics — if >80

### ASM-2: Developers are Primary Buyers
- Statement: First customers are developers/teams who already use AI agents, not enterprises doing greenfield
- Breaks if false: Onboarding flow needs more hand-holding; API-first is wrong priority
- Detection: Signup funnel analysis — if >50

### ASM-3: Pulse is the Primary Value Driver
- Statement: Autonomous task execution (Pulse) drives initial adoption; Heartbeat and Dreams are retention features
- Breaks if false: Restructure pricing — perhaps monitoring (Heartbeat) is the wedge
- Detection: Feature usage heat map at 90 days

### ASM-4: Skills Ecosystem Creates Lock-in
- Statement: A marketplace of shared skills creates network effects and switching costs
- Breaks if false: Skills are too niche; users prefer custom implementations
- Detection: Skill install rate, cross-tenant skill usage at 6 months

### ASM-5: Sub-5-Minute Onboarding is Achievable
- Statement: Signup → first running agent in <5 min is technically feasible
- Breaks if false: Requires pre-provisioned infrastructure per tenant (cost implications)
- Detection: P95 onboarding time measurement

### ASM-6: Open Core is the Right Model
- Statement: Core orchestration open-source attracts developers; premium features (multi-tenant, enterprise auth, SLA) drive revenue
- Breaks if false: Open core gets forked; premium features aren't compelling enough
- Detection: GitHub stars vs paid conversion at 12 months

---

Created: 2026-02-03 | Phase Zero