Semantic Programming Wiki

Semantic-first compilation, Universal AST, native x86-64 and the road to true selfhosting.

SWC is the current native Windows compiler path around the Semantic Programming representation used by Code Transpiler. The project is built around one core idea:

SemanticProgram = Universal AST = canonical IR

Source languages are lowered into a language-independent semantic program. Backends consume that semantic graph directly and either emit source, validate semantic contracts, or lower to native machine code and object/executable formats.

The big picture

flowchart LR A[Source language] --> B[Frontend] B --> C[SemanticProgram / UAST] C --> D1[Source emitter] C --> D2[Semantic runtime] C --> D3[Native x86-64 backend] D3 --> E[COFF .obj] E --> F[PE .exe] C --> G[.se / .sp / .spz]

What this wiki covers

how the Semantic formats relate to each other;
how the Universal AST is used as the canonical program representation;
how native Windows x86-64 compilation works;
how the current per-unit object build/debug pipeline works;
what true selfhosting means for ;
how to diagnose unresolved bindings, member layouts and backend gaps;
how to contribute without hiding unsupported semantics behind fallbacks.

```html

SWC and true selfhosting

SWC is the native compiler path for Semantic Programming. Its purpose is not merely to translate Semantic source into another high-level language, but to compile the canonical SemanticProgram / Universal AST directly into native Windows x86-64 programs.

The compiler therefore sits directly on top of the same semantic representation used throughout the Semantic Programming toolchain:

Semantic source → SemanticProgram / UAST → native x86-64 → COFF → PE

This is an important distinction. SWC is not intended to be a wrapper around another language compiler and it is not a source-to-source bootstrap shortcut. The native backend consumes the language-independent semantic graph, lowers supported operations to machine code, creates Windows COFF object files and ultimately produces PE executables.

The SWC compiler pipeline

A native SWC compilation conceptually consists of the following stages:

Load Semantic source. The compiler reads the Semantic program that is to be compiled. The source may originate from Semantic source files or from one of the serialized Semantic representations used by the toolchain.
Construct or load the canonical SemanticProgram. Program meaning is represented by the Universal AST. The backend does not treat the surface syntax as the canonical program representation.
Resolve semantic relations. Bindings, declarations, types, members, calls, fields and other relations required by native lowering must be resolved before code generation can safely continue.
Lower supported semantics to native x86-64. The native backend transforms Semantic operations into Windows x86-64 machine code. Unsupported operations are compiler errors rather than silently ignored constructs.
Build COFF object units. Successfully lowered compilation units are written as .obj artifacts. Persisting object files per unit makes the bootstrap process easier to inspect and allows failures to be isolated to the unit that introduces an unsupported semantic requirement.
Link the final PE executable. The generated objects are combined into a native Windows executable that can run without requiring the original source compiler process.

flowchart TD A[Semantic source] --> B[Frontend / loader] B --> C[SemanticProgram / Universal AST] C --> D[Binding and layout resolution] D --> E[Native semantic lowering] E --> F[x86-64 machine code] F --> G[COFF .obj units] G --> H[PE linker] H --> I[Native SWC .exe]

Why SWC matters for selfhosting

The long-term purpose of SWC is true compiler selfhosting. That means the compiler itself must be expressible as genuine Semantic source and the resulting native compiler must be capable of compiling the same compiler source again.

The intended bootstrap chain is:

stage1.exe -selfhost.se stage2.exe
stage2.exe -selfhost.se stage3.exe

Here, stage1.exe is the existing trusted compiler used to start the bootstrap. It compiles the Semantic implementation of SWC, represented here by -selfhost.se, and produces stage2.exe.

The critical step is the second compilation. stage2.exe must itself understand the Semantic compiler source, execute the same semantic compilation pipeline and produce stage3.exe. At that point the compiler is no longer merely capable of compiling ordinary Semantic programs: it is capable of compiling its own implementation.

Selfhosting is proven by compilation, not by packaging.

What counts as true selfhosting?

For SWC, selfhosting specifically means that the next compiler generation is produced from the actual Semantic implementation of the compiler.

A valid bootstrap therefore requires:

the compiler implementation to exist as genuine Semantic source;
SWC to parse or load that program into the canonical SemanticProgram / UAST;
the required compiler semantics to be supported by the native backend;
native x86-64 code to be generated from those semantics;
real COFF object files and a PE executable to be produced;
the generated compiler to be able to repeat the process itself.

Several shortcuts deliberately do not satisfy this definition. A bootstrap is not considered selfhosting if the generated executable merely contains, extracts, copies or replays an already compiled compiler binary. Likewise, replacing unsupported compiler semantics with silent fallbacks would make the bootstrap result misleading.

The selfhosting work therefore follows the same principle as the rest of the native backend:

Fail closed instead of pretending that unsupported semantics succeeded.

Stage 2 and Stage 3

The distinction between Stage 2 and Stage 3 is useful because it exposes whether the new compiler is actually operational.

Stage 1 is the trusted seed compiler used to compile the Semantic SWC implementation.
Stage 2 is the first compiler executable produced from that Semantic implementation.
Stage 3 is produced by Stage 2 compiling the compiler implementation again.

Reaching Stage 2 demonstrates that the existing compiler can compile the Semantic implementation. Reaching Stage 3 demonstrates something stronger: the compiler produced from Semantic source is itself capable of performing the compiler bootstrap.

flowchart LR A[Stage 1 compiler] -->|compile selfhost.se| B[Stage 2 compiler] B -->|compile selfhost.se| C[Stage 3 compiler] C --> D[Compare / validate bootstrap result]

Object-by-object bootstrap development

Compiler selfhosting exercises a much larger part of the language than small native test programs. It stresses function calls, data structures, member access, control flow, bindings, layouts, runtime interactions and many other semantic relationships at once.

For that reason, the current SWC workflow builds and preserves native object artifacts as individual compilation units succeed. Instead of treating the compiler as one opaque all-or-nothing build, the bootstrap can be inspected at the point where a specific unit fails.

This makes it possible to distinguish failures such as:

an unresolved semantic binding;
an unknown declaration or callable target;
a missing member or field layout;
an unsupported UAST node or semantic facet;
a native lowering operation that has not yet been implemented;
a relocation or object-generation problem;
a link-time dependency that is still missing.

This incremental approach is important for a selfhosting compiler because every newly supported semantic construct reduces the distance between compiling isolated native programs and compiling the compiler itself.

Selfhosting as a backend completeness test

Selfhosting is also a practical test of the Semantic architecture itself. Since SWC operates on the canonical Universal AST, every construct needed by the compiler must have a well-defined representation and a native interpretation.

If the compiler source expresses a concept that cannot be represented faithfully in the UAST, the semantic model is incomplete. If the UAST represents it correctly but SWC cannot lower it, the native backend is incomplete. If the backend silently discards the information, the resulting compiler cannot be considered a trustworthy bootstrap.

This is why the selfhosting effort is closely connected to the project's core design principles:

One semantic truth: SWC compiles the canonical UAST rather than inventing a second native-only program model.
Fail closed: unsupported semantics stop compilation with a visible error.
No fake success: semantic information must not disappear during native lowering.
Deterministic transport: loading the same Semantic program through different supported Semantic formats should preserve its meaning.
Incremental progress: successful native units are retained and can be inspected independently.
Real bootstrap: the final proof is a compiler produced by a compiler produced from Semantic compiler source.

SWC development on GitHub

The Semantic Programming source code and ongoing compiler development are available on GitHub. The repositories contain the implementation work around the Semantic representation, tooling and native compiler path:

Semantic Programming Language on GitHub →

For contributors working on SWC, the most useful areas to understand first are the Universal AST, semantic binding and layout resolution, native lowering, COFF object generation, PE linking and the selfhosting build/debug workflow.

The end goal can be summarized in one line:

Semantic compiler source → SWC → native compiler → SWC again

When that chain works without embedding or replaying a prebuilt compiler, SWC has reached true native selfhosting.

```

Start here

Read Getting Started for the practical build flow.
Read Architecture to understand the canonical IR.
Read Semantic Formats for .se, .sp and .spz.
Read Native Compilation for x86-64/COFF/PE.
Read Selfhosting for the bootstrap definition and milestones.
Read Object Build & Debugging when working on the current compiler bootstrap.
Read ChatGPT Plugins for AI-assisted Semantic tooling.

Design principles

One semantic truth. UAST is canonical; compatibility views are derived.
Fail closed. Unknown or unsupported semantics must produce an explicit error.
No fake success. A backend must not silently drop fields, facets or relations.
Deterministic transport. Semantic formats are intended to preserve the same program meaning.
Incremental native progress. Object artifacts are persisted as soon as a unit succeeds.
Selfhosting means selfhosting. No embedded seed executable in the final bootstrap proof.

Next: Getting Started â†’