# Customer Experience Contract

This contract defines observable behaviour. Exact endpoint paths may remain compatible with existing
routes or be introduced additively during implementation.

## Common Response State

Every customer-facing state-bearing response provides:

- canonical `state` and `severity`;
- `observed_at` and explicit freshness when not live;
- plain-language `summary` and customer impact;
- stable non-secret `code` for support correlation;
- ordered `next_actions`, filtered by authorization;
- `correlation_id` when an operation or failure is involved.

Raw exceptions, stack traces, signed license material, credentials, tokens, document content, and
secret-bearing command output MUST NOT appear.

## Readiness Interface

The readiness interface returns the ApplianceReadiness model. It MUST distinguish:

- product/API unreachable from a degraded dependent capability;
- licensed from provisioned, hardware-supported, and currently available;
- ready from stale last-known-ready;
- customer impact from technical diagnostic detail.

Phase 1 may extend the existing readiness-report route additively. Existing fields remain until all
packaged consumers move to the versioned contract.

## Operation Interface

Supported behaviours:

1. **Create/acknowledge**: validates authorization, prerequisites, conflicts, scope, and confirmation.
2. **Read**: returns durable current state by operation ID after refresh, restart, or session change.
3. **List**: returns role-filtered recent and active operations.
4. **Act**: exposes only valid retry/resume/cancel/recovery actions for the current state.

Creation MUST be idempotent for duplicate customer submissions within the defined request window.
Conflicting operations return a customer-facing explanation and reference the blocking operation.
Every operation interface enforces server-side authorization and is tested for both permitted and
denied roles. Removal additionally exposes retained/deleted data categories and preserves backups by
default unless a separately confirmed policy explicitly requires deletion.

## Error Contract

Errors provide status, stable `code`, plain-language `message`, `affected_scope`, safe
`remediation`, and optional `correlation_id`. Validation errors identify fields without discarding
other valid setup progress. Authorization errors do not reveal protected resource existence.

## Entitlement Contract

Customer-facing output uses Workstation and Server S/M/L/Max labels. Compatibility identifiers may
appear only in authorized diagnostics. Every capability state identifies one primary reason:
licensed, not licensed, not provisioned, unsupported by hardware, degraded, or unavailable.

## Audit Contract

Every privileged, security-sensitive, licensing, configuration, and lifecycle action records actor,
time, category, redacted scope, result, and correlation ID. Secret values and signed payloads are
never recorded. Denied and failed actions are auditable where safe.

## Accessibility Contract

- All functionality is operable by keyboard with visible focus and logical order.
- Dynamic status and validation feedback is programmatically announced without stealing focus.
- Labels, instructions, errors, and confirmations are programmatically associated.
- Status and severity never rely on colour alone.
- Content supports required contrast, zoom, reflow, and reduced-motion behaviour.
- Acceptance requires automated and representative manual WCAG 2.2 AA evidence.

## Release Evidence Contract

Each phase records source revision, package/ISO identity and checksum, test environment, product
configuration, validation results, known limitations, pilot findings, resolutions, and joint approval
from product ownership and delivery/support.