SEMAPRAX

The idea: make meaning, constraints, and change first-class parts of programming.

Semaprax keeps human-readable .spx source in Git. The compiler also exposes a versioned semantic graph: declarations, types, contracts, effects, and their relationships. A coding agent can ask what a function means, inspect its callers, and propose a change against the exact revision it inspected.

This is a language and toolchain, not a prompt wrapper, a natural-language compiler, or a requirement to use AI. You can write and run ordinary programs without an AI model or API key.

You need Git and Rust/Cargo 1.88+ for this source-checkout route. The two commands below use the checker and interpreter; they do not require Clang, Node.js, or a model provider. Cargo may download Rust dependencies and compile the toolchain on the first run.

git clone https://github.com/wavect/semaprax.git
cd semaprax

cargo run --locked -p semaprax -- check examples/meaning.spx
cargo run --locked -p semaprax -- run examples/meaning.spx

The first command reports a verified program and its revision. The second prints 42. No global installation or PATH change is needed.

From the same repository directory, install the standalone CLI:

cargo install --locked --path . --bin semaprax

Ensure Cargo's binary directory is on PATH; in Bash or Zsh:

export PATH="$HOME/.cargo/bin:$PATH"
semaprax --version

Then create, check, test, and run a multi-file project without leaving the repository directory:

semaprax new first-semaprax
semaprax check first-semaprax/semaprax.toml
semaprax test first-semaprax/semaprax.toml
semaprax run first-semaprax/semaprax.toml

The generated calculator prints 42. It includes a manifest, source, tests, and an AGENTS.md with project commands and language-specific guidance. new requires a fresh destination; it does not initialize Git, install packages, or access the network.

All remaining commands assume the repository root. To stay with the no-install route, replace semaprax with cargo run --locked -p semaprax --. Shell examples use POSIX syntax; Install covers Windows, prebuilt release archives, prerequisites, and troubleshooting. The full quickstart takes the generated project further.

This is the complete program you just ran:

module examples.meaning;

@id("math.add")
fn add(left: i64, right: i64) -> i64
    requires left >= 0
    requires right >= 0
    ensures result == left + right
{
    left + right
}

@id("app.main")
fn main() -> i64
    ensures result == 42
{
    add(19, 23)
}

add is the human-facing name; math.add is its persistent semantic identity. requires and ensures are part of the function's meaning, not just comments. The last expression is the function's result.

Verification is progressive: the implemented checks and contract machinery combine static validation with runtime guards in supported profiles. “Verified” does not mean every program has a full formal proof or is bug-free. The language tour explains the rules through committed, compiler-checked examples.

Start with the same program, but ask for the representation a tool can use:

# The complete semantic graph for this file.
semaprax graph examples/meaning.spx

# Bounded context around one stable declaration identity.
semaprax context examples/meaning.spx app.main \
  --depth 1 --max-bytes 65536 --max-nodes 256

# Just the contract-oriented view of the function it calls.
semaprax context examples/meaning.spx math.add --depth 1 --filters contracts

The important shift is from “find something that looks like this text” to “inspect and change this declaration at this revision.” The supported workflow is:

Inspect graph/context → propose semantic edit → inspect impact/review
                     → replay checks → explicitly authorized apply

Semantic patches and the managed workspace protocols implement defined editing operations, not arbitrary AI rewrites. Supported patches check their base revision and semantic constraints before changing source. Read-only reports are not permission to write, and multi-file validation is not itself publication.

For tool builders, the repository includes MCP-connected review/publication workflows in the agent-workflow package and a Rust embedding API. These are scoped integration routes, not a universal IDE agent or an unrestricted filesystem API.

Every generated project includes AGENTS.md. The installed compiler also carries targeted language help, declaration examples, and diagnostic fixes:

semaprax help language
semaprax help language topics
semaprax help diagnostic SPX-T208
semaprax help diagnostic codes

Use the agent quick reference, standard library catalog, and language shapes catalog as compact context. The VS Code extension adds .spx highlighting.

A model can propose an action. That does not give it authority to perform it.

Semaprax also has source-defined Agents with typed roles for tasks, state, observations, proposals, outcomes, and results. Its implemented iterative lifecycle separates model output from the deterministic code that decides what happens next:

Initialize once
    ↓
Observe → model proposes → decode typed Proposal → authorize → execute → reduce
    ↑                                                                      │
    └──────────────────────────── Continue ────────────────────────────────┘
                                      or Complete / Suspend / Fail

