SEMAPRAX

Meaning in. Verified machine code out.

An experimental, agent-native systems programming language built around a stable semantic program graph.

Get started · See what works · Read the RFC · View the roadmap · Visit the project page

Warning

SEMAPRAX is pre-alpha research software. Its language, graph schemas, diagnostics, and ABIs will change. Do not use it for production or safety-critical workloads.

Most programming tools—and most coding agents—work by editing character ranges and repeatedly reconstructing program meaning. SEMAPRAX keeps readable .spx source for humans and Git, while exposing a deterministic, versioned semantic graph as the preferred interface for agents.

That design gives SEMAPRAX three defining properties:

Principle	What it means
Stable meaning	Public declarations have persistent identities; types, effects, contracts, ownership, and call relationships are explicit.
Verified changes	Semantic patches are revision-bound, replayable, and stale-safe. Failed transactions leave source unchanged.
Shared lowering	Native and WebAssembly backends consume the same validated stable-ID HIR and target-neutral cleanup meaning.

Get started

Prerequisites

• Rust 1.85 or newer
• Clang for native compilation
• Node.js 22 or newer for the browser/WebAssembly verification example

Clone and run

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

# Parse, type-check, and verify a program.
cargo run --locked -p semaprax -- check examples/meaning.spx

# Compile it to a host-native executable and run it.
cargo run --locked -p semaprax -- run examples/meaning.spx

The example prints:

42

Install the development CLI locally if you prefer shorter commands:

cargo install --path .
semaprax check examples/meaning.spx
semaprax run examples/meaning.spx

Inspect meaning, not text

# Emit the deterministic semantic graph.
cargo run --locked -p semaprax -- graph examples/meaning.spx

# Ask for a bounded semantic slice around a stable declaration ID.
cargo run --locked -p semaprax -- context \
  examples/meaning.spx app.main \
  --depth 1 --max-bytes 65536 --max-nodes 256

Build for the web

cargo run --locked -p semaprax -- build \
  examples/control_flow.spx \
  --target web \
  -o target/control-flow-web

node scripts/verify-web.mjs target/control-flow-web

A small SEMAPRAX program

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)
}

@id gives a public declaration persistent semantic identity. Contracts are checked and carried into the supported native and Wasm artifact lanes instead of existing only as comments.

More examples cover control flow, effects, ownership, lifecycles, records, and the native callable target.

How it fits together

flowchart LR
    S["Human-readable .spx source"] --> V["Parser + verifier"]
    V --> H["Validated stable-ID HIR"]
    H --> G["Versioned semantic graph"]
    G --> A["Context · impact · review"]
    P["Revision-bound semantic patch"] --> T["Replay + transaction gates"]
    G --> T
    T --> S
    H --> N["C11 / Clang"]
    H --> W["WebAssembly Core"]
    N --> NE["Native executable"]
    W --> WB["Browser package"]

Loading

Readable source is the canonical Git projection. The semantic graph is the preferred agent projection. Both native and Wasm lowering begin only after the same parser, resolver, verifier, and HIR validation path.

Project status

Current release line: v0.2 · Maturity: pre-alpha research

The completion matrix is the source of truth for project claims. At the current evidence milestone it records 39 Partial and 17 Missing full-goal requirements. A feature is not called implemented unless its stated gate has executable evidence; a successful narrow prototype does not satisfy a broader product gate.

Evidence-backed prototype surface

Area	Where it is today
Language core	Typed i64/bool functions, bindings, expressions, checked arithmetic, contracts, effects, and explicit capabilities.
Data model	Bounded records, explicit Copy generics, Copy variants, compiler-owned Option/Result, exhaustive Copy matching, and a constrained postfix ? slice.
Ownership	Move and partial-place checking, explicit lifecycle/ownership boundaries, and independently replayed target-neutral cleanup plans. General lifetime, aliasing, concurrency, and public resource execution remain open.
Agent interface	Deterministic Graph v10–v14, bounded context, impact preview, repair discovery, semantic review, and exact evidence replay.
Semantic changes	Atomic single-file patches plus bounded managed multi-file workspace transactions and replacements-only semantic workspace operations. These do not provide general Git/editor-tree atomicity.
Project build	A bounded explicit pure-scalar semaprax.toml build input reuses one in-memory Workspace Phase-A pass and publishes a Web package. Explicit stable-ID use function provider edges are its only cross-file composition; native lowering is internal evidence only. This is not dependency management, a managed workspace, or production packaging.
Native target	C11/Clang scalar and bounded Copy-data execution plus a locally evidenced generated scalar Native Rust SDK package. Exact-head SDK promotion and public general resource/string/FFI/aggregate ABI admission remain open.
Web target	WebAssembly Core plus a generated package; selected stable-ID scalar functions have bounded JavaScript/TypeScript bindings. General browser-SDK and public Component Model output remain open.
Applications	Private CI evidence exists for bounded desktop and mobile prototypes. Public SDKs, packaging, lifecycle breadth, and production distribution remain open.
Agent runtime	A bounded injected-host Rust API has hosted deterministic fake-host evidence. It is not a live provider transport, CLI agent, durable-memory system, wallet, payment, signing, or ambient-authority surface.

