The Manifesto

Section I

The Los Alamos Principle

In 1943, a small group of physicists gathered in the New Mexico desert to solve an "impossible" problem. They had no powerful computers. No decades of established methodology. What they had was complete knowledge of the physics, meticulous planning, and absolute precision in implementation.

They succeeded because they understood a fundamental truth: when you know everything about your problem at design time, you can build solutions that seem impossible to those constrained by runtime thinking.

When you carve the solution in stone before main() runs, you achieve what appears magical to those still building with runtime scaffolding.

Section II

Cathedral vs. The Bazaar: A Type System Perspective

Eric Raymond taught us about two development models: the Cathedral (designed, planned, structured) versus the Bazaar (emergent, dynamic, flexible). We propose a third dimension to this metaphor: when the architecture crystallizes.

class Tensor {
    void* data;
    vector<int> shape;
    string dtype;

    void* index(vector<int> coords) {
        return data + calculate_offset(coords);
    }
};

template<uint32_t batch, uint32_t seq,
         uint32_t hidden, uint32_t heads>
struct AttentionTensor {
    static constexpr auto dims =
        dimensions<batch,seq,hidden,heads>;
    using dtype = float16_t;

    template<uint32_t b,uint32_t s,
             uint32_t h,uint32_t n>
    DEVICE dtype& at() {
        static_assert(b<batch && s<seq);
        constexpr uint64_t offset =
            compile_time_index<dims,b,s,h,n>();
        return data[offset];
    }
    dtype* data;
};

Maximum flexibility. Minimum performance guarantees — versus — everything known at compile-time, zero runtime overhead, and the compiler sees the entire universe of your computation before generating a single instruction.

This is the essence of Cathedral Architecture: crystallizing decisions into the type system, transforming runtime computation into compile-time verification.

Section III

The Four Pillars of Cathedral Architecture

Pillar I — Complete Compile-Time Knowledge

Consider the humble operation thread_id / sequence_length.

__device__ uint32_t batch =
    thread_id / seq_len;

template<uint32_t divisor> struct Division {
    DEVICE static uint32_t div(uint32_t value) {
        if constexpr (is_power_of_2(divisor)) {
            return value >> log2_ct(divisor);
        } else {
            constexpr auto params =
                barrett_params(divisor);
            return (value * params.multiplier)
                       >> params.shift;
        }
    }
};

Pillar II — Zero-Cost Abstractions as a Hard Guarantee

virtual float compute(const Tensor& t) = 0;

struct FastTensor : Tensor {
    float compute(const Tensor& t) override;
};

template<TensorConcept T>
DEVICE float compute(const T& tensor) {
    return tensor.compute_impl();
}

Guaranteed zero cost because: template instantiation = compile-time dispatch; DEVICE inline = forced inlining; concept checking = compile-time verification; no runtime polymorphism = no indirection.

Readable Compile-Time Diagnostics — The Cathedral Error Model

Cathedral Architecture doesn't just fail at compile-time — it fails informatively. A plain static_assert tells you that something is wrong. Cathedral error architecture tells you exactly what went wrong, with the actual values that caused it, baked directly into the type system.

static_assert(A::dims[1] == B::dims[0],
              "Matrix dimension mismatch");

// → error: Matrix dimension mismatch
// You know something is wrong. You don't know what the values were.

static_assert_printer<
    A::dims[1] == B::dims[0],
    MatMulError::dimension_mismatch,
    static_assert_printer_val_inserter<A::dims[1], B::dims[0]>
>::impl;

// → error: 'nonexistent_value' is not a member of
// 'static_assert_printer_impl<MatMulError::dimension_mismatch,
//  static_assert_printer_val_inserter<512, 768>>'
//
// You see the error enum. You see 512 vs 768. You fix it
// without running a single instruction.

Pillar III — The Type System as Computational Graph

template<ModelConfig config>
struct TransformerBlock {
    using qcur      = MatMul<config, attn_q, attn_norm_mul>;
    using kcur      = MatMul<config, attn_k, attn_norm_mul>;
    using vcur      = MatMul<config, attn_v, attn_norm_mul>;
    using qcur_rope = Rope<config, qcur, inp_pos, rope_freqs>;
    using kcur_rope = Rope<config, kcur, inp_pos, rope_freqs>;
    using kq        = MatMul<config, k_view, q_permute>;
    using kq_soft   = Softmax<config, kq, kq_mask>;
    using kqv       = MatMul<config, v_view, kq_soft>;
    using output    = MatMul<config, attn_output, kqv_merged_cont>;
};

• Dependencies are compile-time relationships
• The compiler can see the entire compute graph
• Memory planning is constexpr — exact requirements computed by the compiler
• Impossible to construct invalid graphs — the type system won't allow it

Pillar IV — Cathedral Mathematics: Computation as Proof

void matmul(Tensor a, Tensor b, Tensor out) {
    assert(a.shape[1] == b.shape[0]);
    assert(out.shape[0] == a.shape[0]);
    assert(out.shape[1] == b.shape[1]);
}

template<Dims A, Dims B>
    requires(A::dims[1] == B::dims[0])
auto matmul(Tensor<A> a, Tensor<B> b)
    -> Tensor<Dims<A::dims[0], B::dims[1]>>
{
}

If the code compiles, the mathematics is correct. This isn't just type safety — this is mechanical verification of mathematical correctness. The Cathedral transformation: "Test that your matrix dimensions match" becomes "Prove that your matrix dimensions match, or the program doesn't exist."

Section IV

Division Elimination as Exemplar

The Division Elimination whitepaper demonstrates Cathedral thinking applied to one of computing's most fundamental operations. Integer division costs 20–40 cycles on GPUs. Every tensor indexing operation requires multiple divisions. This overhead dominates lightweight kernels.

