Download all docs

Topology: what can be part of what

Elements do not float in a void — each one has a residence: a class that answers “where does this live, and what can it hold or attach to?” Topology is that relationship layer. This page is the Chemistry-pillar reference for it: the four residence classes, how compound differs from nested, and how attachment (bonds and references) works on top of the flat element model.

Residence: the four classes

Every element type declares a residence class in its definition.yaml. There are exactly four, and each is a one-sentence answer to “what can this be part of?” — the same sentence the per-element page’s Topology section renders:

  • library — created from the library and placed inside an app or circle. A top-level building block you compose with other elements. Most element types are library: a python action, a sql table, a slack connector.
  • nested — lives nested inside a parent element rather than standing alone; it is created in the context of its container. A nested element does not appear at the circle’s top level on its own.
  • modifier — attaches to another element, shaping that element’s behaviour rather than running on its own. An auth-policy, a rate-limit, a brand — they are configuration on an element, not standalone runners.
  • structural — a structural container: it holds and organises other elements inside it on the canvas. The circle itself is the archetype.

The residence class is data, not code: physics and portal never branch on element type to decide where something can live — they read the residence class from generated metadata. When a definition does not state a residence explicitly, it is derived from the element’s form: a modifier form defaults to modifier residence, a manifest form to structural, and everything else to library.

Form vs. residence

These are two different axes that travel together. Form describes what an element is structurally — the valid forms are atom, compound, modifier, data, and manifest. Residence describes where it lives. A modifier-form element has modifier residence; a manifest-form element is structural; an atom is usually library. Form is the shape; residence is the place.

Compound vs. nested

These look similar but are different relationships:

  • A compound element (form compound) is a parent type whose children are real, top-level-dispatched element types — automation nests condition, loop, and wait; lab nests brain, ears, and mouth. The per-element Topology section says so directly: “This is a compound element — it nests condition, loop, wait inside it.” See Compound elements for the full treatment.
  • A nested element (residence nested) is one that simply cannot stand alone — it is created in the context of a container, full stop. Compound is about a parent exposing named child types; nested is about an instance’s residence.

Attachment: bonds and references

Containment is one relationship; attachment is the other. The runtime uses one unified attachment model for both modifiers and data:

  • Modifiers (form modifier) attach to an element via bonds_to declarations — the modifier names the element types it may shape.
  • Data elements (form data) are referenced by consumers via uses declarations — an action that reads a sql element references it.
  • Both are stored in the same element_modifiers table and validated through the same can_attach / validate_attachment path.

Containment itself (which element may contain which) is checked against a parent’s bonds / contains list. None of this is hardcoded per type: the topology rules are looked up from the type registry at runtime, so a new element type’s containment and attachment rules come from its declaration, not from a recompile.

On the flat element model

Elements sit flat under their circle — there is no owning tree of folders. The relationships on this page are not a directory hierarchy; they are declared edges: containment (bonds/contains), attachment (bonds_to), and reference (uses), each resolved from the type registry. A circle’s elements are a flat set, and topology is the declared relationships between members of that set, not a nesting of files. How those relationships compose at the instance level is the composition concept; this page is the type-level rules that say what is even allowed.

Related