cubical-transport-hott-lean4/docs/EULERIAN.md

EULERIAN.md — The Project's Poetic Record

Drafted 2026-05-01 on Dev_REL2. The metaphors that have guided this project's design discipline, paired with their concrete Lean / Rust counterparts. This document is for newcomers, future agents, and the project's own philosophical record. It is not a specification — INDUCTIVE_TYPES.md, REL2_PLAN.md, QUESTIONS.md, ALGEBRA_PLAN.md, and KERNEL_BOUNDARY.md carry that load. This document carries the image of the system.

---

0. Why a poetic record

Cubical type theory's geometric vocabulary — paths, faces, lines, fillers, transports, currents — is not decoration. It is the design discipline that keeps the codebase architecturally coherent across REL1, REL2, and beyond. When a metaphor lands cleanly on a concrete Lean construct, that's the system signalling its own architectural soundness. When a metaphor breaks down, the underlying construct usually has a real design flaw.

The metaphors below are not aspirational; each one names something that already exists in the code (or is committed to in a planned phase).

---

1. The river bed — CType.interval

The river requires a river bed. Without one, paths flow over unspecified medium.

Concrete: CType.interval (REL2 Phase 1, landed 2026-04-30 as commit ce2ee87 on Dev_REL2). Promoted the cubical interval to a first-class type primitive. Pre-REL2, CTerm.dimExpr r typed at the placeholder .univ; post-REL2 it types at .interval.

Why it matters: Path-constructor dim arguments (loop @ r, seg @ r, squash _ _ @ r, …) now carry real semantic ground. The interval is the medium that all dimension-flowing computation requires. Without it, the engine had Paths but no canonical river-bed type for the dim-coordinate paths flow along.

---

2. The river — Path and transp

Water moves. A path is the witness of motion from one bank to the other; transport is the act of crossing.

Concrete: CType.path A a b (the type of paths from a to b in A); CTerm.transp i A φ t (transport of t : A(0) to A(1) along the line λi.A, restricted by face φ).

Why it matters: Paths are proof-relevant equalities; transport is the operation that turns a path into actual movement of values. This is the cubical equivalent of "we don't just know the river runs from source to mouth; we follow the current."

---

3. The estuary — boundary firing on path constructors

Where the river meets the sea, the current becomes one with something larger.

Concrete: Path-ctor boundary firing in eval: when a .dim- typed argument lands on a face in the constructor's boundary system, eval substitutes the boundary clause body instead of producing the raw vctor. Currently TODO in REL2 (REL1 has the syntactic shape; REL2.1 lands the firing semantics).

Why it matters: This is what makes HITs compute. S¹'s loop @ 0 reduces to base; ‖A‖₋₁'s squash x y @ 0 reduces to x. Without boundary firing, HITs are syntactic placeholders; with it, they are operational.

---

4. The current — pointwise transport distribution

Matter flows along the geometry; the current is how it gets there.

Concrete: Pointwise transport distribution over .ind S params: when transport encounters a .ctor term, it distributes through the ctor's args by transporting each non-recursive arg via its CType's transport rule, recursing on .self args. Currently deferred to REL2.1 (REL2.0 produces stuck ntransp neutrals, correct but not maximally reduced).

