cubical-transport-hott-lean4/PLAN.md

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