TenantAtlas/specs/082-action-surface-contract/research.md

# Research — Action Surface Contract + CI Enforcement

This document resolves planning unknowns for Spec 082 and records key design decisions.

## Decision 1 — Scope enumeration (Tenant + Admin panels; exclude Widgets)

**Decision**: The validator enumerates in-scope Filament classes by scanning `app/Filament/**` for Resources, Pages, and RelationManagers and then filtering to:
- `app/Filament/Resources/**` (tenant panel discovery)
- `app/Filament/Pages/**` (tenant panel discovery)
- `app/Filament/RelationManagers/**` (used by resources)
- plus any admin-panel explicit resources/pages registered via `app/Providers/Filament/AdminPanelProvider.php`

Widgets are explicitly excluded.

**Rationale**:
- Matches clarified spec scope (Tenant + Admin panels; Resources/Pages/RelationManagers; exclude Widgets).
- Deterministic and fast (filesystem + reflection; no UI runtime required).
- Aligns with existing repo patterns (guard tests that scan filesystem and fail with actionable output).

**Alternatives considered**:
- Discovering via Filament panel runtime discovery: rejected (adds runtime coupling and can be non-deterministic in CI).
- Enumerating only by filesystem: accepted as baseline, but we still need a small allowlist for admin explicit registrations.

## Decision 2 — Declaration attachment mechanism

**Decision**: Each in-scope class provides a declaration via a static method (e.g., `public static function actionSurfaceDeclaration(): ActionSurfaceDeclaration`).

**Rationale**:
- PHP-first, simple, no attribute parsing or config conventions.
- Easy to require/validate by reflection.
- Plays well with existing Filament static patterns (Resources already use statics like `$recordTitleAttribute`).

**Alternatives considered**:
- PHP 8 attributes: rejected for now (slower adoption, harder to keep structured without additional tooling).
- Central registry config: rejected (drifts away from the component, discourages ownership).

## Decision 3 — Contract enforcement: “declare or exempt” + representative runtime checks

**Decision**: CI enforces that each in-scope class has a declaration and that every required slot is either marked satisfied or has an explicit exemption with a non-empty reason.

The validator does not attempt to prove that every underlying Filament `table()` / `getHeaderActions()` actually contains those actions. Instead, representative runtime tests cover constitution-critical behavior (grouping, confirmation, RBAC semantics, canonical run links).

**Rationale**:
- Deterministic and robust across Filament internal changes.
- Avoids brittle source parsing and avoids needing Livewire/Filament runtime contexts.
- Still forces explicit human intent on each surface, which is the governance goal.

**Alternatives considered**:
- AST/static parsing of PHP to verify `->actions()` / `->bulkActions()` usage: rejected (high complexity and brittleness).
- Instantiating Filament objects and introspecting action definitions for every surface in CI: rejected initially (risk of boot/DI coupling). Representative runtime tests are used instead for critical guarantees.

## Decision 4 — Profiles and required “slots”

**Decision**: Model “profiles” that map to component archetypes (e.g., list-only, list+detail, read-only list, run-log list). Each profile defines required slots:
- List header actions
- List row actions (max 2 visible; rest in “More”)
- List bulk actions (grouped; “More” label)
- List empty-state actions
- Detail header actions (if the component has a detail view/edit/view page)

**Rationale**:
- Keeps enforcement simple and consistent.
- Allows targeted exceptions by profile without exploding per-component logic.

**Alternatives considered**:
- One giant universal profile: rejected (too many exemptions, low signal).

## Decision 5 — Exemption policy

**Decision**: Exemptions require:
- a non-empty reason string
- optional tracking reference (issue/PR link)
- no deadline requirement

**Rationale**:
- Matches clarified spec.
- Keeps CI deterministic (no time-based expiry).

**Alternatives considered**:
- Required expiry dates: rejected (creates “time bombs” in CI).

## Decision 6 — Standard grouping label and safe-default Export

**Decision**:
- The canonical group label for secondary row actions and bulk action groups is `More`.
- For `ReadOnly` + `RunLog` profiles, the default expected safe bulk action is `Export` (otherwise exemption required).

**Rationale**:
- Matches clarified spec.
- Provides a consistent, predictable UX baseline.

**Alternatives considered**:
- Allowing arbitrary labels: rejected (inconsistent UX; harder to audit).

## Decision 7 — Typed confirmation threshold

**Decision**: The contract model includes a `requiresTypedConfirmation` flag for actions that are destructive/irreversible, affect > 25 records, or change access/credentials/safety gates.

**Rationale**:
- Matches clarified spec.
- Keeps enforcement declarative and reviewable.

**Alternatives considered**:
- Always requiring typed confirmations: rejected (too heavy for routine admin workflows).