# Resolution Case Contract

Status: Draft for Spec 350  
Scope: Derived operator-guidance envelope only

## Purpose

`ResolutionCase` is the shared productized guidance object for current-release operator issues that already exist in repo truth.

It answers:

1. What is wrong?
2. Why does it matter?
3. What is the dominant next step?
4. Is that step navigation/disclosure-only or an existing safe executable path?
5. Which source records prove this guidance?

This contract must wrap existing guidance producers. It must not replace them or persist a second truth model.

## Design Constraints

- Derived only; no persistence
- Scope explicit
- Exactly one primary action
- Source-traceable
- Safe-execution aware
- Provider-neutral in the core contract
- Technical details secondary

## Required Shape

```php
[
    'key' => 'review_pack.output_not_customer_ready',
    'scope' => [
        'type' => 'environment',
        'workspace_id' => 1,
        'managed_environment_id' => 41,
        'source_surface' => 'customer_review_workspace',
    ],
    'severity' => 'warning',
    'status' => 'action_required',

    'title' => 'Output not customer-ready',
    'reason' => 'The published review is based on incomplete evidence.',
    'impact' => 'This review pack should not be shared externally until the evidence basis is refreshed.',

    'primary_action' => [
        'key' => 'environment_review.open_current_limitations',
        'label' => 'Inspect review blockers',
        'type' => 'navigation',
        'url' => '...',
        'capability' => null,
        'requires_confirmation' => false,
        'audit_event' => null,
        'operation_run_type' => null,
    ],

    'secondary_actions' => [
        [
            'key' => 'evidence.open_basis',
            'label' => 'Open evidence basis',
            'type' => 'navigation',
            'url' => '...',
        ],
    ],

    'source_refs' => [
        ['type' => 'environment_review', 'id' => 6],
        ['type' => 'review_pack', 'id' => 8],
    ],

    'evidence_refs' => [
        ['type' => 'evidence_snapshot', 'id' => 8],
    ],

    'technical_details' => [
        'review_status' => 'published',
        'output_readiness' => 'publication_blocked',
        'evidence_state' => 'missing',
    ],
]
```

## Required Fields

| Field | Requirement |
|---|---|
| `key` | Stable, repo-owned case identifier |
| `scope` | Explicit workspace/environment/review/operation/provider scope |
| `severity` | Presentation-only severity |
| `status` | Presentation-only actionability state |
| `title` | Primary operator-facing issue label |
| `reason` | Plain-language explanation of the dominant cause |
| `impact` | Why this matters now |
| `primary_action` | Exactly one dominant next step |
| `secondary_actions` | Optional supporting navigation/disclosure actions |
| `source_refs` | Required repo-backed source references |
| `evidence_refs` | Optional but required when evidence truth is central to the case |
| `technical_details` | Secondary disclosure payload only |

## Allowed Scope Types

- `workspace`
- `environment`
- `review`
- `review_pack`
- `evidence`
- `provider_connection`
- `operation`
- `finding`
- `system`

## Allowed Severities

- `critical`
- `warning`
- `info`
- `success`

## Allowed Statuses

- `action_required`
- `blocked`
- `needs_review`
- `informational`
- `ready`
- `resolved`
- `unknown`

## Existing Runtime Inputs To Reuse

| Existing producer | How it maps into `ResolutionCase` |
|---|---|
| `ReviewPackOutputResolutionGuidance` | `title`, `reason`, `impact`, `primary_action`, `secondary_actions`, `technical_details`, and review-output evidence-basis truth |
| `OperationUxPresenter` | dominant issue/action text for operation follow-up cases |
| `OperatorExplanationPattern` | trust/reliability/next-action semantics that can inform title/reason/impact |
| `EnterpriseDetailSectionFactory::primaryNextStep()` | existing primary-next-step shape for action text and supporting guidance |
| provider readiness summaries and required-permissions guidance | provider-owned issue/reason/action sources |

## Hard Rules

- Do not persist resolution cases.
- Do not create source refs that cannot be resolved to repo-backed records.
- Do not expose more than one primary action.
- Do not encode hidden scope.
- Do not force executable action metadata onto producers that only support navigation, qualified download, or disclosure today.
- Do not introduce a standalone evidence-basis adapter in v1 while review-output guidance already owns that truth.
- Do not use the contract as a generic workflow-state machine.