ahmido
2bf53f6337
Some checks failed
Main Confidence / confidence (push) Failing after 44s
## Summary - enforce shared operation run link generation across admin and system surfaces - add guard coverage to block new raw operation route bypasses outside explicit exceptions - harden Filament theme asset resolution so stale or wrong-stack hot files fall back to built assets ## Testing - 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 tests/Unit/Filament/PanelThemeAssetTest.php Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #268
199 lines
6.7 KiB
Markdown
199 lines
6.7 KiB
Markdown
# Data Model: Operation Run Link Contract Enforcement
|
|
|
|
## Overview
|
|
|
|
This feature introduces no new persisted business entity. Existing `OperationRun` records, workspace and tenant authorization truth, and canonical operations destination pages remain authoritative. The new work is a derived link-generation and guard contract over those existing records and helper families.
|
|
|
|
## Existing Persistent Entities
|
|
|
|
### OperationRun
|
|
|
|
**Purpose**: Canonical runtime and monitoring truth for operation collection and detail destinations.
|
|
|
|
**Key fields used by this feature**:
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `tenant_id`
|
|
- `type`
|
|
- `status`
|
|
- `outcome`
|
|
- `context`
|
|
|
|
**Rules relevant to this feature**:
|
|
|
|
- Admin-plane and system-plane detail links resolve to existing canonical monitoring surfaces; the feature does not add a new route family.
|
|
- Tenant-bound runs remain subject to destination-side entitlement checks even when the source link carries canonical tenant continuity.
|
|
- The feature changes how source surfaces build URLs, not how `OperationRun` lifecycle truth is persisted.
|
|
|
|
### Tenant
|
|
|
|
**Purpose**: Existing tenant scope and entitlement anchor for admin-plane collection continuity and tenant-bound run inspection.
|
|
|
|
**Key fields used by this feature**:
|
|
|
|
- `id`
|
|
- `external_id`
|
|
- `workspace_id`
|
|
- `name`
|
|
|
|
**Rules relevant to this feature**:
|
|
|
|
- Admin-plane collection links may preserve entitled tenant context only through helper-supported parameters.
|
|
- Detail links never create a tenant-prefixed duplicate route; tenant relevance is enforced at the destination against the run itself.
|
|
|
|
### Workspace
|
|
|
|
**Purpose**: Existing workspace isolation boundary for canonical admin monitoring routes.
|
|
|
|
**Key fields used by this feature**:
|
|
|
|
- `id`
|
|
- membership and capability truth via existing authorization helpers
|
|
|
|
**Rules relevant to this feature**:
|
|
|
|
- Non-members remain `404` on canonical admin monitoring routes.
|
|
- The feature does not add any new workspace-scoped persistence or copied navigation records.
|
|
|
|
## Derived Models
|
|
|
|
### AdminOperationCollectionLinkInput
|
|
|
|
**Purpose**: Canonical input model for helper-owned admin collection links.
|
|
|
|
**Fields**:
|
|
|
|
- `surfaceKey`
|
|
- `tenantId` or `tenantExternalId` when the source surface owns entitled tenant continuity
|
|
- `navigationContext`
|
|
- `activeTab`
|
|
- `problemClass`
|
|
- `allTenants`
|
|
|
|
**Validation rules**:
|
|
|
|
- Tenant context is included only when the source surface already owns an entitled tenant.
|
|
- `activeTab`, `problemClass`, and `allTenants` remain limited to current helper-supported semantics.
|
|
- Collection URLs are always emitted by `OperationRunLinks::index(...)`.
|
|
|
|
### AdminOperationDetailLinkInput
|
|
|
|
**Purpose**: Canonical input model for helper-owned admin detail links.
|
|
|
|
**Fields**:
|
|
|
|
- `surfaceKey`
|
|
- `runId`
|
|
- `navigationContext`
|
|
|
|
**Validation rules**:
|
|
|
|
- Detail links are emitted only through `OperationRunLinks::view(...)` or `OperationRunLinks::tenantlessView(...)`.
|
|
- No source surface may mint a tenant-prefixed or surface-local duplicate detail route.
|
|
|
|
### SystemOperationCollectionLinkInput
|
|
|
|
**Purpose**: Canonical input model for helper-owned system collection links.
|
|
|
|
**Fields**:
|
|
|
|
- `surfaceKey`
|
|
|
|
**Validation rules**:
|
|
|
|
- Collection links are emitted only through `SystemOperationRunLinks::index()`.
|
|
- System-plane collection links never fall back to admin-plane monitoring.
|
|
|
|
### SystemOperationDetailLinkInput
|
|
|
|
**Purpose**: Canonical input model for helper-owned system detail links.
|
|
|
|
**Fields**:
|
|
|
|
- `surfaceKey`
|
|
- `runId`
|
|
|
|
**Validation rules**:
|
|
|
|
- Detail links are emitted only through `SystemOperationRunLinks::view(...)`.
|
|
- System-plane detail links never fall back to admin-plane monitoring.
|
|
|
|
### CoveredLinkProducer
|
|
|
|
**Purpose**: Planning and guard model for every app-side source that emits an `OperationRun` collection or detail link.
|
|
|
|
**Fields**:
|
|
|
|
- `surfaceKey`
|
|
- `filePath`
|
|
- `plane` (`admin`, `system`)
|
|
- `linkKind` (`collection`, `detail`, `both`)
|
|
- `contractState` (`migrated`, `verified_helper_backed`, `allowlisted_exception`)
|
|
- `justification`
|
|
|
|
**State transitions**:
|
|
|
|
- `raw_bypass` -> `migrated`
|
|
- `raw_bypass` -> `allowlisted_exception`
|
|
- `existing_helper_path` -> `verified_helper_backed`
|
|
- `thin_delegate` -> `verified_helper_backed`
|
|
|
|
**Rules**:
|
|
|
|
- Every first-slice producer must end in either `migrated`, `verified_helper_backed`, or `allowlisted_exception`.
|
|
- `allowlisted_exception` is valid only for infrastructure or redirect code that should not absorb UI-context dependencies.
|
|
- `verified_helper_backed` is valid for already-converged system producers and thin delegates that forward directly to the canonical helper family.
|
|
|
|
### OperationRunLinkGuardReport
|
|
|
|
**Purpose**: Derived failure output for the bounded regression guard.
|
|
|
|
**Fields**:
|
|
|
|
- `scannedPaths[]`
|
|
- `allowlistedPaths[]`
|
|
- `acceptedDelegates[]`
|
|
- `violations[]`
|
|
|
|
### GuardViolation
|
|
|
|
**Purpose**: Actionable output for a newly detected raw bypass.
|
|
|
|
**Fields**:
|
|
|
|
- `filePath`
|
|
- `line`
|
|
- `snippet`
|
|
- `expectedHelper` (optional)
|
|
- `reason`
|
|
|
|
**Rules**:
|
|
|
|
- When present, `expectedHelper` points to a concrete replacement path such as `OperationRunLinks::index(...)`, `OperationRunLinks::view(...)`, or `SystemOperationRunLinks::view(...)`.
|
|
- Violations are limited to the declared guard boundary and must not report tests or helper implementations themselves.
|
|
|
|
## Consumer Matrix
|
|
|
|
| Producer | Plane | Link kinds | Target state |
|
|
|----------|-------|------------|--------------|
|
|
| `RecentOperationsSummary` | admin | collection | migrated |
|
|
| `InventoryCoverage` | admin | collection + detail | migrated |
|
|
| `InventoryItemResource` | admin | detail | migrated |
|
|
| `ReviewPackResource` | admin | detail | migrated |
|
|
| `TenantlessOperationRunViewer` | admin | collection fallbacks | migrated |
|
|
| `RelatedNavigationResolver` | admin | detail | migrated |
|
|
| `AdminPanelProvider` | admin | collection nav shortcut | allowlisted exception |
|
|
| `TenantPanelProvider` | admin | collection nav shortcut | allowlisted exception |
|
|
| `EnsureFilamentTenantSelected` | admin | collection redirect shortcut | allowlisted exception |
|
|
| `ClearTenantContextController` | admin | collection redirect fallback | allowlisted exception |
|
|
| `ViewTenant` | system | collection + detail | verified helper-backed |
|
|
| `ViewWorkspace` | system | collection + detail | verified helper-backed |
|
|
| `Runs` | system | collection + detail | verified helper-backed |
|
|
| `ViewRun` | system | collection + detail | verified helper-backed |
|
|
|
|
## Persistence Boundaries
|
|
|
|
- No new table, enum-backed state, cache record, or presentation-only persistence is introduced.
|
|
- The producer inventory and allowlist are repository-level planning and guard artifacts, not product-domain records.
|
|
- Canonical navigation context remains derived request state owned by existing helper and navigation abstractions. |