41 lines
4.8 KiB
Markdown
41 lines
4.8 KiB
Markdown
# Research: Canonical Operation Viewer Context Decoupling
|
|
|
|
## R-001: Authorization must remain run-first and direct-entitlement based
|
|
|
|
- **Decision**: Keep `OperationRunPolicy::view()` as the canonical authorization boundary for `/admin/operations/{run}` and keep its logic based on the run's workspace membership, direct tenant entitlement, and capability resolution by run type.
|
|
- **Rationale**: The existing policy already encodes the correct 404 versus 403 semantics: workspace non-members and users lacking entitlement to the run's tenant receive deny-as-not-found, while in-scope users missing a resolved capability receive forbidden. This matches Spec 143 and Spec 144 directly and avoids scattering authorization across header-context helpers.
|
|
- **Alternatives considered**:
|
|
- Move authorization into `TenantlessOperationRunViewer::mount()`: rejected because it would duplicate policy logic and increase the chance of 404 versus 403 drift.
|
|
- Authorize from selected tenant context instead of the run's tenant: rejected because that is the failure mode the spec is explicitly correcting.
|
|
|
|
## R-002: `OperateHubShell` should remain a display and navigation helper only
|
|
|
|
- **Decision**: Treat `OperateHubShell::activeEntitledTenant()` as the source for header labels, return affordances, and optional banner context, but not as a precondition for canonical viewer legitimacy.
|
|
- **Rationale**: `OperateHubShell` already resolves the current admin-plane tenant context in a way that respects route tenant, Filament tenant, and remembered tenant fallbacks. That makes it useful for describing the operator's current context, but using it as an authorization or route-validity gate would reintroduce the same hidden coupling Spec 144 is removing.
|
|
- **Alternatives considered**:
|
|
- Ignore active tenant context completely on the viewer: rejected because the spec explicitly requires non-blocking transparency when current header context differs from the run tenant.
|
|
- Force the viewer to switch the remembered tenant to the run's tenant: rejected because it would turn a read action into an implicit context mutation and violate the spec's convenience-only rule for remembered context.
|
|
|
|
## R-003: Context mismatch UX belongs in the viewer wrapper, not in policy or infolist definitions
|
|
|
|
- **Decision**: Add canonical-context messaging in `TenantlessOperationRunViewer` and render it in `tenantless-operation-run-viewer.blade.php` above the reused infolist.
|
|
- **Rationale**: The current viewer wrapper already renders the redaction-integrity note before the infolist and owns polling and page-level concerns. Adding a second informational banner there is low-risk and preserves reuse of `OperationRunResource::infolist()` without injecting presentation logic into policy code or shared resource schema builders.
|
|
- **Alternatives considered**:
|
|
- Inject banner rows directly into `OperationRunResource::infolist()`: rejected because the infolist is shared and the banner is specific to the canonical workspace viewer semantics.
|
|
- Encode mismatch state in policy responses: rejected because authorization responses should stay limited to allow, 404, and 403 semantics.
|
|
|
|
## R-004: Preserve the existing canonical deep-link helper contract
|
|
|
|
- **Decision**: Keep `OperationRunLinks::tenantlessView()` and the `admin.operations.view` route as the only canonical run-view target for this feature.
|
|
- **Rationale**: Existing tests and notification surfaces already rely on this helper, and `OperationRunLinks::view()` already normalizes tenant-aware callers onto the tenantless canonical route. The problem is not URL shape; it is trust in the viewer after the URL is opened.
|
|
- **Alternatives considered**:
|
|
- Introduce a new source-aware deep-link helper: rejected because it would fragment the canonical route contract.
|
|
- Reintroduce tenant-bound operation detail URLs: rejected because Spec 078 already consolidated operations onto the canonical tenantless route family.
|
|
|
|
## R-005: Extend focused existing tests and add a small spec-specific pack
|
|
|
|
- **Decision**: Extend the strongest existing viewer, shell, authorization, and canonical-link tests, and add a small `tests/Feature/144/` pack for mismatch and deep-link trust scenarios.
|
|
- **Rationale**: The repo already has substantial coverage around `TenantlessOperationRunViewer`, `OperateHubShell`, operations canonical URLs, and tenant isolation. Reusing those anchors reduces new-test duplication while still giving Spec 144 a clear regression pack that maps directly to the acceptance criteria.
|
|
- **Alternatives considered**:
|
|
- Put all coverage in one large existing test file: rejected because the matrix of mismatch, lifecycle, and deep-link cases becomes harder to scan and maintain.
|
|
- Add only spec-specific tests with no existing-test updates: rejected because that would miss the places where current semantics are already encoded and likely to regress. |