breadcrumb-the-shire/docs/reference-module-manifest-contract.md

# Module Manifest Contract (V1.1)

Letzte Aktualisierung: 2026-03-18

## Ziel

Verbindlicher Contract fuer `modules/*/module.php`, damit Module zur Runtime deterministisch geladen und validiert werden.

## Status

Dieses Dokument ist die kanonische (normative) Quelle fuer Manifest-, Runtime- und Guard-Regeln des Modul-Systems.
`/docs/reference-extension-readiness.md` referenziert diesen Contract und dupliziert keine Felddefinitionen.

## Aktivierung (`APP_ENABLED_MODULES`)

- nicht gesetzt: `config/modules.php` gilt.
- gesetzt und leer (`APP_ENABLED_MODULES=''`): keine Module.
- gesetzt mit Liste (`APP_ENABLED_MODULES='a,b'`): exakt diese Module.

## `permissions` Contract

`permissions` ist eine Objektliste:

```php
'permissions' => [
    [
        'key' => 'module.permission',
        'description' => 'Human readable text',
        'active' => true,      // optional, default true
        'is_system' => true,   // optional, default true
    ],
],
```

- `key` und `description` sind Pflichtfelder.
- Runtime-Sync erfolgt ueber `php bin/module-permissions-sync.php`.
- `module-runtime-sync` fuehrt diesen Sync automatisch aus.

## `scheduler_jobs` Contract

`scheduler_jobs` ist eine Objektliste mit vollem Default-Contract:

```php
'scheduler_jobs' => [
    [
        'job_key' => 'module.job',
        'handler' => App\\Scheduler\\MyJobHandler::class,
        'label' => 'Job label',
        'description' => 'Job description',
        'default_enabled' => true,
        'default_timezone' => 'Europe/Berlin',
        'default_schedule_type' => 'daily', // hourly|daily|weekly
        'default_schedule_interval' => 1,
        'default_schedule_time' => '02:00', // required for daily/weekly
        'default_schedule_weekdays_csv' => null, // weekly: e.g. '1,3,5'
        'default_catchup_once' => true,
        'allowed_schedule_types' => ['daily', 'weekly'],
    ],
],
```

- Manifest ist Source of Truth fuer Job-Metadaten und Defaults.
- Handler werden zur Laufzeit container-resolvable fuer `execute(...)` geladen.

## `ui_slots` Contract (V1.2)

Neue generische Slot-Typen:

- `topbar.right_item`: `{ key, template, permission?, order }`
- `layout.body_end_template`: `{ key, template, permission?, order }`
- `layout.head_style`: `{ key, path, permission?, order }`
- `runtime.component`: `{ key, script, export?, selector?, scope?, config_path?, default_config?, phase?, permission?, order }`

`runtime.component.phase` ist `early|default|late` (Default: `late`).

Abgrenzung CSS:

- `layout.head_style` = global auf allen Seiten.
- `asset_groups` = seiten-/kontextbezogen ueber `style_groups`.

## Guard-Regeln

- Route-Kollisionen sind fail-fast:
  - Modul vs Modul auf `target` und `path`.
  - Modul vs Core auf `path` beim Router-Boot.
- Layout-Provider duerfen reservierte Core-Keys nicht ueberschreiben (`moduleSlots`, `csrfKey`, `currentTenant`, ...).
- Layout-Provider-Top-Level-Keys muessen namespaced sein (`<module_id>.<key>`).

## Standard-Runbook

`php bin/module-runtime-sync.php` fuehrt in fester Reihenfolge aus:

1. `module-migrate`
2. `module-permissions-sync`
3. `module-build`
4. `module-assets-sync`

Der Output enthaelt eine deterministische Step-Summary (`migrate`, `permissions-sync`, `build`, `assets-sync`) inklusive `vendor_warnings_ignored=<n>`.
First-party Warnings/Notices/Deprecations gelten als Fehler (fail-fast).