SEMAPRAX examples

Audience: newcomers to the language and contributors looking for a minimal subject to point a command at.

Status: this index records what each committed example demonstrates and which command was observed to succeed on it. It is not a status claim. Completion matrix is the status authority, and each row's reference owns the exact admission rules.

New here? Read the documentation entry point first, then work through the executable quickstart. The CLI guide covers the commands used below.

How to read the tables

semaprax below means the standalone CLI. From a checkout you can substitute cargo run --locked -p semaprax -- for it; the quickstart covers installing it. A few rows need the private semaprax-full toolchain CLI instead, and say so.

• check verifies a single .spx file or a semaprax.toml manifest.
• run executes the entry main and prints the returned i64. The observed value is shown as → 42.
• test runs a project's declared test modules.
• graph emits the deterministic semantic graph; context answers bounded queries about one declaration. graph succeeded on every .spx file listed here. context was exercised on examples/meaning.spx, examples/ownership.spx and examples/refutable_match.spx only.
• build emits a target package into a directory you name with -o.

Every command and result in the tables below was executed locally against the standalone semaprax CLI on macOS arm64. That is local evidence for one host and one build. It is not hosted, release, or cross-platform evidence, and the repository's own gates in quality gates remain the authority on what is covered.

Start here

Example	Teaches	Command (observed)	Reference
examples/meaning.spx	requires/ensures contracts on a two-function module; the fixed subject of the graph and revision snapshots in tests/examples.rs	semaprax run examples/meaning.spx → 42	RFC 0001
examples/calculator.spx	Six arithmetic and boolean functions with stable @id identities; the subject shared by the web and Rust projections below	semaprax run examples/calculator.spx → 42	RFC 0001
examples/control_flow.spx	let bindings and if used as a value-producing expression	semaprax run examples/control_flow.spx → 42	RFC 0001

Language basics

Example	Teaches	Command (observed)	Reference
examples/net_http_get.spx	The six net_* operations composing a plain-TCP HTTP/1.1 GET: connect, piecewise net_send, net_wait readiness, net_stream_stdout into the bounded transcript, close. main returns 0 without touching the network; fetch executes only through the hosted network seam or the native network profile (no CLI command yet)	semaprax run examples/net_http_get.spx → 0	Bounded Language Network I/O v1
examples/http_app_routing.spx	A typed route/handler dispatch profile over a closed i64 route-code domain: bounded request-line and Content-Length header parsing, five routes (health, echo, not-found, method-not-allowed, malformed) exercised against five literal HTTP/1.1 request byte arrays standing in for a deterministic fixture transport, no sockets	semaprax run examples/http_app_routing.spx → 0	HTTP Application Routing v1
examples/effects.spx	A module-level permit set with a function that declares uses { clock.read }	semaprax run examples/effects.spx → 42	RFC 0001, Capability Manifest v1
examples/classes.spx	A class with a field and two methods, one of them returning a new instance	semaprax run examples/classes.spx → 42	Class Inheritance v1
examples/inheritance.spx	A three-level class hierarchy with method override, super dispatch and an upcast binding	semaprax run examples/inheritance.spx → 6	Class Inheritance v1
examples/strings.spx	String literals and structural string equality, nothing else	semaprax run examples/strings.spx → 1	RFC 0001
examples/string_ops.spx	The string_concat, string_len and string_is_empty intrinsics	semaprax run examples/string_ops.spx → 7	String Operations v1
examples/string_ops_v2.spx	string_starts_with, string_contains, string_len_chars and string_from_char over non-ASCII text, including astral-plane input	semaprax run examples/string_ops_v2.spx → 7	String Operations v1
examples/iterator-operations.spx	map/filter/fold over Iter<T> with owned for loops and scalar closures	semaprax run examples/iterator-operations.spx → 1	Owning Iterators v1, Generic Iterator Operations v1
examples/lazy-iterator-adapters.spx	Bounded lazy fused map/filter/fold adapters over Iter<T> (first_if, map_filter, filter_fold, map_fold) with owned for loops and IterStep dispatch	semaprax run examples/lazy-iterator-adapters.spx → 1	Owning Iterators v1, Bounded Lazy Iterator Adapters v1

