Current Addon Contract Shape

Purpose

This page summarizes the current governed addon shape for quick reference.

Minimum Files

addons/example_addon/
  manifest.php
  README.md
  CHANGELOG.md
  bootstrap/install_contract.php
  routes/routes.php
  src/schema_contract.php
  src/permissions_contract.php
  src/admin_runtime.php
  src/public_targets.php
  tests/smoke.php

Not every addon needs every file, but missing files should be intentional and explainable.

Truth Ownership

• `manifest.php` owns package identity, display metadata, risk declarations, classification hints, and contract-provider pointers.
• `bootstrap/install_contract.php` owns installer-facing provider/function pointers and lifecycle execution boundaries.
• `src/permissions_contract.php` owns permission definitions and recommended role grants.
• `routes/routes.php` owns route definitions, route permission metadata, admin targets, and public target provider references.
• `src/public_targets.php` owns public target records and frontend access metadata.
• `src/schema_contract.php` owns schema table names, SQL, and schema apply behavior.
• Runtime files own rendering and request handling after the governed route/access decision is made.

What Not To Duplicate

Do not copy the full permission catalog into manifest and install contract.

Do not copy the full route table into manifest and install contract.

Do not make Dashboard, Menu Manager, Addons Manager, or Installer infer addon-owned domain truth from copied fragments when a governed contract file exists.

Verification

Lint changed PHP files, run the addon smoke test when available, and verify key URLs return HTTP 200.

For frontend RBAC, verify both allowed and denied paths. Working by accident is still a little too spicy for release work.