ahmido
4cf2712f92
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. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #421
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
|