TenantAtlas/specs/194-governance-friction-hardening/data-model.md

# Data Model: Governance Friction Hardening and Operator Vocabulary

## Overview

This feature introduces no new persisted entity, table, enum-backed database field, or long-lived artifact. It reuses existing Filament pages, current mutation services, current audit loggers, and existing authorization helpers while adding a derived planning model for governance-action semantics.

## Existing Source Truths Reused Without Change

The following truths remain authoritative and are not redefined by this feature:

- existing page and resource routes
- existing model ownership and scope semantics
- existing capability checks and `UiEnforcement` behavior
- existing confirmation, audit, and `OperationRun` behavior for underlying actions
- existing domain services that own lifecycle mutation
- existing tenant, workspace, and system-plane separation

This feature changes action semantics, reason consistency, vocabulary, and regression protection only.

## New Derived Planning Models

### GovernanceActionFamilyEntry

**Type**: derived semantic inventory entry  
**Source**: explicit Spec 194 family matrix + code-level guard catalog

| Field | Type | Notes |
|------|------|-------|
| `familyKey` | string | Stable identifier such as `exception_decision`, `review_lifecycle`, or `run_triage` |
| `canonicalObject` | string | Operator-facing object noun such as `exception`, `review`, `snapshot`, `run`, `finding`, or `tenant` |
| `panels` | array<string> | `tenant`, `admin`, `system` |
| `surfaceKeys` | array<string> | Concrete surfaces that host this family |
| `defaultActionOrder` | array<string> | Canonical order of verbs inside the family |
| `supportsDocumentedDeviation` | boolean | Whether family-level deviations are allowed only when explicitly catalogued |
| `defaultMutationScopeSource` | string | Where the family gets its mutation scope wording |

### GovernanceActionRule

**Type**: derived action-semantics rule  
**Source**: governance catalog + concrete action bindings

| Field | Type | Notes |
|------|------|-------|
| `actionKey` | string | Stable identifier such as `approve_exception` or `archive_review` |
| `familyKey` | string | Links action to its family |
| `frictionClass` | string | `F0`, `F1`, `F2`, or `F3` |
| `reasonPolicy` | string | `none`, `optional`, or `required` |
| `dangerPolicy` | string | `none`, `contextual`, or `required` |
| `canonicalLabel` | string | Operator-facing default button label |
| `modalHeadingPattern` | string | Canonical confirmation or reason-capture heading |
| `successNotificationPattern` | string | Canonical post-success phrase |
| `auditVerb` | string | Stable action wording for audit trail alignment |
| `serviceOwner` | string | Existing service or class that owns the mutation |

### GovernanceActionSurfaceBinding

**Type**: derived surface binding entry  
**Source**: existing Filament actions on target pages

| Field | Type | Notes |
|------|------|-------|
| `surfaceKey` | string | Stable surface identifier |
| `pageClass` | string | Concrete Filament page or resource page class |
| `actionName` | string | Local Filament action name |
| `familyKey` | string | Family that the local action belongs to |
| `statePredicate` | string | Human-readable visibility or state rule |
| `primaryOrSecondary` | string | Whether the action is the main governance action or a supporting action on that surface |
| `capabilityKey` | string or null | Canonical capability registry entry |
| `uiFieldKey` | string or null | Input field name used for reason capture when applicable |
| `auditChannel` | string | `tenant_audit`, `workspace_audit`, `system_audit`, or `operation_context` |

### DocumentedGovernanceDeviation

**Type**: derived exception entry  
**Source**: spec-approved deviation list

| Field | Type | Notes |
|------|------|-------|
| `actionKey` | string | The action deviating from its family default |
| `surfaceKey` | string | Surface where the deviation occurs |
| `deviationType` | string | `friction_override`, `reason_override`, `vocabulary_override`, or `danger_override` |
| `rationale` | string | Why the default family rule is insufficient |
| `reviewGate` | string | What test or review guard must assert the exception |
| `allowedUntil` | string or null | Optional bounded-lifetime note for temporary deviations |

### GovernanceRegressionExpectation

**Type**: derived regression entry  
**Source**: spec guard and test strategy

| Field | Type | Notes |
|------|------|-------|
| `familyKey` | string | The family under protection |
| `requiresGuardCoverage` | boolean | Catalog and exception guard required |
| `requiresFeatureCoverage` | boolean | At least one concrete page or service test required |
| `requiresBrowserSmoke` | boolean | Browser smoke required for high-risk families |
| `requiresPositiveAuthCase` | boolean | Positive authorization coverage required |
| `requiresNegativeAuthCase` | boolean | Negative authorization coverage required |
| `mustVerifyAuditPropagation` | boolean | Required when the family uses reason capture or strong lifecycle mutation |

## Resolution Rules

### Family-first rules

1. Every in-scope governance action resolves first to one `GovernanceActionFamilyEntry`, then to one concrete `GovernanceActionRule`.
2. Surface location alone cannot redefine friction class.
3. A local action name may differ from the canonical rule only if a documented deviation exists.

### Friction rules

1. `F0` actions cannot require confirmation, mandatory reason capture, or danger styling.
2. `F1` actions require confirmation but default to no mandatory reason.
3. `F2` actions require confirmation plus explicit explanation.
4. `F3` actions require confirmation, mandatory reason capture, and strong danger separation.

### Reason rules

1. Required reason capture must bind to a concrete UI field and a concrete audit or lifecycle propagation path.
2. Optional reason capture cannot silently become required on one surface without a documented deviation.
3. Existing structured lifecycle metadata may satisfy propagation only if the operator-entered rationale is preserved.
4. In the current release, `refresh_evidence`, `retry_run`, and `restore_tenant` resolve to `reasonPolicy=none`; optional F1 rationale capture is not introduced unless a documented deviation is added.

### Vocabulary rules

1. Canonical labels, modal headings, notifications, and audit verbs derive from the same family rule.
2. Navigation and export actions cannot borrow governance verbs from formal decision families.
3. Euphemistic or implementation-first synonyms are rejected unless explicitly documented.
4. Until a direct risk-acceptance surface exists, any indirect risk-acceptance wording must resolve through the exception family canon rather than creating a local synonym family.

### Deviation rules

1. Deviations are allowed only when the family default is insufficient for a specific surface or workflow state.
2. Every deviation must cite a rationale and a regression check.
3. No silent deviations are allowed.

## Relationships

- One `GovernanceActionFamilyEntry` contains one or more `GovernanceActionRule` entries.
- One `GovernanceActionRule` may bind to multiple `GovernanceActionSurfaceBinding` entries.
- One `GovernanceActionRule` may have zero or more `DocumentedGovernanceDeviation` entries.
- Every family must map to at least one `GovernanceRegressionExpectation` entry.

## Safety Rules

- No derived model may widen tenant, workspace, or system access beyond existing route and helper semantics.
- No action may lose current authorization, confirmation, audit, or `OperationRun` behavior when aligned to the catalog.
- No `F3` action may remain visually or semantically indistinguishable from nearby `F0` or `F1` actions.
- No family may introduce a new synonym set without explicit catalog ownership.
- No reason requirement may be added in UI without a corresponding propagation path in the owning service or audit log.