Aggregation & The Sibling Aggregator¶

One tree has to describe two graphs. This page is about the second one — and about the single rule that decides what every composite collects.

Why two hierarchies¶

Harmony's Node View carries two connection graphs at once:

Hierarchy	Colour	Connects	Means
Input / Transform	🟢 green	peg → its children	"this moves that"
Output / Composite	🔵 blue	comp ← what feeds it	"this composites that"

They are not the same tree. One peg can drive several distinct compositions, and one composite can gather things that no single peg moves.

A staging tree is a tree — it has exactly one kind of parenting. So OSA uses it for the green graph, where indentation already means what you want it to mean: a child row is a child node.

That leaves the blue graph with no indentation to live in. Its answer is position among siblings.

The sibling aggregator¶

A composite with no green container aggregates the siblings below it.

That is a sibling aggregator. It has no scope of its own to look inside, so it looks down the list.

Comp-1        ← starts block 1
Peg-1         ← feeds Comp-1 … but see below: what enters is Comp-2's output
  Comp-2      ← starts an inner block; its output IS Peg-1's output
  Drawing-1   ← feeds Comp-2
  Drawing-2   ← feeds Comp-2
Drawing-3     ← feeds Comp-1
Comp-3        ← ENDS block 1, starts block 2
Drawing-4     ← feeds Comp-3
Drawing-5     ← feeds Comp-3

Reading that aloud: a comp opens a block, everything after it flows into it, and the next comp at the same level closes the block and opens a new one.

A peg does not feed a comp — its hierarchy's output does

Peg-1 is a transform, not an image. What arrives at Comp-1 is the result of everything under Peg-1, and that result comes out of Comp-2 — the comp inside Peg-1's scope, which already gathered Drawing-1 and Drawing-2.

So the wire is Comp-2 → Comp-1. Peg-1 is on the green graph; it never appears on the blue one.

Take Comp-2 away and Peg-1 has no comp to speak for it — then Drawing-1 and Drawing-2 bubble up and are wired into Comp-1 individually, as two inputs instead of one. That is the whole difference between a peg with a comp and a peg without one, and it is covered in What a container outputs.

And a second comp inside Peg-1 would mean two outputs reaching Comp-1 — one per block:

Comp-1
Peg-1              ← now hands Comp-1 TWO outputs
  Comp-2           ← block A → its output goes to Comp-1
  Drawing-1        → feeds Comp-2
  Comp-2b          ← block B: closes A, opens its own
  Drawing-2        → feeds Comp-2b
                   ← Comp-2b's output ALSO goes to Comp-1

Each block that ends inside a container bubbles up as its own output, in tree order. So the number of wires arriving at Comp-1 from Peg-1 is exactly the number of blocks Peg-1 closed — one comp, one wire; two comps, two wires; no comp at all, one wire per drawing.

What breaks the chain¶

Another composite at the same level. That is the only thing that does.

When the walk meets a second comp among the same siblings it flushes the current block and starts a fresh one. There is no marker to set and no option to tick: the presence of the second comp is the boundary.

That is why you can lay out a scene as a flat list of siblings and still get several separate compositions out of it — you separate them by putting a comp where each group should end.

The rule that decides children vs siblings¶

Only green containers create a scope, and there are exactly two of them: Peg and Group.

Slot	Comp aggregates	Why
`C` alone	siblings below	nothing but an aggregation point
`D-C`	siblings below	no green container, so no scope
`BD-C`	siblings below	a backdrop is visual — it does not own nodes
`BD-D-C`	siblings below	same: the backdrop changes nothing about wiring
`P-C`, `G-C`	children	the green container creates an internal scope
`P-D-C`, `G-D-C`	children	same
`BD-P-C`, `BD-P-G-D-C`	children	the peg is what does it; the backdrop just draws a box

A backdrop never changes who aggregates

This is the one people get wrong, and it is worth saying flatly: BD is visual. BG=BD-C aggregates siblings exactly like a bare C, because there is no green connection between the backdrop and the comp for the comp to collect children through. Only P or G turn a comp into a children-aggregator.

Super node with Peg (or Group) + Comp¶

Now the case you build every day.

A slot with a green container and a comp — hero=P-C, hero=BD-P-G-C — makes the comp aggregate its immediate children, in tree order…

…up to the first child that is itself a comp. That child starts a new sibling-aggregator block, and everything after it belongs to that block instead.

hero=P-C            ← green scope; its comp collects the children below
├── arm=D           → feeds hero-C
├── leg=D           → feeds hero-C
├── fx=C            ← a comp among the children: block boundary
├── glow=D          → feeds fx-C
└── dust=D          → feeds fx-C

hero-C gets arm and leg. fx-C gets glow and dust, and fx-C's own output is what continues upward.

That is the whole composition language: a green container opens a scope, and a comp inside it collects until the next comp says stop.

What a container outputs¶

The container	Its output
has an internal comp	a single output — the comp, or the last effect after it
has no internal comp	multi-output: every drawing inside it bubbles up

A peg with no comp does not merge anything. It hands its parent a list, and each item is wired into the parent's comp individually.

SuperNode=P-D-C
├── Peg-1  (P only, no Comp)
│   ├── Drawing-A
│   └── Drawing-B
└── Drawing-C

Peg-1 returns [Drawing-A, Drawing-B], so SuperNode-C receives four inputs:

Port	Input
3	`SuperNode`'s own drawing
2	`Drawing-A` (bubbled from Peg-1)
1	`Drawing-B` (bubbled from Peg-1)
0	`Drawing-C`

Put a comp in the peg and those two collapse into one input. That is the practical difference between Peg-1=P and Peg-1=P-C, and it is usually the reason a graph has more wires than you expected.

Port order¶

The blue graph has a direction, and it is fixed:

Port	Renders	Sits
Port N (highest)	in front	left in the Node View
Port 0 (lowest)	behind	right in the Node View

So the leftmost element in the Node View is on top of the render, and the rightmost is at the back. Inside a super node, the slot's own drawing takes the front port and the children take the ones below it, left to right.

That is also why the Wide Bus puts the top of your tree at the left: tree order, port order and render order are the same order, read the same way.

Reading it in the tree¶

You do not have to simulate any of this in your head — the Details column already tells you what each row builds, and the rule above tells you what its comp will collect:

BACKGROUND      (Backdrop > Peg > Comp)     ← green scope: collects its children
  sky           (Read)                       → feeds BACKGROUND-C
  clouds        (Read)                       → feeds BACKGROUND-C
EFFECTS         (Backdrop > Peg > Comp > Effects)

If a comp is collecting the wrong things, there are only two questions to ask: is there a green container on that slot? and is there another comp above it among the same siblings?