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:

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:

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:

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.