The bounded public Agent Runtime v1 gate is hosted green at Public Agent Runtime v1 is hosted GREEN at 8cf29aff8d1be3ccf74c36bc8c837f0c666ca067 (run 31591039261, 12/12 jobs, private and public deterministic fake-host gates on Ubuntu, macOS, and Windows). Private Economic Agent v1 A+B is exact-head hosted green at fe75c38d898b71e3ed5c57411fb46d0dbd4fc34b in run 31611748969, including both Economic gates on Ubuntu, macOS, and Windows. Public Economic Agent v1 C is exact-head hosted green at 03f1f2736de23d03b298f265f93409de89a6be95 in run 31616168124 (12/12 jobs), including the private, process-termination, and public Economic gates on Ubuntu, macOS, and Windows.

Private Native Rust Interoperability v1 A+B is exact-head hosted green at 50b96dccabe3b3dcbcdf38bab380f3eb8699184c in run 32402944574. Public Native Rust SDK v1 Phase C now adds a narrow API in the still-unpublished builder and generates a dependency-free local Cargo package with stable-ID scalar methods; its exact-head three-host promotion remains pending, and there is still no root CLI or registry package. See Native Rust Interoperability v1 and the Rust calculator consumer.

For precise evidence, boundaries, and non-claims, use these documents:

• Full-goal completion matrix — authoritative status
• Architecture — implementation and trust boundaries
• Quality gates — required executable evidence
• Roadmap — sequencing toward the full objective
• Changelog — notable repository changes

Agent-native workflow

SEMAPRAX is designed so an agent can ask for the smallest useful semantic slice, preview a typed change, inspect its consequences, and only then request an atomic application.

graph/context → semantic patch → impact/review → evidence replay → atomic apply

The current public protocols include:

• bounded forward, reverse, or bidirectional call context;
• stable-ID semantic patches with stale-revision rejection;
• read-only impact, diagnostic repair, and fixed-section review projections;
• independently replayable patch and target-evidence capsules;
• bounded immutable-generation workspace publication through an authenticated ACTIVE pivot for cooperating readers.

Start with Agent Context v1, Semantic Impact v1, Semantic Review v1, and Semantic Patch Evidence v1.

CLI at a glance

Command	Purpose
semaprax check <file> [--json]	Parse, type-check, and verify a source file.
semaprax fmt <file> [--check]	Apply or verify canonical formatting.
semaprax run <file>	Build and run a host-native program.
semaprax build <file> [--target native|native-callable|web] [--export stable-id ...]	Produce a native executable, bounded callable bundle, or browser/Wasm package with selected scalar exports.
semaprax check [semaprax.toml] / semaprax build [semaprax.toml] [--target web]	Check or publish the bounded Project Manifest v1 Web package; --manifest-path selects another manifest.
semaprax graph <file>	Emit the revisioned semantic graph.
semaprax context <file> <stable-id> [options]	Emit a deterministic, bounded semantic context.
semaprax impact <file> <patch.spatch> [options]	Preview supported source consumers and reverse-call impact without writing.
semaprax review <file> <patch.spatch>	Emit the bounded semantic review report.
semaprax patch <file> <patch.spatch>	Apply a supported atomic semantic transaction.

Run semaprax --help for the complete workspace, evidence, repair, and target command surface.

For a calculator-style web core, select persistent function identities directly:

semaprax build examples/calculator.spx --target web \
  --export calculator.add --export calculator.divide \
  -o calculator-web

Import calculator-web/semaprax.bindings.js and call runtime.call("calculator.add", ...). The key survives a source-level function rename because it is the declaration's persistent identity. See Public Wasm Scalar Exports v1 for the exact scalar-only boundary and remaining browser/TypeScript gates.

For the bounded multi-file calculator, run semaprax check examples/calculator-project/semaprax.toml or semaprax build examples/calculator-project/semaprax.toml --target web -o calculator-project-web. The six-line manifest explicitly names all sources, entry/test modules, and Web exports; it has no dependency or capability syntax. See Project Manifest v1 for its scalar-only, Web-only publication boundary: interface/native imports and use type are excluded, while explicit stable-ID use function provider edges compose the named modules. A final post-publication input drift is SPX-J103; callers reconcile the retained digest-bound package and never delete it automatically.

Roadmap

Stage	Focus
0.2 — current	Useful core language, semantic graph, bounded agent context/change/review, and native/Wasm execution slices.
0.3	General ownership and lifetime safety, escape analysis, restricted unsafe code, and a fast development backend.
0.4	Components, packages, reproducible builds, provenance, and portable/native interop.
0.5	Structured concurrency, deterministic effects, applications, and platform adapters.
1.0	One maintained product proving the full cross-platform language and toolchain contract.

This table is orientation, not a claim of completion. See the detailed roadmap and 1.0 completion contract.

Documentation

Document	Read it for
RFC 0001	The language, compiler, interoperability, application, and target contract.
RFC 0002	Algebraic data, records, variants, matching, Option, and Result.
RFC 0003	Cleanup, resource ownership, and ABI phases.
RFC 0004	Proposed native owned-call recovery and settlement contract.
Architecture	Compiler stages, backend boundaries, and repository map.
Migrations	Compatibility notes for agent-facing protocols.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the agent guide before changing semantics. Compiler changes should include a success case, a stable diagnostic regression, canonical round-trip coverage, and native/Wasm equivalence when runtime meaning changes.

Run the full Unix quality gate with:

scripts/quality.sh

Design changes affecting syntax, graph schemas, transactions, effects, ownership, contracts, or ABI should begin as an RFC. By participating, you agree to follow the Code of Conduct.

Citation and license

Use CITATION.cff for repository metadata and CITATION.md for evidence-specific citation guidance. Technical claims should cite the exact commit and the repository document that supports them.

SEMAPRAX is created and maintained by Wavect GmbH and distributed under the Apache License 2.0.