TenantAtlas/specs/232-operation-run-link-contract/quickstart.md

# Quickstart: Operation Run Link Contract Enforcement

## Prerequisites

1. Start the local platform stack.

   ```bash
   export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
   cd apps/platform && ./vendor/bin/sail up -d
   ```

2. Work with:
   - one workspace operator who can access canonical admin monitoring,
   - one entitled tenant with recent `OperationRun` records,
   - one second tenant that the operator must not be able to inspect, and
   - one platform user who can access `/system/ops/runs`.

3. Remember that this feature changes link generation only. No frontend asset build should be required unless unrelated platform assets changed.

## Automated Validation

Run formatting and the narrowest proving suites for this feature:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Filament/InventoryCoverageRunContinuityTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php tests/Feature/078/RelatedLinksOnDetailTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php
```

## Final Guard Boundary

The implemented guard is bounded to the first-slice source surfaces and explicit infrastructure exceptions:

- **Migrated admin producers**: `RecentOperationsSummary`, `InventoryCoverage`, `InventoryItemResource`, `ReviewPackResource`, `TenantlessOperationRunViewer`, and `RelatedNavigationResolver`.
- **Verified system producers**: `ViewTenant`, `ViewWorkspace`, `Runs`, and `ViewRun`, all continuing through `SystemOperationRunLinks`.
- **Accepted thin delegate**: `App\Support\OpsUx\OperationRunUrl`, which forwards to `OperationRunLinks`.
- **Allowlisted infrastructure exceptions**: `AdminPanelProvider`, `TenantPanelProvider`, `EnsureFilamentTenantSelected`, and `ClearTenantContextController`.
- **Forbidden bypasses inside the boundary**: raw `route('admin.operations.index')`, raw `route('admin.operations.view')`, direct `/system/ops/runs` strings, and direct `Runs::getUrl(...)` or `ViewRun::getUrl(...)` outside `SystemOperationRunLinks`.

## Manual Validation Flow

### 1. Validate tenant-aware admin collection continuity

1. Open a tenant-facing surface that exposes the recent-operations summary or an inventory coverage follow-up link.
2. Follow the `Open operations` or equivalent history link.
3. Confirm the destination stays on `/admin/operations` and preserves only helper-supported tenant or filter continuity.
4. Confirm the page does not invent a tenant-prefixed duplicate operations route.

### 2. Validate canonical admin detail links from representative resource surfaces

1. Open one inventory item with a `last_seen_operation_run_id`.
2. Follow the `Last inventory sync` link.
3. Open one review pack with an associated `operation_run_id`.
4. Confirm both links open canonical admin run detail, not a surface-local route or raw fallback URL.

### 3. Validate shared related-navigation and back-link behavior

1. Open a surface that renders an `operation_run` related link through `RelatedNavigationResolver`.
2. Confirm the helper-generated label and URL match canonical admin run detail behavior.
3. Open `TenantlessOperationRunViewer` through a source without an explicit back-link context.
4. Confirm `Back to Operations` and `Show all operations` land on the canonical admin collection helper path.

### 4. Validate system-plane continuity

1. Open a system-plane widget or directory page with run drill-through.
2. Follow collection and detail links into monitoring.
3. Confirm the destination stays on `/system/ops/runs` or `/system/ops/runs/{run}` and does not fall back to `/admin/operations`.

### 5. Validate authorization semantics stayed unchanged

1. As a workspace member who is not entitled to a foreign tenant, request a canonical admin detail URL for that tenant’s run.
2. Confirm the response remains `404`.
3. As a non-platform user, request a system-plane operations URL.
4. Confirm the response remains `404`.
5. As an entitled actor missing the relevant capability, confirm current destination behavior still yields `403` where the route already distinguishes membership from capability denial.

### 6. Validate the explicit exception boundary

1. Confirm that navigation boot, middleware, and clear-tenant redirect behavior still function after the cleanup.
2. Review the named allowlist entries and verify each remaining raw producer is infrastructure-owned rather than convenience-owned.
3. Confirm no new operator-facing page, widget, or related-navigation builder remains on raw `admin.operations.*` assembly outside the allowlist.

### 7. Validate the guardrail

1. Use a temporary local probe or test fixture to simulate one representative raw `route('admin.operations.view', ...)` bypass inside the declared guard boundary without committing it.
2. Run the guard test.
3. Confirm it fails with actionable file and snippet output.
4. Replace the bypass with the canonical helper or move it into an explicitly justified exception and confirm the guard passes again.

## Reviewer Notes

- The feature stays Livewire v4.0+ compatible and does not change provider registration in `bootstrap/providers.php`.
- No new global-search surface is introduced; `InventoryItemResource` already has a view page and `ReviewPackResource` remains non-searchable.
- No destructive action or new asset behavior is introduced.
- The contract boundary is intentionally narrow: platform-owned UI and shared navigation code only.