ARCHITECTURE · SOURCE, MEANING, AUTHORITY

A program model that agents can query without reconstructing meaning from text.

Stable identity first. Source edits second.

In v0.10.1, stable identities connect readable source, checked HIR, semantic context, candidate review and admitted execution profiles. The release also contains opt-in authenticated HIR reuse and separately scoped source work on owned-record updates and Claude repair. These profiles retain their own gates; a green release does not grant new host authority or make every combination public.

semaprax://architecturev0.10.1
entity     Semaprax
status     beta
snapshot   d3fa1da
authority  github.com/wavect/semaprax

How does Semaprax work?

Semaprax checks readable .spx source and resolves it into HIR, its typed compiler representation. Source and semantic identities bind queries, law obligations, candidate changes and execution to the program that was inspected. Coding agents can use the harness around this core; runtime Agents separately decode proposals, authorize effects and reduce state under explicitly supplied host capabilities.

Stable identity first. Source edits second.

Pick a stage to highlight its parts of the architecture below.

Canonical source and stable identity

Readable .spx remains the canonical Git representation. An explicit @id identifies a declaration through supported display-name changes. Compiler-derived revisions bind source and the selected prelude; graph encodings expose those facts without replacing the source.

Bounded context and compact projections

Select a declaration, direction, depth, node count and byte limit. Task context and text, binary or model-text projections preserve exact replay against the selected facts. The native semantic context broker can use Graft or Graphify for additional repository navigation without treating an external index as compiler truth. Persistent semantic-cache entries are private compiler-created HIR, bound to source and installation trust. Warm open reauthenticates and replays the Project. A stale or evicted entry refuses rather than silently substituting a cold result; broader incremental compilation and portable caches remain open.

Source laws and protected implementation repair

Native law declarations give persistent identities to contract and relational requirements. A separately selected LawSet fixes the complete inventory and strict policy. Installed Lean/Z3 adapters prove admitted scalar, modular, structured and list laws; stale, unsupported, unknown and disproved results remain distinct. Candidate repair must satisfy the preserved requirement.

Semantic changes with revision checks

Inspect context, derive a candidate, preview impact and review, replay checks, then authorize application. Bounded expression replacement, structural edits and specified composition each retain their operation and revision limits. Source law edits and implementation repairs follow separate protection rules.

Managed publication and embedding

Managed workspace generations, candidate evidence and Project revision stores bind publication to the checked candidate. The Rust embedding API offers bounded inputs and opaque sessions. Multi-file validation alone does not update arbitrary files, Git refs or editor buffers.

Everyday language and collections

Admitted profiles include records, variants, classes, inheritance, generics with scoped argument inference, Option/Result, loops, iterators, function values, strings and bytes. Immutable List<i64> adds persistent nil/cons/uncons operations. General constraints and arbitrary combinations still require their own admission. vec_update_field<Row>(rows,index,value,"field") consumes an admitted owning vector and updates one exact Copy scalar slot. Flat, invariant-free owned-leaf records, literal selectors and whole-root loans remain required. The tagged specification keeps executable qualification pending; nested records, dynamic selectors and general mutable references are not admitted.

Ownership and callback lifetimes

Owned values, borrowed views, cleanup plans and selected resource compositions are executable. Narrow closure profiles include owned Bytes captures, copied scalar snapshots, transactional mutable scalar state and synchronous borrowed-text captures. Each checks its own escape, move, rollback and cleanup rules; broader lifetime relations remain open.

Rust APIs under explicit boundary contracts

Prepared Rust API indexes select supported imports and exact Cargo inputs. Generated owner, borrowed-view and callback adapters connect checked source to real Regex/Url and Serde/iterator consumers. A same-thread Future bridge uses a caller-owned executor. Foreign assumptions remain explicit; generated glue does not prove a crate’s internals.

Typed runtime Agents

Initialize, observe, propose, decode, authorize, execute and reduce. Authorization repeats each turn and the reducer chooses Continue, Complete, Suspend or Fail. Default live routes use the interpreter; opt-in library routes accept caller-held native C11 or Core Wasm stage hosts with bounded local parity evidence.

Budgets, durable recovery and model calls

Explicit adapters supply transport, credentials and stores. Durable profiles acknowledge intent before dispatch and preserve unresolved attempts as uncertainty. Limits and receipts separate calls, work, bytes, tokens and costs. Generic host retries/failover and the bound source-model route have different contracts; the latter does not automatically switch providers or retry uncertain work.

Resumable source and owned continuations

The interpreter has bounded sequential and control-dependent yields, selected owned-Bytes carrying and authenticated durable source profiles. The public owned-Agent slice has a two-turn lifecycle and selected process-restart gates. Ordinary native/Wasm emitters still refuse yielding functions; a general scheduler and universal continuation ABI remain open.

Compiler-connected development harness

The full toolchain’s harness coordinates explicit tasks, compiler feedback, provider descriptors, per-project locks and trust, model routing, skills and bridges. Official Ponytail/Caveman bundles, Graft/Graphify adapters and RTK model views serve selected workflows. Authoritative command results remain separate from compact model-facing output. The Claude print-JSON adapter validates one bounded proposal and repeats ordinary compiler feedback. Local shell fixtures are not live Claude evidence. Host CLI authentication and organizational policy remain explicit trust inputs; CLI restriction flags are not an operating-system sandbox.

Checked development reload

A retained interpreter session admits a candidate, plans compatibility and activates it between invocations. Polling watches declared Project inputs; invalid changes leave the active revision usable. VS Code controls expose active, pending and dirty state. Source-Agent journal migration is a separate full-toolchain lane.

