soma

The problem

A quantitative fund today needs Python + Pandas + Redis + PostgreSQL + Kafka + Flask + React + Celery + Airflow + Terraform. Ten tools, five languages, three teams. Fifty thousand lines of glue code. The specification lives in Confluence. The code lives somewhere else. They drift apart.

An AI agent can write a function. Maybe a file. But it cannot write a system — services that coordinate, maintain state, handle failures, and evolve. The gap is not intelligence. The gap is that programming languages separate intent from infrastructure, specification from implementation, contract from code.

Soma closes that gap.

memory {
    orders:   Map<String, Order>   [persistent, consistent]     // → SQLite
    cache:    Map<String, Price>   [ephemeral, local]          // → in-memory HashMap
    audit:    Log<Event>           [persistent]               // → SQLite (WAL mode)
}

// Two independent programs, connected via soma.toml

// exchange/app.cell
cell Exchange {
    on order(data: Map) { place_order(data) }
    every 500ms { signal trade(match_orders()) }
}

// trader/app.cell
cell Trader {
    every 3s { signal order(quote) }
    on trade(fill: Map) { record_fill(fill) }
}

// trader/soma.toml: [peers] exchange = "localhost:8082"

Contracts are enforced

The face section is not documentation. It is a machine-checked contract. The compiler verifies it. Break the contract — the program does not compile.

cell API {
    face {
        signal create(name: String) -> Map
        signal delete(id: String)            // ← declared but no handler
        promise all_persistent
    }
    on create(name: String) { return map("name", name) }
}

error: face contract: signal 'delete' declared in cell 'API' has no handler
→ Every signal in the face MUST have a matching on handler.
→ Param counts are verified. Contradictory properties are rejected.
→ Descriptive promises generate warnings. Structural promises are enforced.

This is what separates Soma from every other dynamic language. The face is a structural contract: it declares what signals the cell handles, and the compiler verifies the cell implements them. Signal existence, parameter counts, property contradictions, and structural promises are all checked at compile time. Return types and runtime invariants are not yet verified.

Formal verification

soma verify is a model checker. It exhaustively explores every reachable state in your state machine and proves temporal properties. Not testing — proving.

state order {
    initial: pending
    pending → validated
    validated → sent
    sent → filled
    sent → rejected
    filled → settled
    * → cancelled
}

[verify]
deadlock_free = true
eventually = ["settled", "cancelled"]
never = ["invalid"]

[verify.after.sent]
eventually = ["filled", "rejected"]

[verify.after.pending]
eventually = ["validated", "cancelled"]

$ soma verify app.cell

State machine 'order': 7 states, initial 'pending'

  ✓ 7 states, 11 transitions
  ✓ all states reachable from 'pending'
  ✓ no deadlocks
  ✓ liveness: every state can eventually reach a terminal state

  Temporal properties:
  ✓ deadlock_free
  ✓ eventually(settled or cancelled)
  ✓ never(invalid)
  ✓ after('pending', validated or cancelled)
  ✗ after('sent', filled or rejected)
    counter-example: pending → validated → sent → cancelled
    → The wildcard * → cancelled bypasses the expected filled/rejected

The model checker found a real bug: after sent, the spec requires the order to reach filled or rejected. But the wildcard * → cancelled allows skipping directly to cancelled — violating the spec. The counter-example shows the exact execution path.

This is bounded model checking inspired by CTL temporal logic. It exhaustively explores finite state machine graphs — not data values or guard expressions. For small state machines (5–15 states), the verification is instant and complete. The spec lives in soma.toml, the implementation lives in .cell, and the proof is one command: soma verify.

Intellectual foundations

Soma is not invented from nothing. It stands on decades of research in programming language theory, distributed systems, and formal methods.

Errors that help

Inspired by Elm and Rust. Every error shows the source line, points to the exact expression, and suggests a fix.

error: expected '=', found number '10'
  --> app.cell:3:15
  |
3 |         let x 10
  |               ^

error: cannot add String and Int: hello + 5
  --> app.cell:7:17
  |
7 |         let r = "hello" + 5
  |                 ^

error: undefined function: langth (did you mean 'length'?)
  --> app.cell:4:9

error: face contract: signal 'delete' declared in cell 'API' has no handler
  → The face is a contract. Break it, and the compiler tells you.

What one Soma program replaces

8 tools
4 languages
50,000 lines of glue
Specification: Confluence
Implementation: somewhere else

1 language
1 file (or a few)
1 command: soma serve
~300 lines
The spec IS the program

The language

Soma has one structure: the cell. Face (contract), memory (state), state machines (protocol), signal handlers (behavior). Everything is a cell, from a function to a datacenter.

Match expressions

on request(method: String, path: String, body: String) {
    match path {
        "/"              → html(dashboard())
        "/api/portfolio" → get_portfolio()
        "/api/risk"      → risk_report()
        _                → response(404, map("error", "not found"))
    }
}

Lambdas + higher-order pipes

let portfolio = stocks
    |> filter(s => s.market_cap > 1e9)
    |> map(s => score(s))
    |> sort_by("alpha", "desc")
    |> top(15)

