# 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.