02cc12f73f
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 59s
Implemented the first version of the operator resolution guidance framework. Added new foundation classes (ResolutionCase, ResolutionAction) and a ReviewPackOutputResolutionAdapter. Updated the Customer Review Workspace and Environment Review Resource to use the new adapter. Added extensive test coverage for the framework and UI integrations.
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# 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
|