# Storage Attachment Contract v1

Status: draft for review
Owner: Storage / Inventory / Provisioning / Platform Architecture
Last updated: 2026-05-19

## Purpose

The SKU resource model keeps storage outside compute SKU identity. That is the
right product model, but VM families still need explicit boot, root, data,
shared, and archive storage semantics.

This document defines the storage attachment contract that node families and
runtime providers must satisfy before CPU VM families become product-grade or
before any family claims migration behavior.

## Storage Roles

| Role | Meaning | Typical lifecycle |
|---|---|---|
| `boot` | Image-derived boot disk for a VM or control-plane runtime. | Recreated from image; usually ephemeral. |
| `root` | OS/root filesystem after boot. | Ephemeral or persistent depending on family policy. |
| `data` | User/application data disk attached to an allocation. | Explicitly persistent or ephemeral. |
| `shared` | Storage visible from more than one runtime target. | Required before live migration promises. |
| `archive` | Durable object/archive storage outside runtime attachment. | Managed by storage domain, not compute SKU. |

Compute SKU identity is CPU, memory, accelerator, and billing shape. Storage
size and persistence are attachment/profile choices unless a future product
explicitly creates storage-optimized compute families.

## Attachment Contract Shape

```yaml
storage_attachment:
  boot:
    required: true
    image_profile: ubuntu-noble-cloud-init-amd64
    persistence: ephemeral
  root:
    persistence: ephemeral
    default_size_mib: 20480
  data:
    supported: true
    persistence_options:
      - ephemeral
      - persistent
    default_size_mib: 0
  shared:
    supported: false
    required_for_live_migration: true
  archive:
    supported: true
    provider: managed_storage
```

Families reference this shape. Provider capacity inventory reports whether the
provider can satisfy the required storage roles.

## Family Examples

### CPU VM

A CPU VM family usually has:

1. `boot`: image-derived cloud-init disk;
2. `root`: ephemeral root disk by default;
3. `data`: optional ephemeral or persistent data disk;
4. `shared`: false until a shared storage substrate is approved;
5. `archive`: optional managed storage outside the VM runtime.

### GPU Slice

A GPU slice family usually has:

1. `boot`: image-derived guest disk;
2. `root`: ephemeral guest root disk;
3. `data`: ephemeral local NVMe or provider-local data path when explicitly
   attached to the slice;
4. `shared`: false in v1;
5. `archive`: managed storage or object storage outside the slice runtime.

Local NVMe passthrough or provider-local disks fit the `data` role with
`persistence=ephemeral` unless a reviewed persistent storage contract says
otherwise.

## Mobility Dependency

No family may claim `mobility=live` unless:

1. shared storage is supported and healthy;
2. the runtime provider supports live migration for that storage backend;
3. network identity and route draining behavior are defined;
4. operational evidence confirms storage health before migration;
5. recovery runbooks and tests cover failed migration rollback.

CPU VM with local-only storage can support `cold` recovery. GPU slices and
bare-metal GPU families remain `none` in v1 unless a separate reviewed storage
and checkpoint model proves otherwise.

## Persistence And Deallocation

Every storage attachment must declare deallocation behavior:

| Persistence | Deallocation behavior |
|---|---|
| `ephemeral` | Destroy on allocation release after cleanup/evidence capture. |
| `persistent` | Detach from runtime and retain under storage-domain ownership. |
| `archive` | Already outside runtime; lifecycle controlled by storage policy. |

Provider adapters must not leave orphaned VM disks as an acceptable steady
state. Orphan detection belongs in provider inventory and ops evidence.
The provider-neutral lifecycle and cleanup workflow is defined in
`Provider_Lifecycle_And_Orphan_Reconciliation_v1.md`; storage-specific
attachment code supplies detach/delete evidence to that workflow.

## Relationship To Existing Work

| Existing work | Relationship |
|---|---|
| `Storage_Attachment_Workflow_v1.md` | Describes node task workflow for mount attach/detach. This contract defines the family/provider semantics above that workflow. |
| `Node_Family_Model_v1.md` | Families declare storage attachment support and mobility constraints. |
| `Provider_Capacity_Inventory_v1.md` | Providers report storage pool capacity and storage-role support. |
| `Provider_Lifecycle_And_Orphan_Reconciliation_v1.md` | Defines cleanup, quarantine, and orphan reconciliation for provider-created disks and attachments. |
| Billing Platform Overhaul | Storage usage units are separate from compute SKU billing units unless a family explicitly defines bundled storage. |

## Open Decisions

1. Which storage backend is the first approved shared-storage substrate for VM
   live migration tests?
2. Should persistent data disks be first-class user products before or after
   CPU VM SKUs ship?
3. Which storage attachment events need billing usage records?
4. What is the operator-visible orphan-disk reconciliation workflow?