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

# Pulse v6 Platform Support Model

Last updated: 2026-03-30
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`

## 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`

### 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. `frontend-modern/src/utils/sourcePlatforms.ts` already carries future labels
   such as `vmware-vsphere`, `microsoft-hyperv`, `aws`, `azure`, `gcp`,
   `unraid`, and `synology-dsm`. Those are presentation vocabulary only. They
   are not admitted first-class platforms until governance says so here.
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 |
| --- | --- | --- | --- | --- | --- | --- |
| `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 admitted |

## 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`.