Status: agent-facing contract index for the versioned specification library. Audience: coding agents, tool authors, and integrators needing exact contracts.
Learning or using Semaprax? Start with the user-facing Semaprax Handbook instead: task-oriented, best-practice documentation with copy-paste examples. This directory is the authoritative specification library behind it — precise, versioned contracts (syntax, wire formats, ABIs, protocols, evidence boundaries) that agents and tools cite for exact behavior.
The v0.4.0 baseline is the last release with a HOSTED GREEN implementation claim. The workspace is at version 0.9.0, installable from source; v0.9.0 publishes five native archives and both per-user installers. Read the completion matrix before treating a versioned contract as a supported feature: a specification is not proof of implementation. Contributors start with First contribution.
| You want to… | Start here |
|---|---|
| Install and run your first program | Handbook: Install → First program |
| Learn the language | Handbook: Essentials → RFC 0001 |
| Find a command or example | Handbook: Cheatsheet · Examples |
| Fix a diagnostic | Handbook: Debugging, or run semaprax help diagnostic <SPX-code> |
| Find a library API | Handbook: Stdlib → Standard-library catalog |
| Build a multi-file project | Handbook: First project → Project Manifest v1 |
Write .spx as an agent |
Handbook: Agents → Agent quick reference |
| Query or change program meaning | Agent Context v2 → Semantic Patch v2 |
| Contribute to the compiler | First contribution → Development guide |
| Check feature or release status | Completion matrix · Release status |
Keep readable .spx files in Git. Public declarations can have stable @id
values, so tools can recognize them across edits. Expression IDs may change
with each revision. The formatter gives equivalent source one canonical form.
The compiler checks source before it produces HIR (its checked intermediate form) and a versioned semantic graph. Agents can ask that graph focused questions instead of reading an entire project.
Reports and evidence describe what was checked; they do not grant permission to write. A change must still authenticate its inputs, replay its evidence, and use an authorized transaction.
Native and WebAssembly backends use the same checked HIR and cleanup plan. Evidence applies only to the targets and program shapes named by each feature's specification.
- RFC 0001 is the full language and toolchain contract.
- RFC 0002 covers records, variants, and ownership; RFC 0003 covers cleanup.
- Project Manifest v1 defines multi-file projects. Later manifests add specialized profiles, including Useful Data, Process I/O, and checked filesystem outcomes.
- Wasm Scalar Exports v1 defines the selected JavaScript/TypeScript scalar boundary.
- The owned-byte, flat-record, and owned-string APIs have hosted release regression evidence but remain unpublished and unpromoted. Check each contract and the completion matrix before using one.
Agent tools follow this sequence:
graph/context → patch → impact/review → evidence replay → atomic apply
Validation checks a proposed change; it does not apply it.
- Agent Context v2 explains focused graph queries.
- Semantic Patch v2 defines single-file changes; Impact and Review preview their effects without writing.
- Iterative lifecycle v2 and Direct Runtime v2 cover bounded source Agent runs.
- Project Agent Transport v5 defines an opt-in, read-only transport. Hosted regression evidence does not mean public promotion.
- Diagnostic Repair v1 covers repair discovery; Patch Evidence v2 covers replayable proof. The catalog lists earlier versions and specialized protocols.
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 the reference 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.
- 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.