YVEX System Architecture

Verified source, compiled meaning and isolated computational execution.

Documentation

YVEX turns exact upstream model sources into admitted computational execution. Its compiler seals meaning and physical work; its runtime owns engine/session lifetimes; its backends execute admitted operations. Evidence observes these boundaries without becoming an execution owner.

System context

Static figure · Editable source

Editable context source. Operators, C consumers and application providers enter through typed interfaces. YAI owns semantic work outside this boundary. Hardware executes the admitted computation; a transport adapter does not confer additional model capability.

Source to verified execution

Static figure · Editable source

Editable compiler source.

The signature lifecycle is a fork and join, not a linear IR-to-GGUF conversion:

1. Source and family interpretation authenticate provenance and interpret model meaning.
2. Computation lane seals semantic/program IR and lowers legal operations.
3. Parameter lane derives transformations, quantization, layout and an admitted artifact.
4. Parameter join binds symbolic computation to exact package terminal truth.
5. Deployment admits numerical/implementation classes and resource requirements.
6. Engine generation owns immutable executable resources; sessions own state.
7. Scheduler and backend select real ready work and execute admitted operations.
8. Result and evidence publish only after the required identity/lifecycle checks.

Logical planes

Interpret and compile

• Source and Provenance — Authenticate the exact source before interpreting or executing it.
• Model Semantics and Admission — A family interprets a model; shared machinery owns its execution lifetimes.
• IR and Compilation — Seal computation and parameter lineage before runtime allocation.
• Representation, Quantization and Artifacts — A logical model can have several exact physical representations.
• Artifact and Package Admission — Authenticate a complete package before publishing a usable mapping.

Admit and execute

• Deployment and Specialization — Admit an implementation and resource envelope without changing artifact identity.
• Engine and Session Runtime — A host retains engines; each session owns independent mutable execution.
• Computational State — Sessions isolate state; transactions coordinate publication across distinct geometries.
• Scheduling and Resources — Schedule real ready work and account for resources without inventing physical width.
• Backend and Device Execution — Execute admitted work; do not rediscover model semantics in kernels.

Produce and integrate

• Generation and Decoding — Generate tokens through compiled model work and transactional publication.
• Speculation and Finite Execution — Shared runtime machinery supports distinct result semantics.
• Interfaces and Protocols — Clients project typed system behavior without acquiring execution ownership.

State and lifetime view

Object	Owns	Survives / expires with
Source snapshot	Exact provenance and tensor basis	Immutable source identity
Logical model/program	Interpreted computation and legal effects	Compiled identity
Representation/artifact	Exact encoded parameters and package facts	Authenticated stored bytes
Deployment specialization	Admitted implementation and resource choices	Compatible hardware/workload envelope
Engine generation	Executable resources and stale-reference boundary	Load/unload/drain
Session	Mutable attention/recurrent/component state	Session lifecycle and its parent generation
Transaction/result borrow	Candidate publication and transient value validity	Atomic commit/abort or producer reuse

Captured prefixes are identity-bound snapshots, not generic semantic memory. Persistent cognitive state E and unfinished deliberation L remain research. A client disappearing does not transfer or destroy host authority; cancellation and retirement follow the runtime contract.

Execution and generation view

The scheduler chooses ready progress. An execution batch records actual selected rows; an expert worklist groups their routed populations. CUDA owns buffers, submission, synchronization and equivalent launch geometry below admitted execution. It does not infer topology from a family name or tensor dimensions.

Ordinary generation runs tokenizer/admission → prefill → decode/logits → sampling → transactional publication. Speculation adds target verification; finite readout supplies candidate tokens instead of sampling; native finite models compute typed results directly. Media composition uses admitted component programs, not a second generic runtime.

Trust and support view

“Supported model” means a bounded combination of source, representation, deployment, execution and evidence. Family recognition, a complete artifact, component numerics, model behavior and release qualification are separate gates. Missing semantics, stale generations and unsupported exact requests fail closed.

See Invariants, Contracts, family evidence and current Status.

Source ownership and dependency direction

Core/public ABI → source/artifact/model/tokenizer → compiler/graph → materialization/runtime → backend → generation → evaluation. Domain facts flow through typed reports to renderers and CLI I/O.

Authority boundaries

Boundary	Current owner
Source provenance, inventory, payload trust	src/source/
Remote provider discovery and remote representation records	src/accounts/, src/model/remote.c, include/yvex/catalog.h
Local acquired-source and admitted-package catalogs	src/model/catalog.c, src/model/artifacts/, include/yvex/catalog.h
Family source facts, coverage and logical lowering	src/model/families/
Authenticated finite-frontier text/token construction	src/tokenizer/finite_input.c and source-owned recipes under src/tokenizer/families/
Artifact-neutral parameter transformation, transform binding and representation policy	src/model/compilation/, model compilation owners
GGUF container, qtypes, writer, layout	src/gguf/
Artifact snapshot, integrity, admission, bounded ranges, and package mapping/materialization session	src/artifact/, include/yvex/internal/artifact.h
Backend/model executable weight materialization	src/model/materialization.c, include/yvex/materialization.h
Semantic Model IR, native typed programs, execution lowering, physical programs and state protocols	src/model/compilation/, src/ir/, src/graph/
Runtime binding, model engines, specialization, sessions, residency, scheduler	src/runtime/
Device capability, memory, kernels, launch graphs	src/backend/
Autoregressive composition	src/runtime/generation.c and typed generation owners
Persistent host, live engine observation, routing, protocol, telemetry	src/server/
OpenAI-compatible projection	src/server/openai/ and src/provider/
Command metadata and projections	config/operator/registry.json, generated descriptors, src/cli/

Family source interpretation and graph recipes occupy separate compilation levels, described by family integration. Generic runtime and backend owners consume typed plans, not family-name switches. Pure-SSM execution now has the exact CPU boundary documented by the Mamba2 record; this does not imply hosted conversation or CUDA SSM support.

The exact source-file ownership manifest is config/source_owners.tsv. It is also the sole handwritten production build-membership list; a checked deterministic projection supplies Make product classes. Contributor-facing layout and build ownership rules are in Source and Module Ownership.

Next reads

Invariants · Contract map · Evaluation · Tasks