ahmido 4cf2712f92 feat: operator resolution guidance framework v1 (spec 350) (#421 )

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

2026-06-03 15:35:25 +00:00

2.9 KiB

Raw Permalink Blame History

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

[
    '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

2.9 KiB Raw Permalink Blame History