# Topolei — Architecture Plan

## Core Premise

Topolei is a **Lean 4 extension** that adds cubical-transport homotopy type
theory to Lean 4 via a Rust FFI module.  On top of that foundation, it
builds a unified rendering interface where text and graphs are co-projections
of the same computational primitive: the EML cell.

Process discipline: every layer that will ultimately cross the FFI boundary
is *first* formalized in Lean as axioms and data structures.  The Rust
component then discharges those axioms at runtime via `@[extern]` /
`@[implemented_by]`.  The cubical core (Phase 1) exemplifies this — its
axiom set (eval-level equations for `eval`/`vApp`/`vPApp`/`vTransp`/…,
six glueIn/unglue face axioms, Glue-transport axioms) is complete in Lean
with zero Rust written yet.

**Step-level axioms have been collapsed.**  The Phase 1 Week 7
step↔eval bridge (`Cubical/Readback.lean`, `STATUS.md` § Week 7)
provides `CTerm.readback := readback ∘ eval .nil` and derives NbE
analogues of each step axiom.  Stream B #2d (2026-04-23) completed
the cleanup by physically deleting the now-redundant axioms.  Current
status:
- ✅ Removed from source (NbE theorems in `Readback.lean`):
  T1 `transp_id`, T2 `transp_const_id`, C1 `comp_full`, C2 `comp_empty`,
  `step_papp_plam`.
