# Data Model — Action Surface Contract

This feature introduces a small, explicit model for declaring and validating action surfaces.

## Entities

### ActionSurfaceDeclaration

Represents the contract declaration attached to a Filament component.

**Fields**:
- `version` (int): schema version for forward compatibility (start at `1`).
- `componentType` (enum): `Resource | Page | RelationManager`.
- `className` (string): fully qualified class name (filled by validator when reporting).
- `panelScope` (enum): `Tenant | Admin` (filled by validator based on discovery context).
- `profile` (enum): contract profile (see below).
- `slots` (map<ActionSurfaceSlot, SlotRequirement>): required and optional slots for this component.
- `exemptions` (list<ActionSurfaceExemption>): explicit exemptions with reason.
- `defaults` (ActionSurfaceDefaults): shared UX defaults (e.g., `moreGroupLabel`).

### ActionSurfaceSlot (enum)

Discrete UI locations that may contain actions.

Proposed baseline slots:
- `ListHeader`
- `ListRowPrimary`
- `ListRowMoreMenu`
- `ListBulkMoreGroup`
- `ListEmptyState`
- `DetailHeader`

(Profiles determine which slots are required.)

### SlotRequirement

Requirement status for a single slot.

**Fields**:
- `status` (enum): `Satisfied | Exempt`.
- `details` (optional string): freeform explanation or expected actions.
- `requiresTypedConfirmation` (bool, default false): indicates the actions in this slot require typed confirmation.

### ActionSurfaceExemption

Represents a justified opt-out for a required slot.

**Fields**:
- `slot` (ActionSurfaceSlot)
- `reason` (string, required, non-empty)
- `trackingRef` (optional string)

### ActionSurfaceDefaults

Shared defaults enforced/checked by CI.

**Fields**:
- `moreGroupLabel` (string, required): must be `More`.
- `exportIsDefaultBulkActionForReadOnly` (bool): default expectation for ReadOnly + RunLog profiles.

## Profiles (enum)

Profiles map component archetypes to required slots.

Proposed profiles (initial set):
- `CrudListAndEdit`: list + edit page exists.
- `CrudListAndView`: list + view page exists.
- `ListOnlyReadOnly`: list-only, no edit/view.
- `RunLog`: operational log list (read-only, expects Export bulk action by default).

## Validation rules (CI)

For each in-scope class:
- Must define an action surface declaration.
- Must select a profile.
- For every slot required by that profile:
  - slot must be present with `Satisfied`, OR
  - slot must be marked `Exempt` and there must be a matching exemption with non-empty reason.
- Defaults must include `moreGroupLabel = "More"`.

Note: The validator is intentionally declarative; it validates the presence and completeness of the declaration (and exemptions), not the exact runtime Filament action configuration.