Add enterprise appliance experience Phase 1 foundation

specs/001-enterprise-experience/contracts/customer-experience-contract.md

@@ -0,0 +1,78 @@
+# 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.