examples/effects.spx is a useful reminder that a report generator can refuse a program that checks: semaprax capability-manifest examples/effects.spx reports error[SPX-K202] because clock.read is outside that report's bounded capability vocabulary. Use examples/ownership.spx for a manifest that does emit.

Scalar types

Example	Teaches	Command (observed)	Reference
examples/integers_i32.spx	i32 arithmetic, negation, comparison and the near-minimum value, alongside an i64 result	semaprax run examples/integers_i32.spx → 7	RFC 0001
examples/bytes_u8.spx	u8 literals, division and subtraction, a u8 record field, and a requires clause guarding saturation	semaprax run examples/bytes_u8.spx → 7	RFC 0001
examples/chars.spx	char literals including an escape, char ordering, and a char record field	semaprax run examples/chars.spx → 7	RFC 0001
examples/floats.spx	f64 and f32 arithmetic, unary negation, and float-typed record fields	semaprax run examples/floats.spx → 7	RFC 0001
examples/useful_data_usize_v1.spx	Target-independent usize arithmetic and %, driven by mutable locals	semaprax run examples/useful_data_usize_v1.spx → 0	Portable Indexed Byte Data v1

Data and matching

Example	Teaches	Command (observed)	Reference
examples/records.spx	Nested records, out-of-order field initialization, and nested with update expressions	semaprax run examples/records.spx → 42	RFC 0002
examples/refutable_match.spx	Refutable match over i64, u8 and char with or-patterns, guards, binding arms and _	semaprax run examples/refutable_match.spx → -5	Refutable Match v1

Mutation and loops

Example	Teaches	Command (observed)	Reference
examples/explicit_mutation.spx	let mut locals and reassignment at both i64 and i32 widths	semaprax run examples/explicit_mutation.spx → 500016	Explicit Mutation v1
examples/field_mutation.spx	Assignment to record and class fields, including inside both arms of an if	semaprax run examples/field_mutation.spx → 96	Field Mutation v1
examples/while_loops.spx	Two while loops with their loop-continuation expressions, over mutable locals	semaprax run examples/while_loops.spx → 41	While Loops v1

Expressive standalone examples

These extend the minimal subjects above with multi-concept programs that still run in the reference interpreter (run returns 42) and verify (check and graph pass). Each combines contracts, mutation, loops, records, variants, classes, strings and bytes in a small domain.

Example	Teaches	Command (observed)	Reference
examples/math_algorithms.spx	GCD, LCM, primality, Fibonacci, factorial and digital root with requires/ensures, let mut and while	semaprax run examples/math_algorithms.spx → 42	RFC 0001, Explicit Mutation v1, While Loops v1
examples/expression_evaluator.spx	variant Op/UnaryOp, record Pair, Option/Result pipelines, scalar match and a while-driven Fibonacci fold	semaprax run examples/expression_evaluator.spx → 42	RFC 0002, Refutable Match v1
examples/banking_ledger.spx	record Account, class Portfolio with methods, variant TxKind dispatched to bool, Option/Result over i64 and interest compounding via while	semaprax run --native examples/banking_ledger.spx → 42; the interpreter route does not admit record-typed signatures, with update, or Copy variants and fails closed on SPX-F102	Class Inheritance v1, Field Mutation v1
examples/text_analytics.spx	string_concat/string_len/string_contains, borrow str views, str_as_bytes/byte_len/byte_get word-count and palindrome via indexed while	semaprax run examples/text_analytics.spx → 42	String Operations v1, Portable Indexed Byte Data v1
examples/order_lifecycle.spx	variant Status/Decision, record Line, class Inventory with resource tracking, Result validation and batch while loops	semaprax run examples/order_lifecycle.spx → 42	RFC 0002, Field Mutation v1

Ownership, resources and cleanup

These three declare a resource. All three verify, but run does not reach a result: on this CLI build each reports error[SPX-B104]: native resource lowering requires lifecycle declarations and the verified cleanup ABI. Treat them as check, graph and context subjects.

