Pulse/docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md

# Pulse v6 Platform Support Model

Last updated: 2026-03-31
Status: ACTIVE

This file is the canonical governed model for platform support in Pulse v6.
It exists so new platforms are admitted against one shared contract instead of
through platform-by-platform improvisation.

## Canonical Rules

1. A first-class platform is a governed Pulse platform id with one declared
   primary ingestion mode, one owned onboarding path, explicit canonical
   resource projections, and one declared support matrix across the product
   surfaces below.
2. Platform families are grouping aids, not the support unit.
   `Proxmox` is a family; `proxmox-pve`, `proxmox-pbs`, and `proxmox-pmg` are
   separate first-class platforms because they onboard differently, project
   different canonical resources, and carry different support floors.
3. Runtime variants are not top-level platforms.
   `podman` is a runtime variant inside the first-class `docker` platform.
   `qemu`, `lxc`, OCI guest/runtime details, and TrueNAS app-runtime internals
   are workload technologies inside an owning platform, not new platforms.
4. Transport-specific implementations are not platforms.
   API clients, JSON-RPC sessions, pollers, agent heartbeat schemas, install
   flags, CRUD routes, and saved-connection tests are implementation details.
5. Optional augmentation paths are not platforms.
   A unified agent installed on an API-backed host may enrich or enable
   control for that platform, but it does not replace the platform's primary
   support contract.
6. `hybrid` is an ingestion mode, not a platform category.
   Use `hybrid` only when one first-class platform or resource contract
   intentionally merges API-backed and agent-backed truth.
7. Platform work must project into canonical shared resources first.
   Do not add provider-local top-level resource types by default.

## Platform Categories

### First-Class Platform

A first-class platform must define:

1. canonical platform id
2. platform family, if any
3. primary ingestion mode: `api-backed`, `agent-backed`, or `hybrid`
4. owned onboarding path
5. canonical unified-resource projections
6. support-floor row across the product surfaces below
7. assistant read classification and assistant control classification
8. optional augmentation rules, if a secondary path is allowed

### Runtime Variant

A runtime variant changes how a platform runs but does not change the owning
platform id, onboarding path, or top-level support contract.

Examples:

1. `podman` inside `docker`
2. `qemu` versus `lxc` inside `proxmox-pve`
3. container-runtime details inside TrueNAS-managed `app-container` resources

### Transport-Specific Implementation

A transport-specific implementation is the concrete mechanism used to ingest,
test, or execute a platform path.

Examples:

1. `pkg/pbs`, `pkg/pmg`, and TrueNAS JSON-RPC clients
2. Docker and Kubernetes agent report schemas
3. `--enable-docker`, `--enable-kubernetes`, and `--proxmox-type pve|pbs`
4. platform-connections CRUD and saved-connection test routes

### Optional Augmentation Path

An optional augmentation path is a secondary governed path that enriches an
existing first-class platform without replacing its primary ingestion mode.

Examples:

1. a unified agent on a Proxmox node enabling hybrid host telemetry or guest
   control for `proxmox-pve`
2. a unified agent on a TrueNAS appliance enriching a `truenas` system that is
   already supported through the API-backed poller

## Canonical Ingestion Modes

### API-backed

Pulse polls or queries the platform API directly. Optional agent data may
augment the platform later, but API truth defines the support floor.

Current API-backed primary platforms:

1. `proxmox-pve`
2. `proxmox-pbs`
3. `proxmox-pmg`
4. `truenas`

### Agent-backed

Pulse relies on a Pulse-managed agent as the primary source of truth.
Specialized runtime modules may ride on the same host install, but the agent
path defines the support floor.

Current agent-backed primary platforms:

1. `agent` for unified-agent hosts
2. `docker`
3. `kubernetes`

### Hybrid

Hybrid means one admitted platform deliberately merges API-backed and
agent-backed truth into one canonical resource contract. Hybrid is valid only
when the primary owner and the augmentation rule are both explicit.

Current governed hybrid-capable platforms:

1. `proxmox-pve`
2. `proxmox-pbs`
3. `truenas`

`docker` and `kubernetes` do not become hybrid platforms merely because they
run on a machine that also reports as `agent`; those are parallel first-class
platforms sharing one physical host.

## Canonical Resource Projection Rules

1. Host-like systems should project as canonical `agent` resources plus
   `platformType`, not as provider-local host types.
