# Resolution Action Contract

Status: Draft for Spec 350  
Scope: Dominant next-step contract only

## Purpose

`ResolutionAction` is the action envelope inside a `ResolutionCase`.

It standardizes what the operator should do next and whether that next step remains navigation/disclosure only or can safely reuse an existing source-owned executable path.

Repo note: this contract is intentionally named `ResolutionAction` to avoid colliding with the existing dashboard-local `RecommendedAction` schema in `specs/266-tenant-dashboard-productization-v1/contracts/tenant-dashboard-productization.openapi.yaml`.

## Hard Rules

- Each `ResolutionCase` has exactly one `primary_action`.
- The default v1 bias is `navigation`, `download`, `disclosure`, or `none`.
- Unsupported or unsafe executable actions must degrade to a non-executable action type.
- No fake fix buttons.

## Required Shape

```php
[
    'key' => 'provider_readiness.open_required_permissions',
    'label' => 'Open required permissions',
    'type' => 'navigation',
    'url' => '...',
    'capability' => null,
    'requires_confirmation' => false,
    'audit_event' => null,
    'operation_run_type' => null,
    'disabled_reason' => null,
]
```

## Allowed Action Types

- `navigation`
- `workspace_filtered_link`
- `environment_link`
- `download`
- `disclosure`
- `none`
- `domain_action` only when the source surface already owns the full safety envelope
- `operation_action` only when the source surface already owns the full safety envelope

## Required Safety Fields For Executable Actions

If `type` is `domain_action` or `operation_action`, the action must include:

- `capability`
- `requires_confirmation`
- `audit_event` or equivalent audit reason
- `operation_run_type` when the action is execution-backed

If any of those are unavailable, the action must become `navigation`, `download`, `disclosure`, or `none`.

## Existing Runtime Inputs To Reuse

| Existing producer | Contract expectation |
|---|---|
| scoped URL helpers | populate `url` for navigation/disclosure actions |
| current policy/capability checks | populate `capability` and `disabled_reason` where applicable |
| existing Filament action semantics | preserve confirmation and audit behavior only when the action is already source-owned and executable |
| `OperationRunLinks` | provide proof/detail destinations for operation follow-up |
| current qualified download labels | remain downloads, not disguised execution actions |

## Secondary Actions

Secondary actions are optional supporting actions. They must never compete visually or semantically with the primary action.

Allowed secondary examples:

- `Open evidence basis`
- `Open operation proof`
- `Review limitations`
- `Open provider readiness`

Forbidden secondary examples:

- duplicate copies of the primary action
- fake auto-remediation
- destructive actions without the same safety metadata requirements