Example	Teaches	Command (observed)	Reference
examples/ownership.spx	own and borrow parameter modes, a drop trivial resource, and an ensures clause over a borrow-then-consume pipeline	semaprax check examples/ownership.spx → verified … (run fails with SPX-B104)	RFC 0003
examples/lifecycle.spx	A resource whose drop names an imported finalizer, plus the interface/permits/effects/failure/consumes declaration that supplies it	semaprax check examples/lifecycle.spx → verified … (run fails with SPX-B104)	RFC 0003
examples/native_callable.spx	The smallest owned-resource identity function; the subject for a native-callable bundle	semaprax build examples/native_callable.spx --target native-callable --function example.token.identity -o /absolute/out/callable → built native-callable bundle …	Native Callable ABI v3, RFC 0004

Projects and manifests

Each directory here is a multi-file project rooted at its own semaprax.toml. Pass the manifest or the directory, not a source file. check, test and run all accept it, and build accepts it too — --target web needs no --export list because the manifest's web_exports already selects the surface.

Example	Teaches	Command (observed)	Reference
examples/calculator-project	Project schema v1: three modules, cross-module use function @id(...), a tests module and six web_exports	semaprax test examples/calculator-project/semaprax.toml → project tests passed; run → 42	Project Manifest v1
examples/config-validator-project	Project schema v2 under the useful-text-consumer.v1 profile: four modules over borrowed UTF-8 input	semaprax test examples/config-validator-project/semaprax.toml → project tests passed; run → 0	Project Manifest v2, Useful Text Consumer v1
examples/binary-frame-project	Project schema v3 under the useful-data.v1 profile: indexed byte data with a checksum and magic-number check	semaprax test examples/binary-frame-project/semaprax.toml → project tests passed; run → 0	Project Manifest v3, Portable Indexed Byte Data v1
examples/spxgrep-project	Project schema v4 under useful-data-command.v1: a command entry with a single declared process.stdout.write capability	semaprax test examples/spxgrep-project/semaprax.toml → project tests passed; run → 0	Project Manifest v4, Bounded Stdout Transcript v1
examples/spxgrep-native-command-project	Project schema v5 under useful-data-command.v2: the same command shape with a declared input contract and four capabilities	semaprax test examples/spxgrep-native-command-project/semaprax.toml → project tests passed; run → 0	Project Manifest v5
examples/frame-payload-project	Project schema v8 under owned-data-api.v1: an SPX1 frame decoder returning owned Bytes, Option<Bytes> and Result<Bytes, i64>, with a nine-case corpus.json	semaprax test examples/frame-payload-project/semaprax.toml → project tests passed; run → 0	Public Owned Data API v1, and the directory's own README
examples/spxgrep-language-command-project	Project schema v6 under language-command-io.v1: argv-utf8+stdin-bytes.v1 input read through arg_utf8	semaprax test examples/spxgrep-language-command-project/semaprax.toml → project tests passed; run → 0	Bounded Language Command I/O v1
examples/spxgrep-lines-project	Project schema v7 under line-command-io.v1: line-at-a-time filtering with byte_range over the same argv/stdin input	semaprax test examples/spxgrep-lines-project/semaprax.toml → project tests passed; run → 0	Project Manifest v1, section "Additive Project Manifest v7 line-command profile"
examples/network-http-project	Project schema v12 under network-command-io.v1: an HTTP/1.1 GET composed from effect-gated network operations with an authenticated fixture-only execution lane	semaprax network-run examples/network-http-project --fixture examples/network-http-project/http.fixture.json → an HTTP/1.1 200 OK response ending in hello	Bounded Language Network I/O v1
examples/https-project	Project schema v13 under https-command-io.v1: a bounded https_get with explicit network.http authority and authenticated fixture-v3 replay	semaprax network-run examples/https-project --fixture examples/https-project/https.fixture.json → an HTTP/1.1 200 semaprax response ending in ok	HTTPS Client I/O v1, Project Manifest v1
examples/rpg-battle-project	Project schema v1: four modules (stats, combat, app, tests), scalar combat with contracts, while battle simulation and cross-module use function	semaprax test examples/rpg-battle-project/semaprax.toml → project tests passed; run → 42	Project Manifest v1
examples/analytics-pipeline-project	Project schema v1: rolling sums, filtered sums, weighted scoring and a multi-stage process pipeline over four modules	semaprax test examples/analytics-pipeline-project/semaprax.toml → project tests passed; run → 42	Project Manifest v1
examples/event-scheduler-project	Project schema v1: priority scoring, cost scheduling, overdue detection and while batch evaluation across core, policy, app	semaprax test examples/event-scheduler-project/semaprax.toml → project tests passed; run → 42	Project Manifest v1
examples/agent-response-project	Package Manifest v1 under useful-data.v1 with a bundled [dependencies] edge on std.data.json.doc: four modules that validate an agent-style JSON response - structure, bounded depth, trailing bytes and duplicate member names - and render a pull-based structured verdict	semaprax test examples/agent-response-project/semaprax.toml → project tests passed; run → 0	Bounded JSON Scanner v1, Standard Library v1, and the directory's own README
examples/vector-stats-project	Package Manifest v1 with four modules on Owned Bounded Vec v1: a loop-carried vec_push<i64> accumulates a variable number of readings into one owned vector, and a second bounded while filters them back out through vec_len/vec_get	semaprax test examples/vector-stats-project/semaprax.toml → project tests passed; run → 0	Owned Bounded Vec v1, and the directory's own README
examples/catalog-normalizer-project	Package Manifest v1 under owned-data-api.v1 with three modules: one JSON string token decode validity, length bound and ASCII trim per CNORM-012, exercised against the frozen catalog_normalizer oracle	semaprax test examples/catalog-normalizer-project/semaprax.toml → project tests passed (5 named cases); run → 0	Catalog Normalizer Oracle V1, and the directory's own README
examples/offline-repair-project	Private-host offline repair vertical slice: retained project revision, typed replace_function_body change and durable journal replay with zero new dispatches	semaprax test examples/offline-repair-project/semaprax.toml → project tests passed; run → 0	Private Host Offline Repair v1
examples/everyday-agent-project	Everyday Agent validation product (ABI-09A.17) — Package Manifest v1 under filesystem-io.v3 with bundled std.fs/std.io/std.path.value edges: a typed-filesystem and bounded-JSON manifest review in src/manifest_json.spx, plus a source-declared Agent (everyday.agent) in src/agent.spx checked standalone. The two slices are deliberately not wired into one Agent-calls-filesystem pipeline; the directory's own README records why, with reproductions	semaprax test examples/everyday-agent-project → project tests passed; semaprax check examples/everyday-agent-project/src/agent.spx → verified	The directory's own README
examples/apex-supply-chain	Maturity showcase — Project schema v1 with 9 modules, 30+ scalar functions, requires contracts and while optimization across demand, inventory, routing, pricing, risk, optimization and finance; 11 web_exports and 4 named test cases	semaprax test examples/apex-supply-chain/semaprax.toml → project tests passed (4 named cases); run → 42	Project Manifest v1
examples/task-service-project	Reference application — Package Manifest v1 under useful-data.v1 with bundled [dependencies] edges on std.auth and std.jobs: register/log in/create-update a domain record/enqueue-complete a background job/query status/log out, plus row-level unauthorized rejection and invalid-input rejection, in deterministic fixture mode	semaprax test examples/task-service-project → project tests passed; run → 0	Authentication and Sessions v1, Durable Jobs v1, and the directory's own README
examples/job-service-project	Durable-job reference service — Package Manifest v1 under nested-owned-record-api.v1 with a bundled std.jobs dependency, an authored ReportJob payload, and a checked source handler that the host JobRuntime executes through the retained-call seam; the ordinary entry remains an authority-free deterministic anchor	semaprax test examples/job-service-project → project tests passed; run → 0; cargo test --locked -p semaprax --test useful_data job_service_project exercises the separate host-runtime path	Durable Jobs v1, and the directory's own README

