# Data Model: Enterprise Appliance Experience Hardening

## ApplianceReadiness

Customer-facing aggregate of appliance state.

| Field | Rules |
|---|---|
| `schema_version` | Required contract version |
| `state` | One of loading, empty, ready, degraded, failed, restricted, unavailable, stale |
| `severity` | info, warning, critical |
| `observed_at` | UTC timestamp for underlying observation |
| `freshness_seconds` | Non-negative age at response time |
| `summary` | Plain-language customer impact |
| `affected_capabilities` | Customer-facing capability identifiers, not raw service names |
| `next_actions` | Ordered safe actions with required role and action kind |
| `checks` | Component/capability observations using the same state contract |
| `entitlement` | Reference to current EntitlementState summary |

State precedence: failed/critical impact outranks degraded; stale MUST be reported when freshness is
outside the defined check window even if the previous observation was ready.

## Operation

Durable record for installation and consequential or long-running actions.

| Field | Rules |
|---|---|
| `id` | Stable opaque identifier |
| `correlation_id` | Stable across API, audit, logs, and support evidence |
| `kind` | setup, install, backup, restore, upgrade, restart, remove, reconcile, diagnostic_export, other |
| `actor_id` / `actor_name` | Authenticated actor or explicit system/installer identity |
| `scope` | Redacted description of affected appliance resources |
| `state` | requested, validating, queued, running, awaiting_reboot, succeeded, failed, cancelled, recovery_required |
| `progress_percent` | 0–100 only when meaningful; otherwise omitted |
| `progress_label` | Plain-language current phase |
| `requested_at`, `started_at`, `updated_at`, `finished_at` | UTC timestamps |
| `result_code` | Stable non-secret machine-readable result |
| `customer_message` | Plain-language outcome and impact |
| `recovery_actions` | Safe retry/resume/rollback/restore/restart/escalate actions |
| `metadata` | Allowlisted, versioned, non-secret details only |

Transitions are monotonic except explicit retry, which creates a new Operation linked to its parent.
Terminal states are succeeded, failed, cancelled, and recovery_required. Concurrent conflicting
operations MUST be rejected or queued with an explanation.

Removal operation metadata includes an allowlisted retained-data inventory, deleted-data categories,
backup preservation status, and rollback limitations; it never includes protected content values.

## EntitlementState

| Field | Rules |
|---|---|
| `category` | workstation or server |
| `commercial_label` | Workstation or Server S/M/L/Max |
| `compatibility_tier` | workstation or starter/basic/pro/max; not primary customer text |
| `license_state` | valid, missing, expired, invalid, mismatch, other stable states |
| `licensed_capabilities` | Capability keys from signed entitlement evaluation |
| `provisioned_capabilities` | Derived from install record and deployed roles |
| `hardware_capabilities` | Derived from feasibility evidence |
| `available_capabilities` | Current intersection adjusted for runtime health |
| `observed_at` | UTC evaluation time |

The model MUST distinguish why a capability is unavailable: commercial entitlement, provisioning,
hardware, or current runtime condition.

## AuditEvent

| Field | Rules |
|---|---|
| `id` | Monotonic appliance-local identifier |
| `occurred_at` | UTC timestamp |
| `actor_id` / `actor_name` | Actor identity when known |
| `action_category` | Stable category rather than secret-bearing free text |
| `scope` | Redacted affected resource |
| `result` | success, failure, denied, partial |
| `correlation_id` | Links to Operation and support evidence |
| `detail` | Allowlisted, redacted context |

## SupportEvidencePackage

Logical export; raw secret-bearing files are excluded by default.

| Field | Rules |
|---|---|
| `package_id` | Opaque identifier |
| `created_at` / `created_by` | UTC time and authorized actor |
| `product_identity` | Product category, commercial label, version/build identity |
| `entitlement_summary` | Status and capability summary without signed payload or key |
| `readiness_snapshot` | ApplianceReadiness contract |
| `operations` | Selected redacted Operation records |
| `audit_events` | Selected redacted AuditEvent records |
| `component_evidence` | Allowlisted health/version/status data |
| `redaction_report` | Categories excluded or transformed |
| `checksum` | Integrity checksum of the completed export |

## GuidanceItem

| Field | Rules |
|---|---|
| `id` | Stable local identifier |
| `journey` | setup, readiness, administration, recovery, support |
| `trigger_state` | Optional state or result code |
| `required_role` | Minimum role permitted to execute actions |
| `title`, `summary`, `steps` | Plain-language local guidance |
| `action_kind` | navigate, retry, resume, rollback, restore, restart, escalate |
| `version` | Guidance revision aligned to packaged product |

## Relationships

- ApplianceReadiness references one current EntitlementState and zero or more active Operations.
- Operation produces AuditEvents and may be included in a SupportEvidencePackage.
- SupportEvidencePackage contains snapshots, never live mutable references.
- GuidanceItems are selected by journey, state, role, and result code.