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:

Create/acknowledge: validates authorization, prerequisites, conflicts, scope, and confirmation.
Read: returns durable current state by operation ID after refresh, restart, or session change.
List: returns role-filtered recent and active operations.
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.

3.7 KiB Raw Blame History