2. Current top-level exceptions are `pbs` and `pmg`, which remain dedicated
   canonical resource types because their product semantics are not reducible
   to a generic host row.
3. Proxmox guest workloads project as `vm` and `system-container`.
4. OCI and application workloads project as `app-container`, including
   TrueNAS-managed apps.
5. Docker Swarm service topology projects as `docker-service`.
6. Kubernetes projects as `k8s-cluster`, `k8s-node`, `pod`, and
   `k8s-deployment`.
7. Storage projects through shared `storage`, `ceph`, and `physical-disk`
   resources instead of provider-local storage types.
8. Recovery artifacts stay in `internal/recovery` and reference canonical
   platform ids plus canonical resource ids. Recovery provider strings are
   forward-compatible vocabulary, not support declarations by themselves.

## Support Floor

Every first-class platform must declare one matrix row covering these product
surfaces:

1. onboarding/setup
2. infrastructure visibility
3. workloads, if the platform projects workload resources
4. storage, if the platform projects storage or disk resources
5. recovery, if the platform emits protected-item or recovery-artifact truth
6. alerts, if the platform contributes operator-significant health state
7. assistant read
8. assistant control

A platform counts as supported only when every applicable surface above is
either `supported` or explicitly `n/a`. Blank, implied, or hand-wavy coverage
is not acceptable.

`assistant control` must be classified explicitly as one of:

1. `supported`
2. `augmentation-only`
3. `read-only`
4. `n/a`

## Pre-Support Readiness Stages

An admitted first-class platform may be real engineering work long before it
is honest to call it supported. Pulse therefore uses one governed pre-support
checkpoint so delivery progress is visible without inflating the support claim.

1. `architecture-locked`
   The admission model is resolved and implementation may start, but the
   platform is still only a planned or admitted direction.
2. `first-lab-ready`
   The architecture is locked, the bounded shared phase floor is implemented,
   automated non-live proof covers that floor well enough to catch regression,
   and the next highest-value step is a real lab or customer environment run.
   `first-lab-ready` is an implementation checkpoint, not a support claim.
3. `supported`
   Live proof validates the declared floor and the platform is admitted into
   the current support matrix.

Rules:

1. Only `supported` changes the current support matrix.
2. `first-lab-ready` may be used in execution plans, proof matrices,
   blocked-proof records, and progress reporting for admitted platforms.
3. `first-lab-ready` must not leak into product wording, settings wording, or
   Assistant behavior as if support already exists.

## Current Classification

### First-class platforms

1. `agent` for unified-agent hosts
2. `docker`
3. `kubernetes`
4. `proxmox-pve`
5. `proxmox-pbs`
6. `proxmox-pmg`
7. `truenas`

### Admitted platforms (not yet supported)

1. `vmware-vsphere`

### Presentation-only platform vocabulary

1. `unraid`
2. `synology-dsm`
3. `microsoft-hyperv`
4. `aws`
5. `azure`
6. `gcp`

### Machine-readable projection

`PLATFORM_SUPPORT_MANIFEST.json` is the machine-readable projection of the
supported, admitted, and presentation-only platform vocabulary declared here.
Tests and shared frontend vocabulary may consume that manifest, and the tracked
frontend projection in
`frontend-modern/src/utils/platformSupportManifest.generated.ts` must be
generated from it, but neither projection may introduce platform ids or
governance states that are not declared in this document.

### Runtime variants

1. `podman` is a runtime variant inside `docker`, surfaced through runtime
   metadata such as `containerRuntime`, not as a top-level platform.
2. `qemu`, `lxc`, and OCI guest/runtime details are workload technologies
   inside `proxmox-pve`, not first-class platforms.
3. TrueNAS app runtime internals are implementation details of
   `truenas`-owned `app-container` resources, not `docker` adoption.

### Transport-specific implementations

1. Proxmox, PBS, PMG, and TrueNAS connection CRUD and test routes
2. PBS/PMG API clients and the TrueNAS JSON-RPC poller stack
3. Docker and Kubernetes agent report contracts
4. install-command helpers and setup-script flags
5. platform badge and filter helpers

### Optional augmentation paths

1. unified agent on a Proxmox node
2. unified agent on a TrueNAS appliance
3. host-level agent support that enables shell or guest control for an already
   admitted API-backed platform

## Current Support Matrix

