libvct-spec/spec/000-overview.md

000 — Overview

• Status: Draft
• Normative language: MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

1. Purpose

libVCT (the Vox C Transpiler Library) is a compiler library written in D. Given a program's IR, libVCT optimizes that IR, transpiles it to C17, and drives a system C compiler to produce an object file. An alternate backend emits textual LLVM IR instead of C.

libVCT is a library, not a compiler. A frontend embeds it, builds IR through its builder API, and receives either C source or LLVM IR back. libVCT never links object files into an executable; that is the caller's job, with the single opt-in exception of -mangled mode (see 010 — Driver & CLI).

2. The two-stage IR thesis

libVCT is organized around two IRs:

• HIR: a high-level, tree-shaped AST. The frontend constructs it; libVCT annotates it in place with traits. HIR performs discovery and small, cheap folds.
• VIR: a low-level SSA/CFG instruction IR. VIR performs the heavy transformations and performs no discovery; it is a strict consumer of the traits HIR produced.

The design thesis: because HIR hands VIR a complete, annotated "dictionary" of facts, VIR can skip analysis and go straight to transformation. HIR's cheap folds cascade and parallelize per function, and the VIR that results is smaller and faster to optimize. The intended result is LLVM-class codegen quality at materially lower compile time.

3. Goals

1. Codegen quality is the headline. Generated code quality takes priority over compile speed.
2. Two-stage optimization. HIR performs small folds and trait derivation; VIR performs large transformations.
3. Trait-driven VIR. VIR never re-analyzes. Every fact it uses is an attribute, relationship, or request supplied by HIR.
4. Parallel, cascading HIR. HIR passes run per function in parallel and cascade to a fixpoint.
5. Compiler-friendly C. The C backend always emits C written to be pattern-matched by GCC and Clang.
6. Deterministic output. The same input and configuration produce byte-identical output, regardless of thread count.

4. Non-goals (v1)

• Linking. libVCT produces object files; linking is the caller's job. The sole exception is -mangled mode.
• Windows / MSVC. v1 is Linux/POSIX-first and supports GCC and Clang only.
• LLVM bitcode. The LLVM backend emits textual .ll only; the caller runs llvm-as.
• LLVM debug metadata. There is no !llvm.dbg in v1. Debug mapping exists on the C path via #line directives.
• A hand-authored VIR. VIR is internal and intentionally hostile to hand-authoring. A textual form exists solely for tools and round-trip tests; it is not a supported authoring surface.
• Consuming LLVM IR or Vox's existing IR. libVCT owns its IR definition.

5. Glossary

Term	Meaning
HIR	High-level IR: the frontend AST, annotated in place with traits.
VIR	Vox IR: a low-level SSA/CFG instruction IR.
Trait	The union of an Attribute, Requests, and Relationships attached to a node.
Attribute	A fact about a node (type, value, mutability, …).
Request	An attribute-derived suggestion from HIR to VIR.
Relationship	A directed edge between nodes, traceable up and down.
Cascade	The chain of HIR rewrites triggered by a single fold.
Lowering	The "middleman" that translates annotated HIR into VIR SSA.
Remark	An optimizer decision record emitted for diagnostics.

6. Conformance

An implementation conforms to this specification if it satisfies every MUST and MUST NOT requirement in every specification file listed in §8. SHOULD requirements may be violated only with a documented, deliberate reason. MAY requirements are optional.

Where this specification and an implementation disagree, this specification is authoritative. Where a later specification file refines an earlier one, the later file is authoritative for its subject.

7. Determinism guarantee

For a fixed Config and a fixed input, libVCT MUST produce byte-identical output on every run, independent of thread count. This guarantee binds every stage: HIR optimization, lowering, VIR optimization, and both backends. Determinism is a correctness property, not an optimization.

8. Specification index

File	Subject
000 — Overview	Purpose, thesis, goals, glossary, conformance, determinism.
001 — Architecture	Modules, data flow, public interfaces, boundaries.
002 — Traits	Attributes, requests, relationships, representation, staleness.
003 — HIR	HIR node model, builder contract, textual format, defer.
004 — HIR Optimizer	Pass framework, cascade, parallelism, comptime, budgets.
005 — Lowering	HIR → VIR translation, SSA construction, memory model.
006 — VIR	VIR SSA/CFG model, type system, instructions, invariants.
007 — VIR Optimizer	Pass framework, analyses, pipeline, request handling.
008 — C Backend	VIR → C17: out-of-SSA, compiler-friendly C, layout, ABI.
009 — LLVM Backend	VIR → textual LLVM IR.
010 — Driver & CLI	Pipeline orchestration, flags, C compiler invocation.
011 — Diagnostics	Diagnostics service, source maps, channels, ICE policy.
012 — Testing	Test layers, fixture harness, oracle, fuzzing, matrix.
013 — Build & Packaging	Toolchain, artifacts, API surfaces, memory ownership.
014 — Worked Example	End-to-end trait/request walkthrough (normative).
015 — Open Questions	Deferred items and future work.

9. How to read this specification

Each file is a self-contained specification of one subject. Cross-references name the target file directly (for example, "see 002 — Traits") so that the set can be read out of order.

Specifications state observable and required behavior (what a component must do and what guarantees it must uphold) rather than prescribing internal implementation. Where a component's internal design is load-bearing for correctness (for example, the SSA construction algorithm in 005 — Lowering), the required properties are stated normatively and the named algorithm is given as the reference method.