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	tenant, admin, system
surfaceKeys	array	Concrete surfaces that host this family
defaultActionOrder	array	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.