TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/contracts/resolution-case-contract.md

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

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