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

Quickstart: Operation Run Link Contract Enforcement

Prerequisites

1. Start the local platform stack.

   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:

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.