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](010-driver-cli.md)).

## 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](000-overview.md) | Purpose, thesis, goals, glossary, conformance, determinism. |
| [001 — Architecture](001-architecture.md) | Modules, data flow, public interfaces, boundaries. |
| [002 — Traits](002-traits.md) | Attributes, requests, relationships, representation, staleness. |
| [003 — HIR](003-hir.md) | HIR node model, builder contract, textual format, `defer`. |
| [004 — HIR Optimizer](004-hir-optimizer.md) | Pass framework, cascade, parallelism, comptime, budgets. |
| [005 — Lowering](005-lowering.md) | HIR → VIR translation, SSA construction, memory model. |
| [006 — VIR](006-vir.md) | VIR SSA/CFG model, type system, instructions, invariants. |
| [007 — VIR Optimizer](007-vir-optimizer.md) | Pass framework, analyses, pipeline, request handling. |
| [008 — C Backend](008-c-backend.md) | VIR → C17: out-of-SSA, compiler-friendly C, layout, ABI. |
| [009 — LLVM Backend](009-llvm-backend.md) | VIR → textual LLVM IR. |
| [010 — Driver & CLI](010-driver-cli.md) | Pipeline orchestration, flags, C compiler invocation. |
| [011 — Diagnostics](011-diagnostics.md) | Diagnostics service, source maps, channels, ICE policy. |
| [012 — Testing](012-testing.md) | Test layers, fixture harness, oracle, fuzzing, matrix. |
| [013 — Build & Packaging](013-build-packaging.md) | Toolchain, artifacts, API surfaces, memory ownership. |
| [014 — Worked Example](014-worked-example.md) | End-to-end trait/request walkthrough (normative). |
| [015 — Open Questions](015-open-questions.md) | 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](002-traits.md)") 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](005-lowering.md)), the required properties are stated normatively and the named
algorithm is given as the reference method.