# Research: Portfolio Triage Arrival Context

## Decision: Reuse existing workspace `reason_context` and destination payloads as the source of tenant-arrival intent

### Rationale

`WorkspaceOverviewBuilder` already emits bounded `reason_context` payloads for backup-health and recovery-evidence attention items, along with capability-aware destination metadata and supporting claim-boundary copy. Reusing that structure preserves the current truth model and avoids inventing a second concern taxonomy just for navigation continuity.

### Alternatives considered

- Recompute arrival reason solely from tenant state on the destination page: rejected because it loses the specific reason the operator acted on and cannot preserve source-surface intent.
- Persist portfolio triage sessions: rejected because the continuity need is request-scoped and does not justify new storage or lifecycle overhead.

## Decision: Carry tenant-dashboard arrival state in one bounded, versioned base64url token

### Rationale

The spec explicitly prefers one small arrival-context abstraction over scattered ad hoc query params. The codebase already uses a versioned base64url token pattern for resume state, which provides deterministic encoding, bookmark safety, and graceful decode-to-null fallback without new persistence. The token will carry only allowlisted concern and return-routing metadata; current tenant truth remains re-derived on arrival.

### Alternatives considered

- Infer continuity from the HTTP referrer: rejected because the spec forbids referrer-only inference and browser history is not reliable enough for operator-critical guidance.
- Add many plain dashboard query params such as `source`, `family`, `state`, `return_url`, and `return_filters`: rejected because that spreads continuity semantics across multiple surfaces and increases drift risk.
- Use a persisted triage session key: rejected because it adds new persistence for a problem that can be handled safely in the request.

## Decision: Keep existing backup and restore continuity query params on deeper destinations

### Rationale

`ListBackupSets`, `ListRestoreRuns`, and `ViewRestoreRun` already render bounded explanatory subheadings from `backup_health_reason` and `recovery_posture_reason`, and those behaviors are covered by existing regression tests. The new arrival feature should hand operators to those surfaces intact instead of replacing them with a second downstream continuity system.

### Alternatives considered

- Replace all downstream continuity with the new token: rejected because it would duplicate already-working continuity behavior and expand the scope well beyond tenant-dashboard arrival.
- Drop downstream continuity once the tenant dashboard receives an arrival block: rejected because operators still need semantic confirmation after following the next-step CTA.

## Decision: Render arrival continuity as the first non-lazy tenant dashboard widget

### Rationale

The tenant dashboard is currently composed from widgets, and the codebase already has a non-lazy tenant-banner pattern for high-priority contextual messaging. A dedicated first widget or section satisfies the placement requirement, stays additive, and avoids a dashboard view rewrite.

### Alternatives considered

- Rewrite the dashboard page layout or publish a custom page view: rejected because the spec explicitly avoids a dashboard redesign and the existing widget stack already supports this placement.
- Inject continuity into existing widgets like Recovery Readiness or Needs Attention: rejected because arrival continuity is a separate concern that should appear before the operator interprets domain widgets.

## Decision: Reuse existing query-driven tenant-registry triage state for the return path

### Rationale

`ListTenants` already sanitizes and reapplies `backup_posture`, `recovery_evidence`, and `triage_sort` from the query string on mount. Using the same allowlisted query contract for return links preserves operator flow without session state, back-button dependence, or a new navigation framework.

### Alternatives considered

- Store the previous URL in session and link back to it blindly: rejected because the spec wants an explicit, meaningful portfolio return path rather than browser-history dependence.
- Always return to an unfiltered tenant registry: rejected because it breaks multi-tenant triage continuity and forces the operator to reconstruct the filtered slice manually.

## Decision: Use existing capability-aware destination degradation rules for next-step CTAs

### Rationale

`WorkspaceOverviewBuilder` already emits disabled destinations with helper text when the current user cannot access the target surface. Reusing that pattern keeps next-step guidance truthful and consistent with the rest of the product under RBAC restrictions.

### Alternatives considered

- Hide next-step guidance entirely when access is limited: rejected because the operator still needs to understand what the normal next step would be and why it is unavailable.
- Leave the CTA visible and let it fail on click: rejected because the spec explicitly forbids misleading next-step guidance.

## Decision: Distinguish arrival reason from current tenant truth on the dashboard

### Rationale

The spec requires continuity copy to preserve why the operator arrived while still showing the latest truth if posture changed before the page loaded. The continuity block therefore needs two separate concepts: arrival reason and current-truth boundary. This keeps stale arrival context from becoming a false current claim.

### Alternatives considered

- Treat arrival reason as the current tenant posture until the next refresh: rejected because it can overstate or understate the latest truth.
- Ignore stale arrival context completely once current state changes: rejected because it breaks the operator's understanding of why the tenant was opened in the first place.