Metadata-Version: 2.4
Name: stratum-lang
Version: 1.0.1
Summary: An AI-first, secure-by-construction programming language and hardened runtime, compiled to WebAssembly
Author-email: Alexander Kalyniuk <alex-kalyniuk@fsmelogic.ca>
License: MIT
Project-URL: Homepage, https://fsmelogic.ca
Project-URL: Documentation, https://fsmelogic.ca
Keywords: wasm,webassembly,wasmtime,anomaly detection,secure programming,language,compiler,actor model,edge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wasmtime>=28.0.0
Dynamic: license-file

# Stratum

**An AI-first, secure-by-construction programming language that compiles to a single self-contained WebAssembly module.**

Stratum is a statically typed, actor-based language designed so that whole classes of failure are prevented by the execution model rather than caught after the fact. Actors are isolated with no shared mutable state, effects are capability-narrowed on every operation, and an anomaly detector is built in. The same program runs bit-for-bit identically on a reference engine and a WebAssembly engine, so what you test is what you ship.

Because the whole language is described in one context pack (see `LLM_CONTEXT_PACK.md`), you can paste that pack into any capable LLM and have it write correct Stratum with no prior training on the language. That is the point: AI-generated code you can trust because the runtime, not the model, enforces the guarantees.

This package is **Stratum Basic** — the free, open-source (MIT) tier. It contains the full language, both execution engines (AST reference + WebAssembly), the capability security model, and the open-core anomaly detector.

## Install

```bash
pip install stratum-lang
```

One install works on Windows, macOS, and Linux (pure Python + `wasmtime`).

## Your first program

Save this as `hello.st`:

```stratum
module hello;

fn main() -> Unit effects [console] do
    let a = 5;
    let b = 3;
    print("Sum:", a + b);
    ()
end fn
```

Run it:

```bash
stratum --grant console hello.st
```

## Run on either engine

The same source runs byte-identically on the AST reference engine and the WebAssembly engine:

```bash
stratum --grant console --engine=ast  hello.st
stratum --grant console --engine=wasm hello.st
```

## Capabilities

Stratum has no ambient authority. A program can only do what you grant it on the command line with `--grant`, and every function must declare the effects it uses.

| Capability | Unlocks |
|---|---|
| `console` | `print` |
| `clock` | `now`, `sleep_ms` |
| `randomness` | `random_float`, `random_gauss`, `random_seed` |
| `entropic` | `monitor` (feed the anomaly detector) |
| `self_heal` | `flush`, `mailbox_size`, `snapshot`, `revert` |
| `concurrency` | `spawn`, `send` |
| `introspect` | `describe`, `internal_health` |

## A secure actor with anomaly detection

```stratum
module sensor_demo;

actor Sensor do
    state count: Int = 0;
    state alarmed: Bool = false;

    quarantine on alarmed;              // while `alarmed`, non-privileged msgs drop

    handle Reading(v: Float) effects [entropic] do
        count = count + 1;
        monitor(v);                     // feed the value to the anomaly detector
    end handle

    privileged handle OnPhaseTransition(event: PhaseEvent) effects [console, self_heal] do
        if event.phase == "red" do
            print("anomaly at reading", count);
            let dropped = flush();      // neutralize the message flood
            alarmed = true;             // quarantine self
        end if
    end handle
end actor

fn main() -> Unit effects [console, entropic, randomness, self_heal, concurrency] do
    random_seed(7);
    let s = spawn Sensor;
    let i = 0;
    while i < 60 do
        s.Reading(1.0 + random_gauss(0.0, 0.05));   // steady
        i = i + 1;
    end while
    let j = 0;
    while j < 120 do
        s.Reading(50.0 + random_gauss(0.0, 3.0));   // anomaly burst
        j = j + 1;
    end while
    ()
end fn
```

```bash
stratum --grant console,entropic,randomness,self_heal,concurrency sensor_demo.st
```

## The language in one screen

- Every block closes with a labeled terminator: `end fn`, `end actor`, `end handle`, `end if`, `end while`, `end match`.
- Static types; `Int` and `Float` never mix implicitly (`to_float`/`to_int` to convert).
- No null: use `Optional<T>` with `Some(v)`/`None`, read only by `match`.
- Functions declare their effects: `fn f(x: Int) -> Int effects [console] do ... end fn`.
- Contracts: `requires`/`ensures` runtime-checked pre/postconditions.
- Pattern matching with `match`/`when`, and cross-file modules with a capability ceiling.

Full grammar and more examples are in `GRAMMAR.md` and the `examples/` directory. There is also a self-contained context pack you can paste into any capable LLM so it writes correct Stratum without training data.

## Compile to a standalone `.wasm`

```bash
stratum --emit-wasm=myprog.wasm myprog.st
```

This writes a standalone WebAssembly module plus a sidecar manifest describing the host-import contract and memory layout, so you can embed the module in any host language.

## Editions and support

Stratum Basic is free, MIT-licensed, and the complete language, not a crippled demo. Commercial licensing, support, and editions for production use are available at [fsmelogic.ca](https://fsmelogic.ca).

Stratum is built and maintained by a solo founder (FSME Logic). It is early and under active development. Issues and questions are welcome; please be patient with response times.

## License

MIT. See `LICENSE`.
