TenantAtlas/specs/389-governance-inbox-resolution-intake-v1/contracts/status-mapping.md

# Status Mapping Contract

**Feature**: 389 - Governance Inbox Resolution Intake v1
**Status**: Contract for later implementation

## Allowed Inbox Statuses

V1 allows only these statuses:

| Status | Default visibility | Meaning |
| --- | --- | --- |
| `needs_attention` | Visible | Required input or preparation work needs operator attention. |
| `needs_recheck` | Visible | Persisted state may be stale, unsafe, unknown, hidden, or too expensive to classify in list view. |
| `waiting` | Visible | A current, scope-valid, context-valid, visible operation is running. |
| `ready_to_continue` | Visible | Current step can continue for this viewer. |
| `failed` | Visible | Current, scope-valid failure needs attention. |
| `blocked` | Visible | Current viewer cannot execute next action but may inspect, or case is blocked. |
| `completed` | Hidden by default | No active work. May appear only in explicit history/completed filters. |
| `cancelled` | Hidden by default | No active work. May appear only in explicit history filters. |
| `superseded` | Hidden by default | No active work. May appear only in explicit history filters. |

## Severity Mapping

| Inbox status | Severity |
| --- | --- |
| `failed` | `high` |
| `blocked` | `high` |
| `needs_attention` | `medium` |
| `needs_recheck` | `medium` |
| `ready_to_continue` | `medium` |
| `waiting` | `info` |
| `completed` | `info` |
| `cancelled` | `info` |
| `superseded` | `info` |

Do not use critical severity for ordinary review publication preparation gaps.

## Case and Step Mapping

| Source condition | Inbox status | Primary action | Notes |
| --- | --- | --- | --- |
| Case `completed` | `completed` | None by default | Hidden from active inbox. |
| Case `cancelled` | `cancelled` | None by default | Hidden from active inbox. |
| Case `superseded` | `superseded` | None by default | Hidden from active inbox. |
| Case `blocked` and viewer can inspect | `blocked` | Inspect preparation | Viewer-relative. Do not persist. |
| Current step actionable and viewer can execute | `ready_to_continue` | Continue preparation | Only if proof/currentness does not contradict continuation. |
| Current step actionable but viewer cannot execute and can inspect | `blocked` | Inspect preparation | Resolution Page remains inspection-only. |
| Current step running and linked operation is current, scope-valid, context-valid, expected type, and visible | `waiting` | Continue preparation or Open operation | Open operation can be primary only when safest. |
| Current step running but operation validation fails | `needs_recheck` | Continue preparation | Do not render operation ID or URL. |
| Current step failed and failed proof is current, scope-valid, context-valid, and visible | `failed` | Continue preparation | Do not infer from stale operation status. |
| Current step failed but failure cannot be proven current and safe | `needs_recheck` | Continue preparation | Conservative fallback. |
| Required proof/input missing or stale and safe summary says operator work is needed | `needs_attention` | Continue preparation | Human reason such as `Required reports are missing`. |
| Proof status hidden, unknown, operator-limited, inspection-only, failed, stale, or unsafe for completion | `needs_recheck` or `needs_attention` | Continue preparation | Never produce `ready_to_continue`. |
| Persisted state cannot be cheaply and safely classified | `needs_recheck` | Continue preparation | Default fail-closed behavior. |

## Needs-Recheck Fallback Rules

Use `needs_recheck` when any of the following is true:

- linked operation may be stale.
- linked operation belongs to another workspace, environment, review, case, or step.
- operation type is missing or unexpected.
- OperationRun completed or failed after the case/step state was written and no current safe summary resolves it.
- proof/currentness summary is missing, unknown, stale, hidden, failed, inspection-only, or operator-limited.
- proof summary contains only persisted raw metadata without Spec 388 validation.
- currentness validation is too expensive for list rendering.
- provider cannot safely decide between waiting, failed, and ready-to-continue.

`needs_recheck` is not an error. It is the safe list-view route back to the Resolution Page.

## OperationRun Link Eligibility

Render operation ID, operation label, operation URL, or `Open operation` only when every check is true:

| Check | Required rule |
| --- | --- |
| Workspace | `operation_runs.workspace_id` equals case workspace. |
| Environment | `operation_runs.managed_environment_id` equals case environment where environment-scoped. |
| Review context | Operation context or safe proof relation matches the case EnvironmentReview where applicable. |
| Case context | Operation context or safe proof relation matches the displayed ReviewPublicationResolutionCase where applicable. |
| Step context | Operation belongs to current step or current safe proof summary for that step. |
| Expected type | Operation type/action is expected for the current step. |
| Currentness | Spec 388 currentness/visibility/usability permits disclosure. |
| RBAC | Current user can view the OperationRun. |

If any check fails:

- do not render `operation_run_id`.
- do not render operation URL.
- do not render `Open operation`.
- show `Operation is running` without a link only when running state itself is safe.
- otherwise show `Needs re-check`.

## Viewer-Relative Behavior

Inbox status is computed for the current viewer:

- An executor may see `ready_to_continue`.
- A read-only operator may see `blocked` or inspection-only behavior.
- A customer-facing user must see no internal item.

The computed inbox status must never be written back to `review_publication_resolution_cases.status`.

## Human Summary Labels

Allowed default reason summaries:

- Required reports are missing.
- Evidence needs to be collected.
- Review needs to be refreshed.
- Export needs to be prepared.
- Operation failed while preparing the review.
- Waiting for operation to finish.
- Publication preparation can continue.
- Preparation status needs to be refreshed.
- You can inspect this preparation, but cannot execute the next action.

Forbidden default reason summaries:

- internal step keys.
- `proof_currentness=stale`.
- `StoredReport missing`.
- `OperationRun failed`.
- `resolution_step failed`.
- `readiness_fingerprint mismatch`.
- proof reason codes.
- `operator_limited`.
- `current_step_key`.

## Sorting Rank

Use this rank when adding the source family to the existing Governance Inbox ordering:

| Inbox status | Recommended urgency rank |
| --- | --- |
| `failed` | 0 |
| `blocked` | 1 |
| `needs_attention` | 2 |
| `needs_recheck` | 3 |
| `ready_to_continue` | 4 |
| `waiting` | 5 |
| inactive history statuses | not shown by default |

Inside equal rank, sort newest `updated_at` first if the existing inbox sort permits it.

## Updated-Date Filter Presets

V1 updated-date filtering is bounded to these presets:

- `Any time`
- `Last 24 hours`
- `Last 7 days`
- `Last 30 days`

Custom date ranges, free-form dates, saved filter views, and generic date-filter registries are out of scope for Spec 389.