TenantAtlas/specs/389-governance-inbox-resolution-intake-v1/contracts/review-publication-resolution-inbox-item.md

# Review Publication Resolution Inbox Item Contract

**Feature**: 389 - Governance Inbox Resolution Intake v1
**Status**: Contract for later implementation
**Scope**: One concrete Governance Inbox item type for Review Publication Resolution Cases

## Purpose

This contract maps existing `ReviewPublicationResolutionCase` records into operator-facing Governance Inbox items. It is a read-only intake contract. It must not become a generic workflow, task, adapter, or proof/currentness abstraction.

## Allowed Item Type

Only this item type is allowed in Spec 389:

```text
review_publication_resolution
```

Do not introduce generic item types such as `resolution_case`, `workflow_task`, `action_case`, `generic_readiness_item`, or `generic_resolution_item`.

## Source Truth

The item may consume:

- `ReviewPublicationResolutionCase` fields and relationships that are already scoped to the current workspace.
- The current `ReviewPublicationResolutionStep`, loaded through the case relationship.
- Existing safe summaries from Review Publication Resolution and Spec 388 proof/currentness logic.
- Existing policy/authorizer answers for the current viewer.
- Existing validated links to Resolution, Review, and OperationRun pages.

The item must not independently infer readiness or proof currentness from raw:

- OperationRun metadata.
- StoredReport metadata.
- EvidenceSnapshot metadata.
- ReviewOutput metadata.
- ReviewPack metadata.
- persisted `proof_summary`.
- persisted `operation_run_id`.
- `readiness_fingerprint`.
- internal step keys.

If safe classification cannot be completed cheaply in list rendering, the item status must be `needs_recheck` and the primary action must navigate to the Resolution Page.

## Existing Governance Inbox Entry Shape

The existing Governance Inbox renderer consumes section entries and normalizes them into operator items. A Review Publication Resolution entry should follow this shape unless implementation introduces a small source-specific DTO that is immediately normalized into the same fields:

| Existing entry key | Required | Contract |
| --- | --- | --- |
| `family_key` | Yes | `review_publication_resolution` |
| `source_model` | Yes | `App\Models\ReviewPublicationResolutionCase` |
| `source_key` | Yes | Case key as an internal source reference, not rendered as the item title. |
| `managed_environment_id` | Yes | Environment ID for environment-scoped cases. |
| `tenant_label` | Yes | Safe environment label visible to the viewer. |
| `headline` | Yes | Operator-facing title, for example `Review can't be published yet`. |
| `subline` | Optional | Safe review label, owner, or last-update context. No raw IDs unless already safe and useful. |
| `urgency_rank` | Yes | Sort rank derived from inbox status. |
| `status_label` | Yes | Human label for mapped inbox status. |
| `destination_url` | Yes when inspectable | Resolution Page URL or, only if primary operation action is safer and validated, OperationRun URL. |
| `decision_label` | Yes | Human decision label such as `Continue review publication preparation`. |
| `reason_label` | Yes | Human reason summary. No internal step/proof reason keys. |
| `impact_label` | Yes | Human impact summary, for example `Review publication remains blocked`. |
| `owner_label` | Optional | Assignee/creator/current owner if available and safe. |
| `due_label` | Optional | `Updated <relative time>` or existing due label pattern. |
| `evidence_label` | Optional | Safe proof availability summary. |
| `evidence_state` | Optional | Display state only, for example `available`, `missing`, `needs_recheck`. |
| `evidence_path_label` | Optional | Safe link label only. |
| `evidence_path_url` | Optional | Validated Review/Resolution/Operation URL only. |
| `exception_label` | Optional | Usually `No accepted-risk state`. |
| `primary_action_label` | Yes | `Continue preparation`, `Inspect preparation`, or validated `Open operation`. |
| `primary_action_url` | Yes when inspectable | URL to the allowed page. |
| `back_label` | Optional | Existing navigation context label. |

## Conceptual Item Fields

If a DTO is used, it must still represent only display-safe fields:

```php
final readonly class GovernanceInboxItem
{
    public function __construct(
        public string $type,
        public string $key,
        public string $status,
        public string $severity,
        public string $title,
        public string $summary,
        public string $nextActionLabel,
        public ?string $nextActionUrl,
        public ?string $environmentLabel,
        public ?string $subjectLabel,
        public ?CarbonImmutable $updatedAt,
        public ?CarbonImmutable $createdAt,
        public ?int $ownerId = null,
        public array $badges = [],
        public array $safeMetadata = [],
    ) {}
}
```

