TenantAtlas/specs/219-finding-ownership-semantics/data-model.md

Data Model: Finding Ownership Semantics Clarification

Date: 2026-04-20
Branch: 219-finding-ownership-semantics

Overview

This feature introduces no new persisted entities. It clarifies responsibility semantics over existing finding and finding-exception records and adds one derived responsibility-state projection for operator-facing surfaces.

Entity: Finding

Represents: A tenant-owned operational governance finding that moves through the findings workflow and may carry both accountable ownership and active remediation assignment.

Key Fields

Field	Type	Required	Notes
id	bigint	yes	Primary key
workspace_id	bigint	yes	Derived tenant ownership boundary
tenant_id	bigint	yes	Tenant isolation boundary
status	string	yes	Existing findings lifecycle state
severity	string	yes	Existing severity dimension
owner_user_id	bigint nullable	no	Accountable person for the finding outcome
assignee_user_id	bigint nullable	no	Active remediation executor / coordinator
due_at	datetime nullable	no	Existing SLA/follow-up deadline
resolved_reason	string nullable	no	Existing closure context
closed_reason	string nullable	no	Existing closure/governance context

Relationships

Relationship	Target	Cardinality	Purpose
tenant()	Tenant	belongsTo	Tenant ownership and authorization
ownerUser()	User	belongsTo	Accountable owner
assigneeUser()	User	belongsTo	Active remediation assignee
findingException()	FindingException	hasOne	Optional exception artifact for accepted-risk governance

Validation Rules

• owner_user_id MAY be null.
• assignee_user_id MAY be null.
• If present, either user ID MUST reference a current member of the active tenant.
• Responsibility changes are allowed only on open findings, matching the current FindingWorkflowService::assign() rule.

Entity: FindingException

Represents: A tenant-owned exception artifact attached to a finding when governance coverage is requested or granted.

Key Fields

Field	Type	Required	Notes
id	bigint	yes	Primary key
finding_id	bigint	yes	Owning finding
tenant_id	bigint	yes	Tenant isolation boundary
owner_user_id	bigint nullable	no	Accountable owner of the exception artifact, not of the finding itself
status	string	yes	Existing exception lifecycle state
current_validity_state	string nullable	no	Existing governance-validity dimension
request_reason	text	yes	Existing request context

Relationships

Relationship	Target	Cardinality	Purpose
finding()	Finding	belongsTo	Parent finding context
owner()	User	belongsTo	Exception artifact owner

Validation Rules

• Exception-owner selection continues to use current tenant-member validation.
• Exception ownership MUST remain semantically distinct from finding ownership on all mixed-context surfaces.

Derived Projection: ResponsibilityState

Represents: An operator-facing derived state computed from owner_user_id and assignee_user_id without new persistence.

Naming convention:

• Operator-facing UI label: orphaned accountability
• Internal derived-state and contract slug: orphaned_accountability

Derived Values

Derived State	Rule	Operator Meaning
orphaned_accountability	owner_user_id == null	No accountable owner is set. This remains true even if an assignee exists.
owned_unassigned	owner_user_id != null && assignee_user_id == null	Someone owns the outcome, but active remediation work is not assigned.
assigned	owner_user_id != null && assignee_user_id != null	Accountability and active remediation assignment are both set.

Rendering Notes

• If owner and assignee are the same user, the state remains assigned; the UI should show both roles satisfied without implying a data problem.
• If both are null, the finding still uses the slug orphaned_accountability and the visible label orphaned accountability.
• If assignee is present but owner is null, the finding remains orphaned_accountability; the UI may also show that remediation is assigned without accountable ownership.

Mutation Contract: ResponsibilityUpdate

Represents: The input/output contract of the existing assignment action.

Input Shape

Field	Type	Required	Notes
owner_user_id	bigint nullable	no	Set, change, or clear finding owner
assignee_user_id	bigint nullable	no	Set, change, or clear finding assignee

Behavioral Rules

• The existing FindingWorkflowService::assign() method remains the mutation boundary.
• The service MUST continue to write both fields explicitly to the finding.
• Operator feedback and audit-facing wording should classify the result as owner_only, assignee_only, clear_owner, clear_assignee, or owner_and_assignee when both fields change in one update.

State and Lifecycle Impact

This feature does not add a new lifecycle family. It overlays responsibility semantics on top of existing findings lifecycle states.

Existing Lifecycle State	Responsibility Impact
new, triaged, in_progress, reopened, acknowledged	Responsibility state is actionable and visible by default
resolved, closed	Responsibility remains historical context only
risk_accepted	Responsibility remains visible, but exception-owner context may also appear and must remain separate