19928d040a
Some checks failed
Lean Action CI / build (push) Has been cancelled
Two structural changes landed together as one coherent body of work.
## 1. Engine is name-clean from higher-order projects
The engine no longer carries "topolei" in its own naming surface.
Higher-order projects depend on the engine, not vice versa, so the
engine should be self-named.
topolei-cubical (Cargo) → cubical-transport
libtopolei_cubical.a → libcubical_transport.a
topolei_cubical.h → cubical_transport.h
TOPOLEI_FFI_ABI_VERSION → CUBICAL_TRANSPORT_ABI_VERSION
topolei_cubical_* (14 FFI fns) → cubical_transport_*
topolei_shim_* (9 shim fns) → cubical_transport_shim_*
Inter-repo references describing topolei as a downstream consumer
(README, KERNEL_BOUNDARY.md, INDUCTIVE_TYPES.md, etc.) are preserved
as legitimate dependency-direction descriptions.
## 2. Universe-stratified, dependently-typed CType
CType : ULevel → Type (genuinely indexed inductive)
with dependent pi/sigma carrying a binder name, a lift constructor
for cumulativity, and parameter lists of Σ-packaged types.
Per CCHM rules:
· univ ℓ : CType (ℓ.succ)
· pi/sigma : CType (max ℓ_A ℓ_B), with named binder
· path A : at A's level
· glue T A : T and A at same level
· ind : at user-chosen level (heterogeneous-level params)
· interval : CType .zero
· lift : CType (ℓ.succ), data-preserving
Every existing engine module cascades through {ℓ : ULevel} implicits
on functions/theorems, pi/sigma binder updates, and Σ-packaged params
lists. CTerm stays un-indexed (universe lives on CType).
## 3. Substrate machinery for the cascade
Universe.lean — ULevel inductive + max algebra (assoc, comm, etc.),
all theorems proven structurally.
Syntax.lean — adds SkeletalCType enum + CType.skeleton level-erasure
projection + per-constructor skeleton_* simp lemmas +
CType.ind_skeleton_ne_pi disjointness lemma. Used to
discharge cross-level HEq cases in TransportLaws/CompLaws
without invoking K.
## 4. Rust ABI v3 → v4
Lean 4 keeps implicit {ℓ : ULevel} parameters at runtime as constructor
fields, in declaration order interleaved with explicit args (verified
via probeLayout instrumentation). Layout for level-bearing constructors
documented in cubical_transport.h §"v4 layout tables".
CType.pi : 5 fields — [ℓ_d, ℓ_c, var, A, B]
CType.path : 4 fields — [ℓ, A, a, b]
CType.glue : 9 fields — [ℓ, φ, T, f, fInv, sec, ret, coh, A]
CType.ind : 3 fields — [ℓ, S, params]
CType.lift : 2 fields — [ℓ, A]
CTerm.transp : 5 fields — [i, ℓ, A, φ, t] (i precedes ℓ)
CVal.vCompFun : 9 fields — [ℓ_d, ℓ_c, env, i, dom, cod, φ, u, t]
... etc
All Rust marshalling (value.rs, eval.rs, transport.rs, composition.rs,
glue.rs, beta.rs, dim_absent.rs, readback.rs, subst.rs, ffi.rs, tags.rs)
updated to match.
## Discipline
· Zero sorry in CubicalTransport/.
· Zero noncomputable instances; zero Classical.propDecidable shortcuts.
· No CType.level projection (the level lives in the inductive's index).
· No parallel CTypeU type.
· No stub substrate types (def Ω := CType.univ etc.).
· Tests restored to full coverage (EvalTest 623 lines, FFITest 351
lines with classifier-runtime tests intact).
## Verification
cd cubical-transport-hott-lean4
lake build # 48 jobs OK
./.lake/build/bin/cubical-test
# ── 49/49 passed ──
# ── 46/46 properties passed ──
# PASS: all smoke + property tests
cd ../topolei
lake build # 90 jobs OK
./.lake/build/bin/probe-test
# ── 7/7 probes passed ──
# PASS: GPU output matches Lean ShaderSemantic
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
63 lines
2.6 KiB
Text
63 lines
2.6 KiB
Text
/-
|
|
CubicalTransport.FFI
|
|
====================
|
|
Documentation + convenience re-exports for the Rust cubical-HoTT
|
|
backend (Phase C, 2026-04-24).
|
|
|
|
## Architecture after Phase C
|
|
|
|
The `@[extern "cubical_transport_*"]` `opaque` declarations and their
|
|
`@[implemented_by]` attributes are **inlined directly in the files
|
|
that own the fallback `partial def`**:
|
|
|
|
| Function | File where extern + impl_by live |
|
|
|-----------------------|----------------------------------|
|
|
| `eval` | `Cubical/Eval.lean` |
|
|
| `vApp`, `vPApp` | `Cubical/Eval.lean` |
|
|
| `vHCompValue` | `Cubical/Eval.lean` |
|
|
| `vCompAtTerm` | `Cubical/Eval.lean` |
|
|
| `vCompNAtTerm` | `Cubical/Eval.lean` |
|
|
| `vFst`, `vSnd` | `Cubical/Eval.lean` |
|
|
| `vTransp` | `Cubical/Transport.lean` |
|
|
| `readback` | `Cubical/Readback.lean` |
|
|
| `readbackNeu` | `Cubical/Readback.lean` |
|
|
| `DimExpr.normalize` | `Cubical/Interval.lean` |
|
|
| `FaceFormula.normalize` | `Cubical/Face.lean` |
|
|
|
|
**Why inline.** Lean 4 requires `@[implemented_by]` to be attached
|
|
at the declaration site. A central FFI module that tries to
|
|
retroactively attach the attribute to imported declarations fails
|
|
with `Cannot add attribute [implemented_by] to declaration ... in
|
|
an imported module`. The extern declaration and the `partial def`
|
|
must therefore be co-located.
|
|
|
|
This file is kept as a documentation anchor + a place to add any
|
|
future shared FFI utilities that don't belong to a specific
|
|
cubical-core module.
|
|
|
|
## Runtime behaviour
|
|
|
|
When `libcubical_transport.a` is linked (default via `lakefile.toml`),
|
|
every runtime call to `eval` / `vApp` / `readback` / etc. routes
|
|
through Rust at native speed. Kernel-level proof reasoning
|
|
continues to go through the axioms in each module — unchanged.
|
|
|
|
Without the Rust library linked, compilation fails at link time
|
|
(every extern symbol is unresolved), so a built executable always
|
|
has Rust present.
|
|
|
|
## ABI version
|
|
|
|
`CUBICAL_TRANSPORT_ABI_VERSION = 1`. Defined in
|
|
`native/cubical/include/cubical_transport.h`. Any change to an
|
|
`@[extern]` signature (arity, argument types) requires incrementing
|
|
the version and updating the C header.
|
|
|
|
## Related documents
|
|
|
|
- `FFI_DESIGN.md` — C ABI contract (memory, marshalling, ownership).
|
|
- `FFI_COMPLETENESS.md` — per-function axiom-coverage audit.
|
|
- `KERNEL_BOUNDARY.md` — what this delivers vs. what requires kernel work.
|
|
-/
|
|
|
|
import CubicalTransport.Readback
|