Skip to content
Eigenius

Composing institutions

This guide is about what happens when multiple institutions cooperate — the cross-cutting story none of the per-host chapters tell on their own. A single WASM-hosted institution chapter (platform §10) or a single substrate-hosted institution chapter (platform §11) covers what one institution looks like; this guide covers what the system looks like when several institutions, each with their own dispatch roles and their own host runtime, share data through the chain and bridge across each other through declared comorphisms.

The canonical worked example throughout is the kinase-institutions.json notebook — five Julia institutions, three cross-institution comorphisms, two storylines (Catalyst → DiffEq forward simulation; Symbolics → JuMP parameter fit), the D14 §9.3 chain-reinsertion contract closed through both the ESL and EigenQL surfaces. Each chapter pulls a slice of that example to ground the concept it covers.

How to read this guide

If you’ve read the ESL, EigenQL, and formula language guides plus at least one of the per-host institution chapters (platform §10 or platform §11) you have all the prerequisites. If not, read at least chapter 1 here first — it summarises the surface vocabulary the rest assumes.

The chapters build on each other:

  1. Introduction — what composition is, the three layers it operates at (shared payload language → declared comorphisms → coordinated dispatch roles), and the kinase notebook as the running example.
  2. Shared payload languages — why composition is cheap when both endpoints speak the same data shape, expensive when they don’t. formulas:FormulaTerm as the v1 example and what makes it the right shape for cross-institution flow.
  3. Comorphisms — bridges between domains — the triadic structure (ExportFormat + transformation Component + ImportFormat), the four-step dispatch pipeline (D14 §9.3), identity transformations vs. structural ones, the exact: bool Satisfaction-Condition and what it means for soundness.
  4. The three dispatch roles in concert — AutoOnLoad gates, OnDemand FIBER, Decidable predicates. How they compose: an AutoOnLoad commit can produce a Verdict that an OnDemand FIBER call later reads; a Decidable predicate downstream can branch on either. The kinase notebook fires two AutoOnLoad gates back-to-back — this chapter explains why that’s the typical shape.
  5. Chain reinsertion of comorphism outputs — D14 §9.3 step 4 in practice. ESL Exp::InstitutionInvoke, EigenQL FIBER ... INTO, deterministic content-hash IRIs, the Trace::Comorphism audit variant. Why reinsertion matters for composition: downstream queries can find and reason about the produced resource as a first-class chain entity.
  6. Walkthrough: reading the kinase notebook end-to-end — the canonical comorphism-mediated example, traced cell by cell. Three parts (flat data, typed institutions, chain reinsertion); how each cell exercises one or more of the mechanics in chapters 2–5.
  7. Statistics + reasoning walkthrough — the second composition shape, traced end-to-end: raw IC50 readings → D52 StatisticalAnalysisPlan Holds → witness-index admission → D39 ReasoningSentence certificate consumes the witness via DerivedEvidence → StrongInhibitor conclusion. No comorphism between the institutions; the composition runs through the shared core:EigenTTType proposition slot.
  8. Composition patterns — when to share a payload language, when to declare a comorphism, when an OnDemand FIBER suffices, when chain reinsertion matters. Identity comorphisms (Symbolics ↔ Intervals) vs. structural ones (Catalyst → DiffEq’s reaction-network → ODE compilation). When exact: false is appropriate.
  9. Failure modes across compositions — chain validation cascades through nested resources; what happens when a comorphism’s source institution rejects an extract; race conditions between AutoOnLoad gates and OnDemand calls; what “stale Verdict” means in a composition.
  10. Appendix — references, source index, related design docs (D14 §4–§6 + §9.3, D26, D27, D32, D39, D46, D47, D48, D49, D52), pointer to the SHACL-comparison note for the conceptual pitch.

Most important chapters

What this guide is not

  • Not a per-host how-to. WASM and substrate authoring live in platform §10 and platform §11 respectively. This guide assumes you can read those.
  • Not the formula language reference. That’s the formula language guide. This guide treats FormulaTerm as a coordination mechanism between institutions; the formula guide treats it as a EigenTT fragment in its own right.
  • Not a single-institution tutorial. Per-institution slow-walks live under platform/julia-institutions/. This guide assumes you’ve internalised at least the intervals tutorial.
  • Not the conceptual pitch. The SHACL-comparison note frames the broad story for someone coming from the W3C semantic web stack. This guide is the structured reference once that framing has landed.

Cross-references

Ready to start? → 1. Introduction