TenantAtlas/specs/232-operation-run-link-contract/data-model.md

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.