TenantAtlas/specs/169-action-surface-v11/research.md

# Phase 0 Research: Action Surface Contract v1.1

## Decision: Add a first-class `ActionSurfaceType` enum to `ActionSurfaceDeclaration` while keeping `ActionSurfaceProfile`

**Rationale**: `ActionSurfaceProfile` currently governs which slots are required, but it does not distinguish constitution-level interaction semantics. The repo needs to tell the difference between clickable-row CRUD or registry surfaces and legitimate explicit-inspect queue or audit surfaces. A first-class `surfaceType` field makes that distinction explicit without forcing slot requirements and behavioral rules into the same enum.

**Alternatives considered**:
- Replace `ActionSurfaceProfile` entirely: rejected because slot requirements and constitution surface semantics are different concerns and existing declarations already rely on the profile model.
- Derive surface type from metadata or inferred heuristics: rejected because the clarified spec requires a first-class declaration-level field and because inference would keep validator failures ambiguous.

## Decision: Keep inspect-model compatibility rules close to the existing contract stack

**Rationale**: The narrowest implementation is one new enum plus validator logic and small helper methods where needed. That keeps the feature inside the current `ActionSurfaceDeclaration` / `ActionSurfaceValidator` architecture and avoids introducing a second action-governance registry or policy layer.

**Alternatives considered**:
- Create a new `ActionSurfaceTypeDefinition` registry or service: rejected because the slice does not justify another framework layer.
- Enforce the new rules in tests only: rejected because the main validator must become the primary contract gate, not just the rendered tests.

## Decision: Extend primary discovery to declared system-panel table pages only

**Rationale**: The six enrolled system list pages already have declarations and targeted tests, but the main discovery pass still excludes them. The safest extension is to scan `app/Filament/System/Pages/**` narrowly for declared, table-backed pages so the main validator covers them without accidentally enrolling auth, dashboard, widget, or other deferred system surfaces.

**Alternatives considered**:
- Hardcode an allowlist of six system classes: rejected because it would preserve a parallel discovery model and create more manual maintenance.
- Broadly discover every page under `app/Filament/System/Pages`: rejected because it would sweep in deferred surfaces such as auth, runbooks, and break-glass tooling.

## Decision: Keep current panel-scope metadata unchanged for this slice

**Rationale**: The feature needs system-panel discovery coverage, not a new panel taxonomy. The current codebase does not have an active consumer that requires a `System` panel scope enum, so adding one now would widen the slice without solving the immediate operator problem.

**Alternatives considered**:
- Add `ActionSurfacePanelScope::System`: rejected because no current validation or runtime rule depends on it, and the spec does not require it.
- Infer system scope through panel providers and extend all scope tests: rejected as unnecessary expansion beyond the current feature goal.

## Decision: Split enforcement between fast validator tests and representative Livewire render tests

**Rationale**: Validator tests are the right seam for declaration-time rules such as required `surfaceType`, allowed affordance combinations, and required exception reasons. Livewire render tests are the right seam for business-visible behavior such as row click actually existing, explicit inspect actually preserving context, and `More` groups actually rendering helpers first, workflow actions next, and destructive actions last.

**Alternatives considered**:
- Declaration-only guard coverage: rejected because the constitution explicitly rejects declaration-only conformance when rendered behavior drifts.
- Browser-only coverage: rejected because it would be slower, broader, and less precise than the current Livewire table guard pattern already used in the repo.

## Decision: Treat `PrimaryLinkColumn` as an exception path that requires an explicit reason

**Rationale**: The spec needs stronger control over linked-column inspect affordances, but the repo does not need a dedicated exception object or secondary taxonomy for that. Requiring an explicit reason on the declaration is enough to keep the exception visible and reviewable.

**Alternatives considered**:
- Allow `PrimaryLinkColumn` anywhere the enum is present: rejected because the constitution requires a concrete reason when row click is not the correct primary inspect model.
- Add a new exception class hierarchy: rejected because it would add structure without a separate current-release problem to solve.

## Decision: Keep the two reference docs in lockstep with validator behavior

**Rationale**: The repo already has two developer-facing references for this domain: `docs/ui/action-surface-contract.md` and `docs/product/standards/filament-actions-ux.md`. The feature should update both together so implementation guidance, spec language, and guard behavior stay aligned.

**Alternatives considered**:
- Update only the constitution: rejected because day-to-day implementation guidance lives in the shorter reference docs.
- Update only one doc and let the other lag: rejected because that would recreate the ambiguity the feature is meant to remove.