jinojose/aipackage
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add enterprise appliance experience Phase 1 foundation

Browse Source
This commit is contained in:
Jino Jose committed 2026-07-12 12:13:23 +05:30
1 parent b3eec34158
commit ebaa2e7219
69 files changed
+6832 -18
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

specs/001-enterprise-experience/data-model.md
+114
View File
@@ -0,0 +1,114 @@
# 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.