Manifest Contract

`manifest.php` is the governed package identity and contract-provider map for an addon. It tells system governance what the addon claims to be and where the real contracts live.

Final intended rule: after install, ordinary runtime should consume system governance-persisted accepted contract truth. It should not reopen `manifest.php` to discover routes, navigation, permissions, lifecycle state, or identity during normal requests.

One Job

The manifest describes the package. It does not own the detailed truth for permissions, routes, schema, admin screens, public targets, or runtime behavior.

Use the manifest for:

• stable identity
• package identity
• display metadata
• classification hints
• risk declarations
• dependency declarations
• contract provider pointers

Do not use the manifest for:

• a full permission catalog
• a full route table
• copied admin target definitions
• copied frontend target definitions
• install execution details
• schema SQL

If the manifest starts carrying copies of those things, drift has already found a comfy chair.

Required Fields For A Governed Addon

• `product_uuid`: stable product/addon lifecycle identity. Keep it unchanged across updates of the same addon lineage.
• `package_uuid`: unique package artifact identity. Change it for each packaged release.
• `addon_key`: stable machine key, normally matching the addon folder name. Use lowercase letters, numbers, and underscores.
• `display_name`: admin-facing addon name.
• `slug`: human-readable URL/path alias. Use lowercase letters, numbers, and hyphens.
• `version`: package version label, such as `v0.0001 Alpha`.
• `addon_type`: package class, such as `application`, `module`, `system`, `integration`, `template`, or `theme`.
• `status`: concise package readiness state.
• `classification`: the intended Admin home and bucket, subject to system governance acceptance.
• `summary`: short human-readable purpose.
• `risk_declarations`: database, public surface, admin surface, filesystem, network, and destructive-action risks.
• `contract_providers`: relative provider paths and functions for the real contracts.

Contract Providers

Use `contract_providers` to point to the real contract files. This is the current clean pattern:

'contract_providers' => [
    'install_contract' => [
        'path' => 'addons/example_notes/bootstrap/install_contract.php',
        'trusted_by' => 'installer',
    ],
    'schema_contract' => [
        'path' => 'addons/example_notes/src/schema_contract.php',
        'trusted_by' => 'installer',
    ],
    'permissions_contract' => [
        'path' => 'addons/example_notes/src/permissions_contract.php',
        'function' => 'amv_example_notes_permissions_contract',
        'trusted_by' => 'installer_aem',
    ],
    'route_contract' => [
        'path' => 'addons/example_notes/routes/routes.php',
        'function' => 'amv_example_notes_routes_contract',
        'trusted_by' => 'admin_aem',
    ],
    'admin_controller' => [
        'path' => 'addons/example_notes/src/admin_runtime.php',
        'handler' => 'amv_example_notes_admin_route',
        'trusted_by' => 'admin_runtime_after_route_acceptance',
    ],
    'public_targets' => [
        'path' => 'addons/example_notes/src/public_targets.php',
        'function' => 'amv_example_notes_public_target_provider',
        'trusted_by' => 'menu_manager_aem_frontend_target_selection',
    ],
],

Provider paths must be relative to the Amvionlie app root after deployment. Do not use absolute local paths.

Correct Ownership

• Permissions belong in `src/permissions_contract.php`.
• Routes, route permissions, admin targets, and public target provider references belong in `routes/routes.php`.
• Schema belongs in `src/schema_contract.php`.
• Install execution pointers belong in `bootstrap/install_contract.php`.
• Public target records and frontend access metadata belong near `src/public_targets.php`.
• Manifest points to those places and describes the package.

Legacy Or Transitional Fields

Older docs and some current code may mention:

• `paths`
• `permissions`
• `routes_contract`
• `admin_surface_contract`
• `frontend_contract`
• `admin_routes`
• `public_routes`
• `admin_navigation`
• `admin_menu`

Do not start new addon work from those fields as primary truth. If they appear in an existing addon, treat them as compatibility or cleanup targets and map them into the governed contract-provider shape.

Identity Fields

`product_uuid` is the real lifecycle identity. New governed addons should always ship a stable `product_uuid`.

`package_uuid` identifies one package artifact. Use a fresh package UUID when you build a new release ZIP, even when `product_uuid` stays the same.

`addon_key` is the machine key. It should match the folder name because discovery flags mismatches.

`slug` is a URL/path alias, not lifecycle identity.

Version Rule

Use the governed Amvionlie version format:

v0.0001 Alpha

Pre-1.0 builds use `v0.xxxx`. The lifecycle suffix is spaced and title case: `Alpha`, `Beta`, or `RC`. `v1.0000` is reserved for the first major release line.

Risk Declarations

Risk declarations should be honest and compact:

'risk_declarations' => [
    'filesystem_write' => false,
    'database_schema' => true,
    'database_data' => true,
    'public_surface' => true,
    'admin_surface' => true,
    'external_network' => false,
    'destructive_actions' => true,
    'notes' => 'Owns example note tables and public note routes.',
],

Final Check

Before packaging, ask:

• Does the manifest only describe and point?
• Does each contract own its own detailed truth?
• Are permissions declared once?
• Are routes declared once?
• Can Installer and system governance find the real files without guessing?

Related pages: Addon Development/Install Contract, Addon Development/Permissions Contract Basics, Reference Samples/Sample Manifest, Reference Samples/Current Addon Contract Shape.