Installer and AEM Overview

This page explains the responsibility split between AEM and Addon Installer.

Final Intended Rule

AEM is the addon lifecycle authority.

AEM owns:

• addon identity
• accepted manifest/runtime contract truth
• clean install vs update classification
• same-lineage decisions
• dependency and compatibility decisions
• risk classification
• route, slug, route-key, and capability collision decisions
• lifecycle state
• persisted contract records

Addon Installer executes the package only after the lifecycle decision is accepted.

Installer owns:

• package intake
• archive/folder safety validation
• staging
• file deployment
• schema apply execution
• permission registration execution
• cleanup
• executor history

Current Drift

Current code is transitional:

• Core discovery still reads `manifest.php` and `bootstrap/install_contract.php` during scan/sync.
• Installer still inspects static manifest fields.
• Installer still performs same-lineage/update checks.
• Installer calls AEM collision validation before deployment.
• Installer records lifecycle-adjacent execution state.

Document that behavior as current implementation detail, not final authority.

Install Flow

1. Package enters Addon Installer intake.
2. Installer validates package safety.
3. AEM validates identity, dependencies, risk, and collisions.
4. AEM returns an accepted lifecycle decision or a block.
5. Installer deploys only the accepted package.
6. Installer applies schema and permissions contracts.
7. Installer records executor history.
8. AEM persists accepted lifecycle/runtime truth.

Update Flow

An update requires:

• same `product_uuid`
• stable `addon_key`
• compatible package contract
• no unsafe route/slug/key collision with another lineage
• declared schema/permission migration behavior

Current code may fall back to addon-key lineage when UUID is missing. That is drift. New governed addons must ship `product_uuid`.

What To Document In Addon Guides

• AEM decides lifecycle meaning.
• Installer executes accepted work.
• Manifest is intake contract.
• Runtime truth should come from AEM-persisted records.
• Transitional code reads must be named as drift.

Related: Installer/Package Install and Update Flow, Addon Development/Route and Slug Collision Handling, Addon Development/Manifest Contract, Addon Development/Install Contract.