Strata

Strata is an experimental systems language for explicit authority, typed concurrency, and runtime-visible execution.

Mantle is the runtime target for Strata programs. Strata source files are written as .str; the compiler builds language-neutral Mantle Target Artifacts as .mta; Mantle validates and executes those artifacts.

The shape is deliberate: Strata should make effects, authority, process behavior, determinism, and communication protocols visible in the program text and checkable before execution. Mantle should execute only what the artifact is allowed to do, and it should leave an observability trail that can be inspected after the run.

Runnable Gates

The first source-to-runtime gate:

cargo build
cargo run -p strata --bin strata -- check examples/hello.str
cargo run -p strata --bin strata -- build examples/hello.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/hello.mta

The example program emits hello from Strata through an explicit emit effect. Mantle prints the emitted output and records the runtime events in:

target/strata/hello.observability.jsonl

This slice is a source-to-runtime slice, not a complete language or release-ready runtime: a real .str file can be checked, built into .mta, and executed by Mantle.

The actor/runtime gate:

cargo run -p strata --bin strata -- check examples/actor_ping.str
cargo run -p strata --bin strata -- build examples/actor_ping.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_ping.mta

That example spawns a worker process, sends it a message, handles the message, updates worker state, terminates both processes normally, and records the runtime trace at:

target/strata/actor_ping.observability.jsonl

Multi-step immutable actor execution uses message-keyed process transitions:

cargo run -p strata --bin strata -- check examples/actor_sequence.str
cargo run -p strata --bin strata -- build examples/actor_sequence.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_sequence.mta

That example sends two messages to a worker. The worker handles the first message, returns a whole replacement state with Continue(...), then handles a later message and returns a whole replacement state with Stop(...). Mantle records process, message, state, and output IDs in:

target/strata/actor_sequence.observability.jsonl

The same message-keyed transitions can be authored with a whole-body match:

cargo run -p strata --bin strata -- check examples/actor_match.str
cargo run -p strata --bin strata -- build examples/actor_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_match.mta

That example uses match msg as an authoring form while lowering to typed Mantle transition IDs, not runtime source-string dispatch.

Non-step match bodies can select an immutable initial state:

cargo run -p strata --bin strata -- check examples/init_match.str
cargo run -p strata --bin strata -- build examples/init_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/init_match.mta

That example uses a typed init match over an enum constructor and lowers the selected whole-state record value into the Mantle initial state ID.

Normal source functions can live at module level or inside a process:

cargo run -p strata --bin strata -- check examples/function_match.str
cargo run -p strata --bin strata -- build examples/function_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/function_match.mta

That example uses module-level signature-pattern functions, a module-level whole-body match helper, process-local helpers in Main and Worker, and a helper-produced send payload. The checker expands those immutable value helpers before Mantle artifact generation.

Source helper patterns can bind typed enum payloads:

cargo run -p strata --bin strata -- check examples/function_payload_match.str
cargo run -p strata --bin strata -- build examples/function_payload_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/function_payload_match.mta

That example constructs payload-bearing enum values in immutable source helper returns, matches them through signature patterns and whole-body matches, and lowers dynamic received payload wrapping into a Mantle value template.

Process state enums can carry typed immutable payloads:

cargo run -p strata --bin strata -- check examples/state_payload_enum.str
cargo run -p strata --bin strata -- build examples/state_payload_enum.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/state_payload_enum.mta

That example admits Idle and Working(Job { phase: Ready }) as typed state values, then lowers a received payload state transition into a Mantle value template that must resolve to the admitted state table before execution.

Current process state can also be matched as immutable data:

cargo run -p strata --bin strata -- check examples/state_payload_match.str
cargo run -p strata --bin strata -- build examples/state_payload_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/state_payload_match.mta

That example enters Working(Job { phase: Ready }), later matches Working(job: Job) through the current state parameter, and returns the whole replacement state Done(job). Lowering emits typed state-specific Mantle transitions, and runtime dispatch selects by admitted message ID plus admitted current state ID.

Process references support multiple runtime instances of one process definition:

cargo run -p strata --bin strata -- check examples/actor_instances.str
cargo run -p strata --bin strata -- build examples/actor_instances.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_instances.mta

That example spawns two Worker instances through distinct process references and sends Ping to both. Mantle records different runtime pid values for the two workers while retaining the same loaded process definition ID.

Actor messages can also carry typed immutable payloads:

cargo run -p strata --bin strata -- check examples/actor_payloads.str
cargo run -p strata --bin strata -- build examples/actor_payloads.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_payloads.mta

That example sends Assign(Job { phase: Ready }), binds the payload with a step parameter pattern as Assign(job: Job), and returns a whole replacement state containing the bound payload value.

The same payload binding can be authored inside a whole-body match:

cargo run -p strata --bin strata -- check examples/actor_payload_match.str
cargo run -p strata --bin strata -- build examples/actor_payload_match.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_payload_match.mta

That example binds Assign(job: Job) inside match msg and lowers to the same typed payload and transition model as the signature-pattern form.

Process references can travel as typed immutable payloads:

cargo run -p strata --bin strata -- check examples/actor_reply.str
cargo run -p strata --bin strata -- build examples/actor_reply.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_reply.mta