| Platform      | Family             | Primary mode | Optional augmentation              | Canonical projections                                                 |
| ------------- | ------------------ | ------------ | ---------------------------------- | --------------------------------------------------------------------- |
| `agent`       | Pulse-managed host | agent-backed | none                               | `agent`, `storage`, `physical-disk`                                   |
| `docker`      | container runtime  | agent-backed | none                               | `agent`, `app-container`, `docker-service`                            |
| `kubernetes`  | cluster runtime    | agent-backed | none                               | `k8s-cluster`, `k8s-node`, `pod`, `k8s-deployment`                    |
| `proxmox-pve` | Proxmox            | api-backed   | host agent may augment into hybrid | `agent`, `vm`, `system-container`, `storage`, `ceph`, `physical-disk` |
| `proxmox-pbs` | Proxmox            | api-backed   | host agent may augment into hybrid | `pbs`, `storage`                                                      |
| `proxmox-pmg` | Proxmox            | api-backed   | none today                         | `pmg`                                                                 |
| `truenas`     | TrueNAS            | api-backed   | host agent may augment into hybrid | `agent`, `app-container`, `storage`, `physical-disk`                  |

| Platform      | Setup                                  | Visibility | Workloads | Storage   | Recovery  | Alerts    | Assistant read | Assistant control |
| ------------- | -------------------------------------- | ---------- | --------- | --------- | --------- | --------- | -------------- | ----------------- |
| `agent`       | install workspace                      | supported  | `n/a`     | supported | `n/a`     | supported | supported      | supported         |
| `docker`      | install workspace / runtime enablement | supported  | supported | `n/a`     | `n/a`     | supported | supported      | supported         |
| `kubernetes`  | install workspace / runtime enablement | supported  | supported | `n/a`     | supported | supported | supported      | supported         |
| `proxmox-pve` | platform connections                   | supported  | supported | supported | supported | supported | supported      | augmentation-only |
| `proxmox-pbs` | platform connections                   | supported  | `n/a`     | supported | supported | supported | supported      | read-only         |
| `proxmox-pmg` | platform connections                   | supported  | `n/a`     | `n/a`     | `n/a`     | supported | supported      | read-only         |
| `truenas`     | platform connections                   | supported  | supported | supported | supported | supported | supported      | supported         |

## Current Inconsistencies To Treat Explicitly

1. `PLATFORM_SUPPORT_MANIFEST.json` intentionally carries admitted and
   presentation-only ids such as `vmware-vsphere`, `microsoft-hyperv`, `aws`,
   `azure`, `gcp`, `unraid`, and `synology-dsm` so shared tests and frontend
   vocabulary can normalize them consistently. Those ids must not be
   interpreted as current support unless the classifications above say so.
2. Recovery provider strings are intentionally forward-compatible and already
   include values such as `docker`, `agent`, and `proxmox-pmg`. Those strings
   do not mean recovery support exists until the platform matrix above marks
   recovery as supported.
3. Frontend compatibility types still expose some legacy or presentation-local
   resource aliases. The canonical backend truth remains the shared
   unified-resource model plus this platform matrix.

## Future Platform Admission

A new platform may be admitted as first-class only after governance answers
all of these questions before implementation starts:

1. What is the canonical platform id, and what platform family does it belong
   to, if any?
2. Is the primary ingestion mode `api-backed`, `agent-backed`, or `hybrid`?
   If hybrid, what is primary and what is only augmentation?
3. What is the canonical onboarding path: platform connections, install
   workspace, or both?
4. What existing canonical resource types does it project into?
   New resource types require explicit justification; provider-local host types
   are forbidden by default.
5. Which support-floor surfaces are `supported`, `augmentation-only`,
   `read-only`, or `n/a`?
6. What stable identities drive dedupe, monitored-system counting, and
   cross-source merge with `agent`, `docker`, `kubernetes`, or other existing
   platforms?
7. What transport/security boundary owns credentials, polling cadence,
   reconnect semantics, and disabled/default behavior?
8. What proof demonstrates the declared floor is real in onboarding,
   visibility, applicable domain surfaces, alerts, and assistant behavior?

If those answers are not yet stable, the work must stop at a governed
open-decision or resolved-decision update instead of starting runtime code.

## VMware vSphere Admission Model