let names = users |> map(u => u.name) |> join(", ")
let active = users |> filter(u => u.status == "active")
let found = users |> find(u => u.id == target)
let valid = orders |> all(o => o.total > 0)

Multi-line strings

let html = """
<div class="card">
    <h2>{stock.ticker}</h2>
    <p class="price">${stock.price}</p>
    <span class="change {cls}">{stock.momentum}%</span>
</div>
"""

State machines

state order {
    initial: pending
    pending → validated { guard { risk_check_passed } }
    validated → sent
    sent → filled
    sent → rejected
    filled → settled
    * → cancelled
}

// Runtime enforces: you cannot reach 'sent' without passing 'validated'.
// The auditor reads the .cell file and sees the policy.
// The policy IS the code.

Declarative storage

memory {
    data:     Map<String, String> [persistent, consistent]     // → SQLite
    cache:    Map<String, String> [ephemeral, local]          // → in-memory
    sessions: Map<String, String> [ephemeral, ttl(30min)]    // → auto-expire
}

// The compiler verifies: [persistent, ephemeral] → contradiction.
// Properties are defined in .cell files. The language grows itself.

Types & variables

let x = 42                             // Int
let price = 3.14                       // Float
let sci = 1.5e3                        // Scientific: 1500.0
let name = "world"                     // String with {interpolation}
let user = User { name: "Alice", age: 30 }  // Typed record
let dur = 5s                            // Duration → 5000ms

for i in range(0, 10) { /* ... */ }   // range, break, continue
while running { if done { break } }   // loops

Self-growing language

// Properties, checkers, and backends are .cell files, not compiler code.

cell property geo_replicated {
    rules {
        implies [persistent, consistent]
        contradicts [ephemeral, local]
    }
}

cell backend redis {
    rules {
        matches [ephemeral, ttl]
        native "redis"
    }
}

// Add geo_replicated to your memory — the compiler now checks it.
// Add a redis backend — the runtime now resolves to it.
// No compiler changes needed. The language grew.

Data pipelines

Soma replaces Pandas for in-memory analytics. Same operations, fraction of the code. Every pipeline is composable via |>.

Pipeline operators

Real example: portfolio construction

let portfolio = universe()
    |> filter(s => s.market_cap > 1e9)
    |> map(s => score(s))
    |> sort_by("composite", "desc")
    |> top(15)
    |> map(s => {
        let weight = clamp(s.composite * exposure / total, 0, 15)
        s |> with("weight", weight)
    })

Web applications

soma serve app.cell — threaded HTTP server, SQLite, CORS, auto-routing, HTML templates. Zero framework.

cell App {
    memory { tasks: Map<String, String> [persistent, consistent] }

    on request(method: String, path: String, body: String) {
        match path {
            "/"     → html(dashboard())
            "/api"  → tasks.values() |> map(s => from_json(s))
            _       → response(404, map("error", "not found"))
        }
    }

    on dashboard() {
        let rows = tasks.values()
            |> map(s => from_json(s))
            |> map(t => """<tr><td>{t.name}</td><td>{t.status}</td></tr>""")
            |> join("")
        return """
        <html>
            <body>
                <h1>Tasks</h1>
                <table>{rows}</table>
            </body>
        </html>
        """
    }
}

// $ soma serve app.cell
// listening on http://localhost:8080

Inter-process signals

Independent Soma programs communicate via signals. No WebSocket code. No HTTP polling. No serialization. signal to send, on to receive. Peers declared in soma.toml. Zero transport code in your program.

cell Exchange {
    on order(data: Map) {
        place_order(data)
    }

    every 500ms {
        let fill = match_orders()
        signal trade(fill)
    }
}

cell Trader {
    every 3s {
        signal order(data)
    }

    on trade(fill: Map) {
        record_fill(fill)
    }
}

// soma.toml
// [peers]
// exchange = "localhost:8082"

The exchange emits signal trade(fill). The trader's on trade(fill) fires automatically. Two independent processes. No shared code. No ws_connect, no http_get, no to_json. The signal is the transport.

Peers are declared in soma.toml, not in code. Change the address — zero code changes. Replace TCP with Kafka — zero code changes. The program contains logic. The configuration contains topology.

// soma.toml — topology is configuration, not code
[package]
name = "trader"

[peers]
exchange = "localhost:8082"    // auto-connects on soma serve startup
risk = "localhost:7082"        // add more peers — no code changes

Three transports, one keyword

signal trade(fill) delivers to all listeners: browsers via SSE, programs via TCP bus, WebSocket clients. Same keyword, runtime resolves the transport.

signal trade(fill)     // one emit → three transports:
                       //   → SSE: browser EventSource('/stream')
                       //   → TCP bus: connected peers (soma.toml)
                       //   → WS: WebSocket clients on :8081

Built with Soma

CLI reference

Architecture

Source (.cell)
    → Lexer → Parser → AST
        → Checker (properties, signals, promises)
        → Interpreter (soma run)
        → Bytecode VM (soma run --jit)
    → Registry (stdlib/*.cell — properties, backends, builtins)
    → Runtime
        → Storage (SQLite | Memory | HTTP Provider)
        → HTTP server (soma serve)
        → SSE streaming (real-time browser push)
        → WebSocket server (bidirectional)
        → TCP signal bus (inter-process signals)