The iterative lifecycle, typed effects, and Direct Runtime give this separation executable form. The checked reducer chooses the next state; authorization runs again for each turn; host capabilities and handlers are supplied explicitly.

Source Agent execution currently uses the retained interpreter and explicitly supplied host integrations. Start with the linked lifecycle and runtime guides; this is not a one-command hosted agent service.

The development tree goes beyond a calculator. Its supported language profiles include the following; individual constructs and target combinations still have explicit limits.

Follow the language tour, then choose a runnable example. The completion matrix separates these implemented profiles from the broader language goal.

You do not need to replace an entire application to explore Semaprax. Start with a small computational kernel, validator, or parser and keep the UI, networking infrastructure, and application services in your host stack.

With Node.js 22+, run this from the repository root. The build emits a Wasm module plus JavaScript bindings and TypeScript declarations:

semaprax build examples/calculator.spx --target web \
  --export calculator.add --export calculator.subtract \
  --export calculator.multiply --export calculator.divide \
  --export calculator.is-negative --export calculator.not \
  -o target/calculator-web

node scripts/verify-wasm-scalar-exports.mjs target/calculator-web

The verifier prints scalar-exports-v1-ok. Now call the generated package:

node --input-type=module <<'JS'
import { readFile } from 'node:fs/promises';
import { instantiateBytes } from './target/calculator-web/semaprax.bindings.js';

const runtime = await instantiateBytes(await readFile('target/calculator-web/app.wasm'));
console.log(runtime.call('calculator.add', 19n, 23n));
// { ok: true, value: 42n }
JS

The API uses the stable identity calculator.add, not a generated display name. Semaprax's i64 values cross this JavaScript boundary as BigInt, hence 19n and 23n. Contract and arithmetic failures use structured status results. See scalar exports and the browser example.

The native path emits C11 and uses Clang. Selected generated Rust SDKs and owned-data JavaScript/Rust interfaces are also available as developer previews. Some require the separate semaprax-full toolchain rather than the standalone CLI; follow the Rust consumer or owned-data API instructions for that route. Generated preview packages are not a promise of registry publication, a stable ABI, or support for every language feature on every target.

For an agent-tooling experiment, inspect math.add with context and follow semantic impact into a supported rename on a copy. The committed examples/rename.spatch deliberately contains a revision placeholder; obtain the current revision before using it, and do not mutate the canonical example used by repository tests.

flowchart LR
    S["Readable .spx source in Git"] --> H["Checked compiler representation"]
    H --> G["Versioned semantic graph"]
    G --> Q["Context, queries, impact and review"]
    G --> T["Replay-checked semantic edits"]
    T --> S
    H --> I["Interpreter"]
    H --> N["Native via C11 / Clang"]
    H --> W["Core WebAssembly / JS bindings"]

These paths share checked program meaning, but admit different subsets. The graph describes the program; it does not itself grant write, network, build, payment, or publication authority.

Development version: 0.4.1 · Maturity: pre-alpha · Full product goal: Partial.

There is executable language, graph, semantic-change, runtime, and host-integration work to explore today. There is not yet a production application toolchain, a stable general ownership/lifetime system or public ABI, a complete package ecosystem, or universal target support. Latest main also contains work beyond the published release; a development-tree capability is not automatically available in a downloaded archive.

The long-term ambition is a systems language in which agents manipulate meaning, humans retain readable source and review control, and compilation connects both to native and portable execution. Memory safety without a mandatory tracing collector, richer verification, broader interoperability, and better agent workflows belong to that language contract.

Reducing irrelevant model context and repair ambiguity is a design goal, not a blanket claim of measured token savings, faster development, or superior model accuracy. Evidence and future goals stay separate: completion matrix · roadmap · releases · changelog.

Versioned specifications define precise behavior for integrations; they are reference material, not prerequisites for your first program.

Try a small program. Find the boundary. Help make it better.

Useful contributions include runnable examples, clearer diagnostics, reproducible bug reports, adversarial tests, target parity, and measured agent-workflow experiments. Start with First contribution, CONTRIBUTING.md, and AGENTS.md. Changes to syntax, graphs, effects, ownership, contracts, or ABIs should begin with an RFC or an explicit update to an existing one.

On Unix, the complete repository gate is:

scripts/quality.sh full

Report an issue · Discuss an idea · Star the repository to follow the work.

Created and maintained by Wavect GmbH. Licensed under Apache 2.0. For research citations and claim-specific evidence, see CITATION.cff and CITATION.md.