Why it matters: Once distribution lands, K7.step (paideia's gradient composition, REL2 Phase 3) reduces definitionally instead of staying as a syntactic .comp. The river not only has a bed and a current — its motion is visible, not just implied.

---

5. The ferry — Bridge.lean (Eq ↔ Path)

Two rivers run in parallel; the ferry carries payload between them.

Concrete: CubicalTransport/Bridge.lean (REL2 Phase 2, landed 2026-04-30 as commit 7152807 on Dev_REL2). The CubicalEmbed α typeclass with default instances for Bool, Nat, and List α [CubicalEmbed α]. Forward bridge Eq.toPath (always available); backward bridge Path.toEq_canonical (REL2.0 canonical case via toCTerm_injective); full backward bridge over arbitrary well-typed paths is REL2.1.

Why it matters: Lean's discrete Eq river (Mathlib, decidable equality, all the discrete-math infrastructure) and the embedded cubical Path river (univalence, proof-relevant identity, the whole CCHM apparatus) flow in parallel through the codebase. The ferry lets payload — Mathlib lemmas, decidable witnesses, K7 encoding — cross between them. Without the ferry, the two rivers exist but can't share cargo.

---

6. The carrying load — paideia K7

The ferry exists. The river bed exists. Now ride a barge across.

Concrete: paideia's K7 (BootstrapGradient) re-encoded as a literal cubical Path between two MasteryProvenance traces. Planned as REL2 Phase 3 in the paideia repo (5–10 days, depends on engine REL2 Phase 1+2 landing). Closes engine issue #1.

Why it matters: K7 was the originating use case — the issue that filed against the engine in the first place. REL1 gave us inductive types; REL2 Phase 1 gave us interval; REL2 Phase 2 gave us the bridge. REL2 Phase 3 is the day the system actually carries load. The poetry was always there; this is when it arrives.

---

7. The wake — Trace.lean and TraceAt.lean

Every passage leaves a wake. Looking at the wake, you can read who has been here, when, and on what business.

Concrete: Topolei/Trace.lean (root) and Topolei/Cubical/{Trace,TraceAt}.lean (engine-side). Trace.traceOf records every sub-CTerm that participated in a computation; TraceAt.traceOfAt does so face-aware (only sub-CTerms whose enclosing face is active at a given assignment).

Why it matters: Provenance is first-class. When debugging, profiling, or auditing a cubical computation, the wake is the record. The face-aware variant (traceOfAt) prunes inactive clauses, so the wake reflects only what actually flowed under a particular set of conditions — the trace of the currents that fired.

---

8. Confluence — HITs and Glue

Multiple flows merge at a confluence; from there, a single larger river continues.

Concrete: Higher inductive types via CTypeSchema with path constructors (s1Schema, intervalHitC, propTruncSchema); Glue types (CType.glue φ T … A) that present the same value via two different equivalence-related forms.

Why it matters: Confluence is where the cubical universe exhibits its non-trivial structure. S¹'s loop is a path between base and itself — the river is non-trivial precisely because of how the flow folds back. Glue is where two type formulations become one type with a coherence witness. Both encode the same architectural insight: equality is structure, and the structure of equality is what cubical type theory makes visible.

---

9. The map — Dev_Algebra and the universal macro

Above the rivers, a map. It shows every current, every confluence, every ferry crossing. A finger on the map can trace any path; a click can re-route.

Concrete (landed 2026-05-01 on Dev_REL2):

• CubicalTransport/Algebra/Meta.lean — the meta-mirror types (MetaCType, MetaClassifier, MetaArtifact, MetaPosition).
• CubicalTransport/Algebra/Edit.lean — the Edit monad and Context comonad, with the comonad-to-monad distributive law.
• CubicalTransport/Algebra/Restructure.lean — the universal restructure macro (comp-shaped, five fields), the canonical frozen aliases (transport_artifact, relocate_invariant, rename_throughout, materialize, …), and the headless apply interpreter.
• CubicalTransport/Algebra/MacroAlias.lean — the @[macroAlias] attribute + alias registry.
• CubicalTransport/Algebra/Methodology.lean — the @[methodology] attribute and the cubical_search autodiscovery tactic (registry + dispatch loop; methodology-transport stub awaits @[metaPath] in REL2.6+).
• CubicalTransport/Algebra/Test.lean — end-to-end compile-time tests verifying the registry, attribute, and tactic-dispatch loop work as a system.

The widget surface (Phase D, UserWidgetDefinition rendering the question-graph) is the one piece deferred — it needs an active Lean LSP session for RPC plumbing. Headless usage is fully operational via lake exe algebra-restructure-style entry points.

Why it matters: The map is the visible face of the system's closure under its own operations. Cubical primitives (transport, comp, Path, Glue, …) at the object level — meta-primitives (restructure, MetaPath, MetaClassifier, methodology-transport, …) at the Lean-source level — same universal comp shape at both strata. The codebase becomes navigable because the navigation tools are built from the same algebra as what they navigate.

---

10. The current's autodiscovery — methodology transport

Once the map is drawn, knowing one passage is knowing many: every connection on the map is a recipe for following the current somewhere new.

Concrete (partial 2026-05-01, full pending REL2.6+): The methodology-transport clause inside cubical_search.

• Registry + dispatch (landed): Algebra/Methodology.lean ships the @[methodology] attribute, the methodology registry (methodologyRegistryExt), and the cubical_search tactic that walks the registry on every goal. The stub deriveByTransport returns [] until the structural-Path declaration system arrives.
• Methodology-transport (pending REL2.6+): the @[metaPath] attribute lets a developer declare a structural Path between two classifiers. Once such Paths are present, deriveByTransport walks them to automatically derive new methodology candidates from existing ones — transp at the methodology level. Twenty starting methodologies + a hundred declared paths → potentially thousands of derived methodologies, each formally certified-by-construction.

Why it matters: This is autodiscovery: the proof-search library grows under structural-Path declarations alone, with no extra authoring. A new equivalence in the codebase is also a new chunk of proof automation — for free. The cubical engine's own transport is what powers the proof-search engine. The system has become reflexive.

---

11. The discipline (one-page summary)

Stratum	River bed	River	Current	Ferry	Wake	Map / autodiscovery
Cubical (object)	CType.interval	Path, transp	comp filler	(within calc)	Trace	(no map yet)
Question (Layer 1)	classifiers	CompQ	q.ask	Bridge	traceOfAt	question-graph
Meta (Layer 3)	MetaCType	MetaPath	restructure	treat_as_* macros	Edit log	widget + cubical_search
Tactic (Layer 5)	methodology library	tactic chains	cubical_search	tactic_from_methodology	tactic trace	methodology-transport

Each row is the same architectural pattern applied at a higher stratum. Reading the columns top-to-bottom, you see the metaphor's lifeline through the system: the river bed has a meta- river-bed (MetaCType), which has a tactic-river-bed (methodology library); the river has a meta-river (MetaPath), which has a tactic-river (chained tactic invocations); and so on.

The discipline is one universal pattern, applied at every stratum, with each instance named according to its register.

---

12. What this discipline buys

1. Architectural coherence under refactoring. Any re-organisation that respects the universal pattern at one stratum trivially respects it at every other stratum. No layer-specific surprises.
2. Vocabulary for newcomers. A new contributor (human or AI) reading the codebase encounters one canonical question shape six times, not six different patterns once each. The cognitive cost of orientation drops dramatically.
3. Proofs as first-class data. Because every theorem reduces to a chain of classifier-conditioned CompQ equivalences, proofs are navigable (the question-graph), factorable (any theorem decomposes into elementary moves), and recomposable (any structurally-valid composition is itself a valid proof).
4. Tooling closure. The macro layer that organises proofs is itself made of the same universal comp shape. Tools manage themselves. No tool sits above the algebra; everything lives inside it.
5. Aesthetic consistency. Every artifact in the codebase has a clean place to live, named in vocabulary that fits the metaphor. Code that looks clean is clean — the visible surface and the underlying algebra agree.

---

13. Where the metaphor strains (and what to do about it)

No metaphor is perfect. Three known strain points:

1. Glue is more than confluence. It's a coherence-witnessed refactor between two formulations — closer to "two roads sharing a bridge that records why they are equivalent." The confluence image gets the geometry but loses the witness; if a reader is confused, the long form is the way out.
2. The interval is not really a river bed. It's a de Morgan lattice. The river-bed image is right for "the medium under the flow" but loses the algebraic structure (meet/join/inversion). Acceptable for documentation; not for formal reasoning.
3. Autodiscovery is not magic. The methodology-transport clause is bounded by declared structural Paths. A path you haven't declared cannot transport methodologies along itself. The "thousands of derived methodologies" claim is real but conditional — bounded by the user's own Path declarations. Future REL3+ AI-prior work may relax this; until then, the autodiscovery is pattern-mechanical, not pattern-imaginative.

These strains are recorded so future readers don't over-extend the metaphor in ways the underlying algebra wouldn't support.

---

14. References

• INDUCTIVE_TYPES.md — REL1 design: schema-based inductives + HITs.
• REL2_PLAN.md — three-phase plan: interval, Bridge, K7.
• QUESTIONS.md — philosophy: questions as types, classifiers, three commitment levels.
• ALGEBRA_PLAN.md — Dev_Algebra branch: universal macro, attributes, autodiscovery tactic, widget.
• KERNEL_BOUNDARY.md — long-horizon scope contract: what the embedding can and cannot do without kernel changes.
• FFI_DESIGN.md / FFI_COMPLETENESS.md — Rust kernel ABI contract and per-function axiom audit.
• NUMERICAL.md — REL3-onward numerical layer (out of scope for these documents but on the same metaphorical map).

---

End of EULERIAN.md. This document is the project's record of its own architectural metaphor. Update when the system grows a new layer that fits the discipline; remove an entry only when the underlying construct retires.