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.