The DTO is optional. If added, it must be concrete to this source family or broadly display-only without creating a generic intake registry.

## Required Display Semantics

Each item must answer:

- What needs attention?
- Why?
- Which review/environment is affected?
- What is the next safe action?
- Is there current proof?
- Who owns it, if known?
- Where does the operator continue?

Default examples:

| Status | Title | Reason | Primary action |
| --- | --- | --- | --- |
| `needs_attention` | Review can't be published yet | Required reports are missing | Continue preparation |
| `waiting` | Review preparation running | Waiting for operation to finish | Continue preparation or validated Open operation |
| `failed` | Review preparation needs attention | Operation failed while preparing the review | Continue preparation |
| `ready_to_continue` | Review preparation can continue | Publication preparation can continue | Continue preparation |
| `needs_recheck` | Review preparation needs re-check | Preparation status needs to be refreshed | Continue preparation |
| `blocked` | Review preparation needs operator access | You can inspect this preparation, but cannot execute the next action | Inspect preparation |

## Safe Metadata Rules

`safe_metadata`, entry context, linked records, and secondary actions may include:

- display status.
- display severity.
- display step label.
- display proof label.
- environment label.
- review label.
- validated action labels and URLs.
- owner display label.
- last updated timestamp.

They must not include:

- raw provider payloads.
- raw Graph responses.
- raw evidence, report, review output, or review pack payloads.
- raw exception messages.
- secrets or tokens.
- `readiness_fingerprint`.
- internal proof reason codes by default.
- internal step keys by default.
- raw `operation_run_id` unless the operation link is fully validated and the ID is needed for an authorized link label.
- StoredReport IDs unless scope-safe and explicitly needed.
- EvidenceSnapshot IDs unless scope-safe and explicitly needed.
- OperationRun metadata.

## Link Contract

### Resolution Page

Use the existing Review Publication Resolution Page as the default destination:

```text
EnvironmentReviewResource::environmentScopedUrl('resolve-publication', ['record' => $review], $tenant)
```

The link is allowed only when the viewer may inspect the case. If the viewer can inspect but not execute, the label should be `Inspect preparation` or `Continue preparation` and the Resolution Page must remain inspection-only.

### Review Detail

`Open review` is secondary and allowed only when the viewer can view the Review in the same workspace/environment context.

### OperationRun Detail

`Open operation` is allowed only when all checks pass:

- same workspace.
- same environment where applicable.
- same EnvironmentReview context where applicable.
- same Review Publication Resolution Case context where available.
- operation belongs to the current step or current safe proof summary.
- operation/action type is expected for the current step.
- Spec 388 currentness/usability/visibility is acceptable for disclosure.
- current user can view the OperationRun.

Permission alone is not sufficient. Do not build operation URLs directly from persisted step metadata. `Open operation` may be the primary action only for a validated `waiting` item where opening the operation is the safest next action; otherwise it must be secondary or hidden. If any check fails, render a non-linked safe label such as `Operation is running` or fallback to `Needs re-check`.

## RBAC and Scope

The provider/query must hide items that the viewer cannot access. It must not reveal inaccessible counts.

Required visibility checks:

- workspace membership.
- environment entitlement.
- subject Review visibility.
- `ReviewPublicationResolutionCasePolicy::view`.
- safe summary visibility.
- customer-facing users and customer workspace surfaces receive no internal item.

Viewer-relative status must not be persisted back to the case.

## Sorting Contract

Default active sorting:

1. `failed`
2. `blocked`
3. `needs_attention`
4. `needs_recheck`
5. `ready_to_continue`
6. `waiting`
7. newest `updated_at` inside each group

If the existing Governance Inbox lane sorter is reused, map urgency ranks to preserve that order inside the new source family.

## Negative Contract

Spec 389 does not allow:

- inline provider checks.
- inline Entra scans.
- inline evidence collection.
- inline review refresh.
- inline export preparation.
- inline cancel resolution.
- inline publish.
- new top-level navigation.
- new global search Resource.
- generic workflow or task model.
- generic adapter registry.