The last two projects both bind a borrowed str local from arg_utf8, so they are the two examples that exercise the invocation-owned argument arena from the command line. run executes each project's main, not its command entry; the argv/stdin command entry itself is driven by cargo test --locked -p semaprax --test project (modules language_command_native, line_command_native, command_argument_borrow) and cargo test --locked -p semaprax --test useful_data (module line_filter_project_v7). Completion matrix owns the status of these profiles.

Target and host projections

These directories are not programs to run. Each is a committed host-side consumer or shell that expects a generated package next to it, and the generated output is deliberately not committed. Build the package first, then run the consumer with its own toolchain. Each directory carries the exact commands; this table says which toolchain is needed and links there.

Example	Teaches	Command (observed)	Reference
examples/calculator-web	A browser shell that calls the generated scalar package by stable ID and renders normalized semantic failures	Standalone CLI is enough: semaprax build examples/calculator-project/semaprax.toml --target web -o /absolute/out/web → built project web package …. Then follow the directory's README	Wasm Scalar Exports v1
examples/calculator-rust	Three separate Cargo consumers of a generated safe-Rust SDK: direct exports, a host-implemented callback, and the six Project exports	Cargo-driven, not a semaprax subcommand; the setup package and its environment variables are in the directory's README. examples/calculator-rust/callback.spx itself checks (semaprax check examples/calculator-rust/callback.spx), but run reports error[SPX-B103]: native Rust imports are unavailable for the ordinary native target	Native Rust Interop v1
examples/owned-data-rust	A single-file owned-byte API (examples/owned-data-rust/owned_data.spx) plus the Cargo setup and consumer packages for its generated safe-Rust SDK	The .spx subject alone runs: semaprax run examples/owned-data-rust/owned_data.spx → 0. SDK generation is the Cargo setup package in this directory, not a semaprax subcommand	Public Owned Data API v1
examples/frame-payload-web	A Node and browser npm consumer that pins stable-ID access through runtime.functions[...] and replays the shared corpus	Use the private semaprax-full for the --target npm route the directory's README documents. The standalone CLI does emit something for this manifest — semaprax build examples/frame-payload-project/semaprax.toml --target npm -o /absolute/out/npm → built Project v2 npm package … — but that output announces itself as a Project v2 package, not the Project v8 owned-data package this consumer reads	Public Owned Data API v1
examples/frame-payload-rust	A safe-Rust consumer of the generated owned-data SDK, reading the same corpus through Serde	Needs the private semaprax-full: the standalone CLI answers build --target rust is unavailable in the standalone crates.io package; use the unpublished semaprax-full toolchain CLI. Commands are in the directory's README	Public Owned Data API v1
examples/embedding-api	A standalone Rust consumer of the public semaprax::embedding_api facade, covering checked source, canonical formatting, graph rendering, warnings, malformed input and API-major refusal	cargo run --locked --offline from the directory; see its README	Embedding API v1

Semantic change input

Example	Teaches	Command (observed)	Reference
examples/rename.spatch	A three-line semantic patch that renames math.add in examples/meaning.spx and requires no new effects	Read-only preview: semaprax impact examples/meaning.spx examples/rename.spatch. As committed it fails closed with error[SPX-G409]: stale semantic patch: expected graph GRAPH_REVISION, current graph sha256:42aeae… — its first line tells you to substitute the current revision, which semaprax check examples/meaning.spx prints. With the real revision substituted into a copy of the patch, impact emits a semaprax.semantic-impact.v1 document whose source_consumers list names the math.add declaration and its one reference site in app.main	Semantic Patch v2

Patch application (semaprax patch) rewrites the file you pass it. Copy examples/meaning.spx somewhere else before trying it, so the committed example stays canonical for tests/examples.rs.

Keeping this index honest

tests/examples.rs carries a readme_index module that fails if a committed example is missing from this file, or if this file names a path under examples or a relative link that does not resolve:

cargo test --locked -p semaprax --test examples

Add a row here in the same change that adds an example.