Pulse now has a resolved architecture recommendation for any future VMware
vSphere work. This does not admit `vmware-vsphere` into the current support
matrix yet. It defines the only acceptable phase-1 model if implementation
starts.

1. treat VMware as one separate first-class platform id,
   `vmware-vsphere`, not as another Proxmox subtype and not as a generic
   future-label shortcut
2. use `vCenter` as the only supported phase-1 entry point
3. treat direct `ESXi` onboarding as deferred work, not as an implied part of
   the vCenter claim
4. keep the primary ingestion mode `api-backed`
5. use official VMware APIs first: vCenter Automation API for modern inventory
   and VM control surfaces, plus the Virtual Infrastructure JSON API for
   alarm, event, snapshot, and performance/detail paths
6. treat a Pulse-managed agent only as future augmentation for deeper host or
   guest behavior, not as a bootstrap requirement or primary support contract
7. project ESXi hosts as canonical `agent`, guest workloads as canonical `vm`,
   and datastores as canonical `storage`
8. keep vCenter, datacenter, cluster, folder, and resource-pool objects as
   topology or relationship metadata under those shared resources rather than
   inventing top-level `esxi-host`, `vsphere-cluster`, or `vsphere-vm` types
9. keep `physical-disk`, `system-container`, `app-container`, and recovery
   artifacts out of the phase-1 projection contract unless a later governed
   slice proves they belong on the shared path

| Platform         | Family | Entry point               | Primary mode | Optional augmentation                  | Canonical projections    | Admission state                                | Readiness stage   |
| ---------------- | ------ | ------------------------- | ------------ | -------------------------------------- | ------------------------ | ---------------------------------------------- | ----------------- |
| `vmware-vsphere` | VMware | `vCenter` only in phase 1 | `api-backed` | host or guest agent later, not phase 1 | `agent`, `vm`, `storage` | architecture locked, not yet in support matrix | `first-lab-ready` |

## VMware vSphere Proposed Phase-1 Floor

This is the proposed phase-1 support floor once implementation and proof land.
It is not a claim that VMware is currently supported in Pulse.

| Platform         | Setup                                  | Visibility | Workloads | Storage   | Recovery | Alerts    | Assistant read | Assistant control |
| ---------------- | -------------------------------------- | ---------- | --------- | --------- | -------- | --------- | -------------- | ----------------- |
| `vmware-vsphere` | platform connections to `vCenter` only | supported  | supported | supported | `n/a`    | supported | supported      | read-only         |

Phase-1 floor details:

1. visibility means inventory and topology read across vCenter-backed ESXi
   hosts, VM placement, and datastore relationships
2. workloads means VM inventory, power/runtime state, guest identity when the
   API exposes it, snapshot-tree visibility, and metrics/alarm context
3. storage means datastore inventory, capacity/free-space/accessibility, host
   attachments, and VM-to-datastore usage
4. recovery stays `n/a` in the platform matrix because vSphere snapshots and
   changed-disk APIs are recovery-adjacent read signals, not a governed Pulse
   recovery-artifact or restore surface by themselves
5. alerts means vSphere alarm state, overall health state, and related
   event/task history projected through shared alert and incident paths
6. assistant control stays read-only even though VMware exposes real control
   APIs, because Pulse has not yet expanded the governed action surface into a
   general VMware admin plane

Phase-1 exclusions:

1. direct `ESXi` onboarding
2. `physical-disk` projection, including vSAN-only physical disk health APIs
3. `system-container` or `app-container` projections
4. treating vSphere snapshots as shared Pulse recovery support
5. assistant or operator control claims for VM power, snapshot lifecycle, or
   guest operations
6. any provider-local resource type, page shell, or AI tool family

Support gate:

Pulse should not call VMware supported until a real vCenter proves the declared
floor end to end: connection onboarding, minimum privilege bundle, supported
version floor, canonical `agent`/`vm`/`storage` projections, alert and metrics
history truth, and assistant read behavior. If that proof does not hold,
implementation must stop at governance rather than widening the support claim.
The concrete first-implementation slice order and stop/go checks live in
`docs/release-control/v6/internal/VMWARE_VSPHERE_PHASE1_EXECUTION_PLAN.md`.
As of 2026-03-31, VMware has reached the governed `first-lab-ready`
checkpoint: the non-live phase-1 floor is implemented and regression-proofed
well enough that the next proper step is a real `vCenter` proof run rather
than more architecture work.