Surface / Surface and Bundle
When to use which
| Situation | Use |
|---|---|
| Something needs to inspect what data a feature uses (fetch planning, replication scope, agent context, render binding, Module checks) | a Surface |
| A child machine placed two or more times, or published for others | a Bundle |
| A child with Subscriptions or resources you keep forgetting to lift | a Bundle, then placements.complete |
| A one-off child used in a single place | a hand-wired Submodel; both are overkill |
| A read boundary with no state machine behind it (a screen, an agent's context) | a Surface; a Bundle would invent transitions that do not exist |
| A state machine with no external readers (internal widget state) | a Bundle or a hand-wired Submodel; a Surface buys nothing |
The negative rows matter more than the positive ones: a Surface without an inspector is paperwork, and a Bundle around stateless UI is machinery around nothing. The Surface README says the first half outright ("If nothing needs to inspect a feature's data needs, a plain function of the Model is simpler"); the same applies to bundles.