One Line Inherits Everything

How Amplifier bundles compose without collisions

The Problem

Every project needs the same stack — but plain config can't be layered

Amplifier projects all need the same providers, tools, hooks, and behaviors under their own domain logic. Plain configuration doesn't compose: you copy-paste, and keys collide.

So what if the unit itself knew how to compose?

The Composable Unit

One Bundle, one method — already shipped

The composable unit is a single Bundle dataclass with one method: compose(self, *others) -> Bundle. It's not a proposal — it's shipped in amplifier-foundation 1.0.0.

But merging a whole bundle correctly is harder than merging one field.

# amplifier_foundation/bundle/_dataclass.py:93 def compose(self, *others: Bundle) -> Bundle:
Shipped & tested — amplifier-foundation 1.0.0 (microsoft/amplifier-foundation)
The Hard Part

Different sections need different merge rules — or files silently overwrite

The hard part isn't merging one field. Different sections of a bundle need different rules, and a naive merge lets context files silently overwrite each other.

compose() answers this with one rule per section family.

How It Merges

Five well-defined strategies — one rule per section family

compose() applies exactly five documented merge strategies, one per section family, so every part merges the right way instead of clobbering.

The context rule is the one that guarantees no collisions.

Zero Collisions

Context keys are prefixed with the bundle name, so files accumulate

Each bundle's context keys are prefixed with its own name during compose. Bundles accumulate files instead of overwriting — the prefix exists to avoid collisions.

Now the ordering rule makes inheriting a whole stack safe.

# _dataclass.py:120 — "avoid collisions during compose" prefixed_key = f"{self.name}:{key}" # _dataclass.py:189 — other bundle's keys prefixed_key = f"{other.name}:{key}"
The Ordering Rule

Includes load in parallel — your bundle composes last, so your logic wins

The registry loads every includes: in parallel with per-chain cycle detection, then composes your bundle last. Inheriting the stack still lets your domain logic override.

That's what makes one line safe to inherit an entire foundation.

# registry.py:690 — load includes in parallel results = await asyncio.gather(*tasks, ...) # registry.py:735 — current bundle overrides return result.compose(bundle)
The Payoff

One line of includes: inherits the whole stack — overrides intact

One declarative line pulls in an entire foundation stack: loaded in parallel, composed with your bundle last, with zero context collisions — verified by a passing test suite.

And the pattern beneath it is what generalizes.

5
merge strategies, one per section family
7
compose-specific tests passing
59
tests passing across bundle + dicts
The Pattern

Make the unit composable, give it one mechanism — pure mechanism

Make the unit composable and give it one mechanism — includes: (declarative) plus compose() (imperative). Layering foundations under domain logic stops being copy-paste.

Sources

Research Methodology

Data as of: 2026-04-09 (amplifier-foundation HEAD 0965a34)

Feature status: Shipped and tested in microsoft/amplifier-foundation, version 1.0.0

Research performed:

Gaps: "Zero collisions" summarizes the namespace-prefix mechanism (code says prefixes are added "to avoid collisions"); no absolute guarantee is asserted in code. Contributor counts (48/1/1) cover only the three composition files, not repo-wide totals.

Primary contributors: Brian Krabach — author of compose() (48 commits to composition files); Diego Colombo (1 commit, relative-path fix #40); Marc Goodner (1 commit, UTF-8 encoding fix).

More Amplifier Stories