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.