- ✅ T4 NbE coverage complete for path-typed lines via
  `readback_transp_plam_general` (Stream B #2c, 2026-04-23) — combines
  the full-face, constant-line, and varying-path cases.  Non-path
  varying lines are vacuous in well-typed code.
- ✅ T5 promoted to eval level via `eval_transp_face_congr` (Stream B
  #2b, 2026-04-23); NbE form `readback_transp_face_congr`.  Step-level
  T5 axiom removed.
- ⚠️ Residual axioms (genuinely need extra machinery): T3 and C4
  (subject reduction, need typing-preservation lemmas).  Step-level T4
  retained as syntactic fallback.

Rust's obligation set is the eval-level equations plus readback
equations (now including `readback_vPathTransp_plam` / `_other`) plus
the residual step axioms — not the full step axiom list.

EML operator (Odrzywolek 2026, arXiv:2603.21852):

    eml(x, y) = exp(x) − ln(y)

Grammar: S → 1 | eml(S, S)

This is the continuous analogue of NAND — a Sheffer operator for all elementary
functions. Every sin, cos, +, ×, √, π is a particular binary tree of eml nodes.
See `exp-log.pdf` for the full constructive proof.

---

## Rendering Stack

```
Lean 4
  EMLTree                  S → 1 | eml(S,S)
  ↓ verified compile
  ShaderIR                 typed binary IR; proofs attached here
  ↓ emit (primary)
  SPIR-V bytes             binary, formal semantics, direct to Vulkan driver
  ↓ (FFI: C ABI)
Rust (wgpu / Vulkan)
  GPU context
  draw(uniformBuffer)
  ↓
Native window (X11/Wayland) — or WebGPU (browser) via the same wgpu
```

### Browser / WASM interoperability

When browser deployment is needed, add a WGSL emitter from the same ShaderIR node.
The proof layer and the IR are unchanged; only the emit step differs.

```
ShaderIR
  ├─ emit/SPIRV.lean   →  SPIR-V bytes   (native Vulkan — primary dev target)
  └─ emit/WGSL.lean    →  WGSL text      (WebGPU / browser — secondary target)
```

WGSL text is compiled to native GPU instructions by the browser (Metal/DX12/Vulkan
under the hood), so runtime performance is identical. The format difference is
parse-time only and immaterial once shaders are uploaded.

**Decision:** Develop against SPIR-V + Vulkan. Add WGSL emitter before any browser
demo. Both share the same ShaderIR, so the WGSL path costs one emitter file, not
an architectural change.

### Why not WASM-compile Lean itself

Lean 4's WASM backend exists (via its C output + emscripten) but produces
large bundles (~30–80MB with elaborator + stdlib).  For the primary
deployment target — "browser-runnable shader demo" — keep Lean as a
native ahead-of-time compiler that emits shader strings/bytes + discharged
proof terms at build time; ship only the Rust FFI runtime as the `.wasm`
module.  A secondary "prove-in-browser" artifact can be built later if
interactive theorem exploration is wanted.

---

## Window Interface

Three surfaces exposed to the window — nothing more:

1. `uploadShader(spirv: ByteArray) → ShaderHandle`
   Compiled EML tree arrives as SPIR-V bytes.

2. `setUniform(handle: ShaderHandle, name: String, value: Float) → Unit`
   Moving a slider = transport along a path in parameter space.

3. `onInput(event: InputEvent) → CellDeformation`
   Click/drag lifts screen coordinates back to cell space (fiber selection).

The window is dumb.  All homotopy structure is resolved in Lean before bytes cross
the FFI.  Rust manages GPU context lifecycle and — on the other FFI surface —
the cubical evaluator kernel linked to Lean's `eval`/`readback` axioms
(with `step` derived — see Phase 4 below).

---

## Phase Roadmap

### Phase 1 — EML Core (Lean 4)
- `Topolei/EML/Tree.lean`     — inductive `EMLTree` (S → 1 | eml S S)
- `Topolei/EML/Eval.lean`     — evaluator `EMLTree → ℂ`
- `Topolei/EML/Derive.lean`   — prove sin, cos, +, ×, π as EML trees (verified)
- `Topolei/EML/Compile.lean`  — EMLTree → ShaderIR

### Phase 2 — ShaderIR + Emitters
- `Topolei/Shader/IR.lean`    — typed intermediate representation
- `Topolei/Shader/SPIRV.lean` — ShaderIR → SPIR-V bytes (primary)
- `Topolei/Shader/WGSL.lean`  — ShaderIR → WGSL text (browser compat)

### Phase 3 — Zigzag Engine Lean Port
Port the n-category combinatorial engine from Rust reference into Lean 4.
See `ZIGZAG_PORT.md` for the step-by-step plan.  Delivers `Topolei/Zigzag/`:
`Monotone`, `Core`, `Diagram`, `Signature`, `Degeneracy`, `Pullback`,
`Normalise`, `Typecheck`, `Tests`.  Plus `Cell/Zigzag.lean` bridging to the
cubical core.  **Pure Lean — no Rust dependency for this phase.**  The Rust
implementation at `zigzag-engine/` is reference material only; see its
README.  Delivers dimension-general normalisation (past the homotopy.io
4D cap), provable essential-identity preservation, and the combinatorial
backend for higher cells.

### Phase 4 — Rust FFI: Cubical Evaluator Backend (the *one* Rust component)
Rust implementations of `eval`, `vApp`, `vPApp`, `vTransp`, `vHCompValue`,
`vCompAtTerm`, `vCompNAtTerm`, `readback`, `readbackNeu`, and the
face-disjoint reductions for transp/comp/glue.  Linked via `@[extern]` +
`@[implemented_by]` to the axioms already stated in `Cubical/Eval.lean`,
`Cubical/Readback.lean`, `TransportLaws.lean` (residual), `CompLaws.lean`
(residual), `Soundness.lean`, and `Glue.lean`.  Turns Lean's
reasoning-only cubical core into a kernel-speed reducer.

**Step is largely derived, not implemented.**  The Week 7 step↔eval
bridge (Sessions 1–4 + Session 5 cleanup landed 2026-04-23) gives
`CTerm.readback := readback ∘ eval .nil` and NbE-level analogues of T1,
T2, C1, C2, `step_papp_plam` (+ partial T4) as Lean theorems — the
former axiom statements have been physically removed from the source.
Four step-level axioms remain on Rust's plate: T3, T5, C4 (each blocked
on separate machinery, see STATUS.md Week 7 table), and the general T4
case.

**This is the only Rust component in topolei.**  It exists solely to
extend Lean 4 with computational cubical-transport HoTT — everything
else is Lean.

### Phase 5 — GPU Runtime (still Rust, but within Phase 4's crate)
wgpu (Vulkan/Metal/DX12/WebGPU) context, shader upload, framebuffer,
uniform buffers.  Three-surface window FFI (upload / setUniform /
onInput) plus the render loop.  Lives in the same Rust crate as Phase 4
for convenience (shared `lean-sys` interop) but is a distinct FFI
surface (effects vs. reductions).

### Phase 3.5 — FM^fr Notation Layer (H4)
- Model mathematical notation as ∫_M A (factorization homology, framed)
- M : framed syntactic manifold (1-manifold = linear text, 2-manifold = 2D layout)
- A : E_n-algebra over EMLExpr — local composition rules
- Framing transports = language transformations (syntax ↔ geometry ↔ interactive)
- LaTeX becomes one framing choice; other framings give graph/interactive/proof renderings
- Depends on: EML evaluator (Phase 1) + cubical transport (cells-spec Phase 1)

### Phase 4 — Cells-EML Bridge
- Connect EMLTree nodes into cells-spec CType/CTerm framework
- EML node = 1-cell; tree composition = path concatenation

### Phase 5 — Subjective Testing Loop
- Minimal interactive window: one EML tree → one rendered cell
- User manipulates parameters; intuition scores recorded in HYPOTHESES.md
- Iterate on interface based on H2 and H3 test results

---

## Constraints (from cells-spec)

1. Zero external HoTT dependencies — own everything from interval algebra up
2. Lean 4 kernel compatibility — cubical calculus deeply embedded as data
3. Self-maintainable — single developer buildable, no external package ecosystem
4. Practical GPU target — proof layer and performance layer separated by narrow FFI