• Runtime thinking: "Division is expensive, we'll try to avoid it where we can."
• Cathedral thinking: "We know at compile-time which divisors are constant, which are powers-of-2, and which are runtime values set once per request. Therefore division can be eliminated entirely."

template<uint32_t divisor> struct Div {
    constexpr uint32_t operator()(uint32_t value) {
        if constexpr (is_pow2(divisor))
            return value >> log2(divisor);
        else
            return barrett_reduce(value);
    }
};

This exemplifies the Cathedral approach: complete knowledge → zero cost → type safety → mathematical proof. When you build the cathedral properly, the "impossible" becomes routine.

Section V

Why Now? The Technology Convergence

Cathedral Architecture became possible only recently due to the convergence of five separate technological threads.

Section VI

The Cathedral Development Model

Design Principles

• Encode invariants in types. If a property can be expressed as a constraint, it must be expressed as a constraint.
• Compute once, use forever. Static constexpr computation is not repeated — it is crystallized.
• Fail at compile-time, not runtime. A program that compiles incorrectly does not exist.
• Let the compiler see everything. Opaque implementations defeat the Cathedral. Transparency is strength.

Development Workflow

Write → Test → Profile
     → Optimize → Repeat

Design → Encode → Verify
       → Compile → Deploy

The Cathedral workflow frontloads effort. Longer design phase. Types capture all invariants. static_assert everything. The payoff: zero runtime debugging, zero "works on my machine" bugs, zero performance surprises, provably correct code.

The Leaf Class Cardinality Principle

Cathedral Architecture's emphasis on compile-time computation raises a legitimate concern: template instantiation can explode combinatorially. The solution is minimizing leaf class cardinality through strategic type propagation.

What Gets Templated Where

• Top Level — Full Templating: Model architecture selection, quantization strategies, memory layout decisions, workspace computation, type construction.
• Middle Level — Selective Templating: Tensor dimensions where varying, data type transformations, memory access patterns.
• Leaf Level — Minimal Templating: Input/output types ONLY. NOT the full configuration space.

Section VII

Cathedral Anti-Patterns

What Cathedral Architecture is NOT:

• Template metaprogramming for its own sake. Cathedral uses templates to encode domain knowledge, not to compute Fibonacci numbers at compile-time.
• Over-generalization. Cathedral specializes aggressively when specialization enables optimization.
• Compile-time computation of runtime values. Cathedral distinguishes what CAN be compile-time (architecture) from what MUST be runtime (data).
• Type gymnastics that obscure intent. If you need a PhD to understand the types, you're doing it wrong.
• Stringly-typed compile-time errors. A string is not a diagnostic. Cathedral errors carry the values that caused them.

What Cathedral Architecture IS:

• Encoding domain knowledge in types
• Eliminating runtime overhead through compile-time reasoning
• Proving correctness through type constraints
• Specializing aggressively for known cases
• Letting the compiler see the full computation
• Minimizing leaf instantiation cardinality
• Producing typed, value-carrying compile-time diagnostics

Section VIII

The Future of Cathedral Architecture

Near-Term Evolution

• Auto-tuning through compile-time search. The compiler tries multiple implementations and selects the fastest — at compile-time.
• Formal verification integration. Types that carry formal proofs of thread-safety, deadlock-freedom, or numerical stability.
• Cross-kernel optimization. Pipeline-level type analysis enabling automatic kernel fusion and transfer minimization.
• Hardware-specific specialization. Architecture-aware templating that generates maximally optimal code per target.

Long-Term Vision

• Programs are proofs. The type system verifies correctness properties that currently require runtime testing or manual review.
• Performance is guaranteed. "Zero-cost abstraction" becomes a formal, verifiable property rather than a compiler-dependent hope.
• Bugs are eliminated. Type errors caught at compile-time → no runtime errors → no CVEs from memory corruption.
• Optimization is automatic. Complete compiler information → globally optimal decisions → human expertise encoded once, applied everywhere.

Section IX

Call to Action

Cathedral Architecture is not just a technique — it's a mindset. A recognition that the boundary between compile-time and runtime is not fixed by the language, but chosen by the programmer.

if (condition) { }

void* ptr = malloc(size);

virtual void compute() = 0;

static_assert(condition,
    "something went wrong");

if constexpr (condition) { }

static byte storage[size];

template<typename T> void compute() { }

static_assert_printer<
    condition,
    ErrorEnum::specific_failure,
    static_assert_printer_val_inserter<values>
>::impl;

The question is not "Can I move this to compile-time?" The question is "Why haven't I moved this to compile-time?"

Join the Cathedral

This is not about adopting a library or framework. This is about how we think about performance-critical systems. When you stare at your template metaprogramming code and see not complexity but crystallized knowledge — you're thinking Cathedral. When your compiler errors carry the exact values that caused them and you fix the bug without running a single line — you're thinking Cathedral.

Section X

The Cathedral Covenant

We, the cathedral builders, commit to:

1. Encode knowledge in types — What can be proven shall be proven.
2. Eliminate runtime uncertainty — What can be decided shall be decided at compile-time.
3. Guarantee zero cost — Abstractions shall have provably zero overhead.
4. Prove correctness — Type systems shall verify properties, not just prevent crashes.
5. Share knowledge freely — Cathedral techniques shall be open, documented, teachable.
6. Minimize leaf cardinality — Compute liberally at the top, instantiate conservatively at the leaves.
7. Diagnose with precision — Compile-time errors shall carry the values that caused them, not strings that describe them.

Appendix A

Cathedral Reading List