Application and economic-agent profiles

A reference service composes checked session, task and job decisions with a snapshot host, explicit HTTP/TLS and selected JSON-event or OTLP telemetry. The accepted Linux/Podman journey remains bounded; SQL adapters are refused. Economic Agents retain host-owned wallet, approval, signing and reconciliation boundaries.

Generated packages and local registry trust

Owned-data Project profiles and a private compiler-owned generic Wasm endpoint have generated consumer evidence. Public generic support remains unsupported and unpublished. Local signed registry metadata, held generations and lock-bound reads do not themselves provide a hosted package registry or network-fetch authority.

Proof and release provenance

The exact-tag Lean job checks a bounded formal kernel and obligation export. Release jobs separately attest five archives, verify the signed aggregate set and exercise each native installer journey before publication. These evidence chains do not prove full-language correctness, notarization or cross-host reproducibility.

One decision core, two domains

Hard screening checks confidentiality, tools, modalities, context and budgets before an advisory router sees candidates. Development phases and runtime deployments share engine code but keep separate evidence keys. Rules make zero router calls; no learned adapter is live-tested or qualified in the dated support record.

Durable turn and choice boundaries

Only an accepted settled turn can open a new route. A handoff carries at most 16 KiB state, accepted-output digests and result references, not the transcript. Delegation reserves the parent allowance and inherits its deadline. Tool/specialist choices are reauthorized against live grants and argument schemas; uncertainty halts for reconciliation.

Native command profiles and bounded data

Project v26/v28 source-command routes are native-only. v28 admits 1 MiB per String and 1 MiB combined staged output with bounded append, while file reads and capabilities keep their older bounds. std.data.json.scan validates complete UTF-8 JSON with explicit duplicate-key policy; std.pattern is a bounded ASCII byte matcher. These additions do not widen every interpreter, Wasm or public API profile.

Compiler guidance and evidence-preserving optimization

Installed diagnostic topics suggest exact imports, effect declarations, ownership repairs and admitted syntax. Manifest formatting has an explicit fmt –manifest mode. Tagged optimization work preserves identity, HIR replay, loan accounting and resource ceilings; individual source receipts and pending gates remain visible rather than implying measured whole-project speedups.

The source projection stays readable

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

Repository status at the audited snapshot

Repository snapshotd3fa1da · 2026-11-08. The v0.10.1 tag resolves to the pinned source commit. Its exact-tag CI completed successfully. This does not establish blanket production or security assurance.
Full product status55 Partial · 0 Implemented · 0 Missing
Graph and project contractCanonical source, stable IDs and checked compiler representations connect laws, semantic queries, edits and execution. Feature-selected graph and Project schemas preserve their own admission, compatibility and host-authority contracts.
Published beta releasev0.10.1 · Published 8 November 2026 at 13:43 UTC. All 97 jobs in the exact-tag release workflow passed, including six native installer journeys across five targets. Five archives and two installers ship with SHA256SUMS, five archive attestations and independently verified signed aggregate provenance. This is beta qualification, not notarization, reproducible-build assurance or a current revocation check. Exact-tag CI.
Package and API previewsThe release includes useful language, law, harness and host-integration profiles. Generated Rust/npm packages, public generic ABIs and broader platform support retain separate publication and support decisions.

Reviewed on 8 November 2026 against the published v0.10.1 commit, asset manifest and successful release workflow. The tagged handbook and channel registry still contain v0.9.0 examples; use the pinned v0.10.1 commands here. Historical benchmark results keep their original scope. The live handbook follows main and may describe later work. GitHub repository.

// DOCS

Open the Semaprax handbook

The online handbook is the English guide published from main and may cover changes after 0.10.1. Use the pinned snapshot when reproducing this release.

// REF

Primary sources for this page

Reviewed on 8 November 2026 against the published v0.10.1 commit, asset manifest and successful release workflow. The tagged handbook and channel registry still contain v0.9.0 examples; use the pinned v0.10.1 commands here. Historical benchmark results keep their original scope. The live handbook follows main and may describe later work.

  1. Compiler architecture and trust boundaries
  2. Semantic graph implementation
  3. Native source laws
  4. Strict selected-law assurance
  5. Installed Lean and Z3 profiles
  6. Harness, providers, model receipts and prompt rendering
  7. Runtime execution and current completion boundaries
  8. Resumable source continuations
  9. Source-owned Agent public entry
  10. Checked hot-reload session
  11. Reference service host
  12. Tagged changelog and release history
  13. Runtime routing, handoff and choice authority
  14. Routing support and unevaluated qualification gate
  15. Native-only resource-output command contract
  16. Strict whole-document JSON scanner
  17. Standard-library catalog and pattern scope
  18. Native Project tests and pending execution gate
  19. Owned-record scalar updates, narrowly scoped
  20. A private Claude repair adapter
  21. Reuse checked HIR with authentication
// FAQ

Questions and practical answers

Is the semantic graph a knowledge graph or RAG system?

The core graph is derived by the compiler from checked source, with stable declarations, types, contracts and relationships. The development harness can additionally use Graft or Graphify for repository navigation. Those external indexes complement the compiler’s semantic facts and do not replace its revision and validation rules.

Can an agent edit any program through semantic patches?

The toolchain exposes specific revision-bound edit operations, candidate review and replay checks. Protected law inventories keep requirements separate from editable implementation bodies. An agent must use an admitted operation and authorized application route; a context query or successful proof is not permission to overwrite arbitrary files.

Research project by Wavect: Wavect GmbH. Created by Wavect as an open-source systems research project.