That example sends Work(ProcessRef<Sink>) to a worker, binds the received reference as Work(reply_to: ProcessRef<Sink>), and sends Done through the received typed reference. Mantle traces both the runtime pid and admitted process ID for the transported reference.

Fail-closed actor failure has source-to-runtime evidence:

cargo run -p strata --bin strata -- check examples/actor_panic_no_replay.str
cargo run -p strata --bin strata -- build examples/actor_panic_no_replay.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/actor_panic_no_replay.mta

That example returns Panic(Failed) after a worker dequeues one of two accepted messages. Mantle records the abnormal step and process_failed event, exits non-zero, and does not replay the consumed message.

What Strata Is For

Strata is aimed at programs where the important behavior should be explicit:

• which effects a function may perform;
• which authority a process or component may exercise;
• which messages a process accepts and emits;
• which state transitions are valid;
• which operations must be deterministic;
• which protocols govern local or distributed communication.

The goal is not just to run code. The goal is to make runtime behavior part of the checked interface of the program.

What Mantle Is For

Mantle is the execution layer. Its job is to validate and run .mta artifacts, manage processes and mailboxes, dispatch approved effects, supervise failures, and emit runtime evidence.

The .mta format is intentionally language-neutral. Strata is the first frontend, but Mantle should remain a stable target for other frontends that want the same runtime semantics.

Design Principles

• Source first: .str is the authoring surface.
• Explicit effects: undeclared side effects should be rejected.
• Explicit authority: runtime capability use should be visible and checked.
• Runtime evidence: execution-bearing milestones should produce traces.
• Fail closed: invalid artifacts, unsupported authority, and unsafe runtime states should be rejected rather than silently widened.
• Language-neutral runtime artifacts: Mantle artifacts identify their format, version, and source language internally, and carry executable type identity through Mantle type-table IDs rather than source type strings.
• Corpus matters: examples, libraries, fixtures, and conformance cases are part of the language/runtime, not an afterthought.

Corpus And Libraries

New languages do not succeed on syntax alone. They need a durable body of high quality code: examples, standard patterns, libraries, tests, rejection cases, and runtime traces.

Strata and Mantle grow through two tracks:

• native Strata programs and libraries that show the language as it is intended to be written;
• companion Rust crates that expose Mantle-oriented ideas where using an existing language is the right engineering path.

Those two tracks should reinforce each other. Rust libraries can make the runtime semantics useful earlier, while Strata examples and libraries build the idiomatic corpus needed for the language itself.

Project Direction

MVP expansion targets:

• richer .str parsing and diagnostics;
• richer actors/processes with typed mailboxes;
• broader process references plus message send and receive behavior;
• broader process state transitions;
• normal termination and failure reporting;
• explicit effect checking beyond the emit, spawn, and send slice;
• Mantle runtime traces that prove execution happened inside the runtime;
• conformance tests and example programs that double as corpus material.

Full-shape targets include typed distribution, supervision, capability-aware runtime behavior, artifact validation, upgrade coordination, and reproducible publication.

File Types

• .str files are Strata source files.
• .mta files are Mantle Target Artifacts.

See docs/src/file-types.md for the source/artifact boundary, MIME identifiers, and tooling notes.

Repository Layout

examples/                 runnable Strata examples
crates/strata/             Strata source checker, builder, and CLI
crates/mantle-artifact/    Mantle Target Artifact encode/decode/validation
crates/mantle-runtime/     local Mantle runtime and CLI
crates/strata-mantle-acceptance/
                          Strata/Mantle source-to-runtime acceptance tests
tools/                     editor and MIME metadata

Development

Repository automation is centralized in Justfile. GitHub Actions and lefthook delegate to the same recipes used locally.

CI caches Cargo registry/git data and per-job target directories using GitHub-owned, SHA-pinned actions.

The mdBook under docs/ is the primary project documentation. Start with docs/src/getting-started.md for first use, then docs/src/language-reference.md and docs/src/syntax-reference.md for the accepted source surface.

The workspace uses Rust Edition 2024 and requires Rust 1.85 or newer. The standard gates select stable Rust explicitly. Nightly is used only by the fuzz and Miri recipes, which select it per command. Do not set a repository-wide nightly override.

Install the local command runner:

rustup toolchain install stable --profile minimal --component rustfmt,clippy
cargo +stable install just --version 1.50.0 --locked

The 1.50.0 value is the pinned just command runner version, not the Rust compiler version.

List available commands:

just --list

Run the verification bundle:

just quality

Install local hooks:

brew install lefthook
# or: winget install -e --id evilmartians.lefthook
# or: go install github.com/evilmartians/lefthook@latest
lefthook install

Run native checks plus the Linux quality job through act:

just ci-local

The underlying stable gate recipes are:

just fmt-check
just check
just test
just lint
just build
just metadata-check
just toolchain-policy-check
just docs
just diff-check

Run the source-to-runtime gates manually:

just source-to-runtime-gates

Nightly-only validation is also available for fuzz and Miri smoke coverage:

just install-fuzz-tools
just fuzz-ci
just install-miri-tools
just miri-ci