SEMAPRAX documentation

Status: living public documentation entry point for v0.5.0; the HOSTED GREEN implementation baseline remains v0.4.0.

Audience: language users and integrators.

This is the public documentation entry point for SEMAPRAX. Start here to learn the language and its supported workflows. Contributor process, implementation evidence, private experiments, and repository internals live in the separate development guide.

SEMAPRAX is alpha. A versioned document describes an exact bounded contract; it does not imply that the broader feature is complete or stable. The completion matrix is the product-status authority. The v0.4.0 baseline records HOSTED GREEN for the released implementation and supersedes its pre-release local-only status.

The v0.5.0 prerelease contains smoke-tested Linux x86-64, Apple Silicon macOS, and Windows x86-64 archives. The implemented release code has HOSTED GREEN evidence; the release-note publication issue is not an outstanding code-evidence gate. See the release baseline and release record and checksums. The release remains unsigned, not notarized, and alpha. Recent project and tooling notes are summarized in CHANGELOG.md, with compact highlights in CHANGELOG-SUMMARY.md, and full history in docs/CHANGELOG-ARCHIVE.md.

Choose a path

You want to…	Start with…
Understand the current implementation and evidence stage	v0.4.0 HOSTED GREEN baseline
Install a working toolchain	Install
Track recent changes	CHANGELOG
Try the language	Follow the executable quickstart, then explore the root README
Learn the language itself	Work through the language tour
Write SEMAPRAX as a coding agent with a small context window	Load the compiler-checked agent quick reference
Fix a known SPX-* diagnostic without loading the full reference	Run semaprax help diagnostic <SPX-code>; semaprax help diagnostic codes lists exact supported codes
Find a standard-library declaration and its contract	Read the generated standard library catalog; Standard Library v1 owns the tiers and required modules
Find a minimal example to point a command at	Examples index
Find or automate a compiler command	Using the SEMAPRAX CLI and Unified CLI
Highlight .spx files in Visual Studio Code	The repository's VS Code extension
Understand the language design	RFC 0001
Work with records, variants, matching, Option, or Result	RFC 0002
Understand ownership and cleanup	RFC 0003
Build a multi-file project	Project Manifest v1, then the owning additive profile
Run a source-defined Agent	Iterative lifecycle v2 and Direct Runtime v2
Use generic collections or callbacks	Generic compiler collections, function values v2, and closures v2
Call SEMAPRAX from JavaScript	Wasm Scalar Exports v1
Inspect the unpromoted Project v8 owned-byte SDK boundary	Public Owned Data API v1
Inspect the unpromoted Project v9 flat-record boundary	Public Flat Owned Record API v1
Inspect the unpromoted Project v10 owned-string boundary	Public Owned UTF-8 API v1
Query program meaning	Agent Context v2 and Universal Semantic Query
Preview or apply a semantic change	Semantic Patch v2, then Impact and Review
Validate an authority-free Project transaction	Universal Semantic Transaction v2 and composition
Integrate a compiler report or generated artifact	Use the reference catalog
Contribute to the compiler	First contribution, then the development documentation

Core concepts

Source and identity

Readable .spx source is the canonical Git projection. Public declarations can carry persistent @id identities, while expression identities may change with a revision. Canonical formatting removes incidental textual differences.

Checked semantic representation

The compiler parses and verifies source before producing stable-ID HIR and a versioned semantic graph. Graph queries expose bounded context without making source text the agent's only representation.

Evidence and authority

Reports and evidence capsules are deterministic descriptions. They are not signatures, approvals, or write authority. A mutating route must authenticate its inputs, replay the relevant evidence, and own the final transaction.

Shared backend meaning

Native and WebAssembly implementations consume the same verified HIR and target-neutral cleanup plans. The released implementations have hosted-green evidence within their admitted target profiles. This does not extend a feature to targets or shapes excluded by its owning specification.

Public language and workflow references

• RFC 0001: complete language and toolchain contract.
• RFC 0002: algebraic data and aggregate ownership.
• RFC 0003: cleanup and resource ABI.
• Mutation, field mutation, while loops, and refutable matching: bounded language extensions.
• Project Manifest v1: bounded multi-file input and build contract. Later manifest versions are additive specialized profiles, including Useful Data v2 / Project v16 and Process I/O / Project v18 and Checked filesystem outcomes / Project v19.
• Wasm Scalar Exports v1: generated JavaScript and TypeScript boundary for selected stable-ID scalar functions.
• Useful Text Consumer v1 and Portable Indexed Byte Data v1: narrow text and byte-data profiles.
• Public Owned Data API v1: additive Project v8 implementation and completion contract for copied owned-byte results in JavaScript/TypeScript and safe Rust. Release regression evidence is hosted green; the generated packages remain unpublished and formal promotion is open.
• Public Flat Owned Record API v1: additive Project v9 descriptor and physical JavaScript/safe-Rust flat-record boundary. Release regression evidence is hosted green; it remains unpublished and unpromoted.
• Public Owned UTF-8 API v1: additive Project v10 descriptor and physical JavaScript/safe-Rust string boundary. Release regression evidence is hosted green; it remains unpublished and unpromoted, and depends on an explicit Project v9 promotion decision.

Agent workflow references

The supported conceptual flow is:

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

The additive Project transaction APIs also provide authority-free validation and replay; validation alone does not perform the final apply operation.

• Agent Context v1 and v2 define bounded semantic queries.
• Project Agent Transport v5 defines the opt-in, read-only Project v8 descriptor and inline npm carrier methods. Its released implementation has hosted-green evidence; public promotion remains a separate decision.
• Iterative lifecycle v2, typed effects v3, and Direct Runtime v2 define bounded source Agent execution. Checkpoints v2 and durable migration v3 retain their explicit authorization, replay, and recovery boundaries.
• Semantic Patch v2 defines the supported single-file operation format.
• Diagnostic Repair v1 defines repair discovery and the sole Patch v3 operation.
• Semantic Impact v1 and Semantic Review v1 are read-only previews.
• Patch Evidence v1, v2, and Target Evidence v1 define independently replayable evidence formats.
• The workspace references extend the same principles to a bounded managed immutable-generation workspace; they do not make raw Git or editor paths atomically visible.

Reference catalog

Versioned reference documents are intentionally precise. They define one wire format, report, ABI, admission profile, or evidence boundary. They are useful to tool and host authors but are not the recommended introduction to SEMAPRAX.

The exhaustive, audience-separated list is in source catalog:

• public language and workflow references;
• agent and workspace protocol references;
• target, ABI, schema, and package projections;
• internal architecture, quality, status, roadmap, decisions, and private experiment contracts.

Compatibility and status

• v0.4.0 baseline owns the current hosted-green release evidence classification and its relationship to historical evidence.
• Protocol migrations records compatibility changes between versioned agent-facing formats.
• Completion matrix owns product status and completion criteria.
• Changelog owns historical implementation changes.
• Changelog summary gives a compact latest-notes view.
• Roadmap owns future sequencing, not implementation claims.

Keeping these responsibilities separate prevents the same status narrative from drifting across the README, RFCs, architecture, and roadmap.