@wenathlan/saddle 1.8.17 → 2.0.2

package/passage.config

@@ -0,0 +1,1331 @@
+{
+  "meta": {
+    "name": "passage.config",
+    "title": "saddle - Passage Configuration (3 homonym domains kept separate + host playbook)",
+    "version": "2.0.0",
+    "date": "2026-08-22",
+    "language": "en",
+    "conceptSeparation": "'passage' has 3 distinct domains in the pool: (1) gateway - L7 Pingora reverse proxy (routes/upstreams/TLS 1.3); (2) passthrough - PCI device passthrough modes (VFIO/MDEV/MIG/vGPU/SR-IOV/vfio-user/hotplug/KVM/none); (3) network_binding - VM network bridge modes + host port binding (never localhost). A 4th section carries the AetherForge host-side VFIO playbook. Sections are NEVER merged.",
+    "sources": [
+      "pool:passage.config [S6 YAML - L7 gateway pingora, UNIQUE]",
+      "pool:passage.json [V5 - passthrough matrix, UNIQUE]",
+      "pool:nested_passage.json [network_binding never-localhost, UNIQUE]",
+      "pool:passage.yaml [AetherForge host playbook VFIO, UNIQUE]",
+      "cross-ref: gpus.json#gpu_profiles_vfio (11 GPUs vfioIds)"
+    ],
+    "mergeReport": {
+      "gatewayRoutes": 7,
+      "gatewayUpstreams": [
+        "vmprimary",
+        "mttgworkers",
+        "gpumetrics",
+        "hyperscalepool"
+      ],
+      "passthroughModesOverview": 8,
+      "passthroughSections": [
+        "vfio",
+        "mdev",
+        "mig",
+        "vgpu",
+        "sriov",
+        "vfio_user",
+        "hotplug",
+        "kvm",
+        "none_mode",
+        "decision_matrix"
+      ],
+      "networkModesRef": "6 modes (direct/bridge/nat/overlay_vxlan/zero_trust/latency_optimization) canonical in vm.config.json#production_example.vm.network.passage.modes",
+      "vfioIdsGpus": 10,
+      "rePins": "node 22.12.3->24.19.0 LTS/26.7.0, ts 5.6.3->7.0.2, docker 27.3.1->29.7.2, qemu 9.1.2->11.1.0",
+      "pinPatch": "embedded active config values re-pinned date-first 2026-08-22 (9.1.2->11.1.0, 27.3.1->29.7.2, 22.12.3->24.19.0, 5.6.3->7.0.2, 25.2.7->26.2.1, 19.1.7->22.1.8, 1.9.0->1.16.1, libvirt 10.10.0->12.5.0, checkout v4.2.2->v5); originals preserved under *_legacy*/source_value keys"
+    },
+    "inheritedSourcesPassthroughJson": [
+      "https://docs.kernel.org/driver-api/vfio.html",
+      "https://docs.kernel.org/driver-api/vfio-mediated-device.html",
+      "https://docs.nvidia.com/data-center/tesla/mig-user-guide/",
+      "https://www.cloudhypervisor.org",
+      "https://raw.githubusercontent.com/cloud-hypervisor/cloud-hypervisor/main/docs/vfio-user.md",
+      "https://github.com/cloud-hypervisor/cloud-hypervisor/releases",
+      "https://www.qemu.org/docs/master/system/device-emulation.html",
+      "https://github.com/actions/runner-images/issues/12933",
+      "https://github.com/actions/runner-images/issues/14062",
+      "https://actuated.com/blog/kvm-in-github-actions",
+      "https://github.com/e2b-dev/infra/blob/main/self-host.md"
+    ]
+  },
+  "gateway": {
+    "meta": {
+      "project": "saddle (grand merge)",
+      "version": "2.0.0",
+      "schema": "passage.config",
+      "schemaversion": "2026.08.22",
+      "engine": "passage gateway v6",
+      "runtime": {
+        "node": "24.19.0 LTS (current 26.7.0)",
+        "typescript": "7.0.2",
+        "python": "3.14.7",
+        "rust": "1.82.0",
+        "pingora": "0.4.2",
+        "docker": "29.7.2",
+        "qemu": "11.1.0",
+        "rePinNote": "legacy saddle-v6 pins (node 22.12.3, ts 5.6.3, docker 27.3.1, qemu 9.1.2) superseded date-first 2026-08-22; pingora/rust gateway pins kept"
+      },
+      "cicd": {
+        "checkout": "v5",
+        "setupnode": "v4.1.0",
+        "setuppython": "v5.4.0",
+        "setuprust": "v1.0.0",
+        "dockerbuildx": "v3.7.1"
+      },
+      "generated": "2026-08-22T00:00:00+00:00",
+      "compatibility": [
+        "vm.config",
+        "gpu.config",
+        "qemu.config",
+        "mttg.config",
+        "docker.config",
+        "boards.json",
+        "cores.json",
+        "processors.json",
+        "gpus.json",
+        "vcpus.json",
+        "vram.json",
+        "amdryzenxseries.json",
+        "nvidiablackwell.json"
+      ],
+      "mode": "root-direct",
+      "layers": 3,
+      "maxfilesize": 45,
+      "docsquality": "high",
+      "legacyRuntimeSaddleV6": {
+        "node": "22.12.3",
+        "typescript": "5.6.3",
+        "python": "3.14.7",
+        "rust": "1.82.0",
+        "pingora": "0.4.2",
+        "docker": "27.3.1",
+        "qemu": "9.1.2"
+      }
+    },
+    "passage": {
+      "bind": {
+        "address": "0.0.0.0",
+        "httpport": 8080,
+        "httpsport": 8443,
+        "adminport": 9091,
+        "metricsport": 9090
+      },
+      "protocol": {
+        "http2": true,
+        "http3": true,
+        "quic": true,
+        "tls": {
+          "minversion": "TLS1.3",
+          "maxversion": "TLS1.3",
+          "only": true,
+          "ciphersuites": [
+            "TLS_AES_128_GCM_SHA256",
+            "TLS_AES_256_GCM_SHA384",
+            "TLS_CHACHA20_POLY1305_SHA256"
+          ],
+          "curves": [
+            "X25519",
+            "P-256",
+            "P-384"
+          ],
+          "alpn": [
+            "h2",
+            "h3",
+            "http/1.1"
+          ]
+        }
+      },
+      "runtime": {
+        "workermodel": "pingora",
+        "workertthreads": "auto",
+        "nodemain": "pipelinememorypassage.ts",
+        "implementation": "coreorchestrator.ts",
+        "nativepriority": [
+          "node:fs",
+          "node:http",
+          "node:https",
+          "node:crypto",
+          "node:path",
+          "node:os",
+          "node:net"
+        ]
+      },
+      "limits": {
+        "maxconnections": 131072,
+        "maxrequestsize": "50GiB",
+        "keepalive": "75s",
+        "readtimeout": "30s",
+        "writetimeout": "30s"
+      },
+      "logging": {
+        "level": "info",
+        "acceslog": "/var/log/saddle/passage/access.log",
+        "errorlog": "/var/log/saddle/passage/error.log",
+        "requestidheader": "x-saddle-request-id",
+        "format": "json"
+      },
+      "errorcatcher": {
+        "enabled": true,
+        "endpoint": "/_passage/error",
+        "uisize": "44px",
+        "fallbackpage": "/usr/share/saddle/static/error44.html",
+        "jsonerror": true,
+        "catchall": [
+          502,
+          503,
+          504,
+          413,
+          429
+        ]
+      }
+    },
+    "upstreams": {
+      "vmprimary": {
+        "id": "vmprimary",
+        "description": "Primary QEMU 11.1.0 VM pool, AMD Ryzen X Series, 1..1024 vCPU modular",
+        "type": "qemuvm",
+        "discovery": "static",
+        "engine": "qemu 11.1.0 + kvm",
+        "nodes": "/mnt/data/saddle-v6/boards.json",
+        "endpoints": [
+          {
+            "address": "127.0.0.1",
+            "port": 22,
+            "weight": 100,
+            "meta": {
+              "vcpu": 32,
+              "rammb": 65536,
+              "role": "primary",
+              "arch": "amdryzenxseries",
+              "qemu": "11.1.0"
+            }
+          },
+          {
+            "address": "10.88.0.2",
+            "port": 2222,
+            "weight": 100,
+            "meta": {
+              "vcpu": 137,
+              "rammb": 7919,
+              "role": "oddcustom",
+              "board": "x3d",
+              "notes": "modular unlimited"
+            }
+          },
+          {
+            "address": "10.88.0.3",
+            "port": 2222,
+            "weight": 120,
+            "meta": {
+              "vcpu": 64,
+              "rammb": 131072,
+              "role": "secondary",
+              "arch": "xseries"
+            }
+          }
+        ],
+        "healthcheck": {
+          "path": "/healthz",
+          "interval": "5s",
+          "timeout": "2s",
+          "healthythreshold": 2,
+          "unhealthythreshold": 3,
+          "expected": 200,
+          "protocol": "https",
+          "tls": "TLS1.3"
+        }
+      },
+      "mttgworkers": {
+        "id": "mttgworkers",
+        "description": "MTTG transcode workers, ffmpeg 7.1, nvenc Blackwell GB200 B200",
+        "type": "transcode",
+        "discovery": "dns",
+        "dnsname": "mttgworkers.saddle.internal",
+        "engine": "ffmpeg 7.1 + cuda 12.8 + python 3.14.7",
+        "configref": "mttg.config",
+        "endpoints": [
+          {
+            "address": "10.88.0.10",
+            "port": 9000,
+            "weight": 200,
+            "meta": {
+              "vcpu": 64,
+              "rammb": 131072,
+              "gpu": "b200sxm",
+              "vrammb": 196608,
+              "sku": "nvidia-blackwell-b200",
+              "pipeline": "mttg"
+            }
+          },
+          {
+            "address": "10.88.0.11",
+            "port": 9000,
+            "weight": 250,
+            "meta": {
+              "vcpu": 192,
+              "rammb": 262144,
+              "gpu": "gb200",
+              "vrammb": 393216,
+              "sku": "nvidia-blackwell-gb200",
+              "pipeline": "mttg",
+              "nvlink": true
+            }
+          },
+          {
+            "address": "10.88.0.12",
+            "port": 9000,
+            "weight": 80,
+            "meta": {
+              "vcpu": 16,
+              "rammb": 32768,
+              "gpu": "b100",
+              "vrammb": 98304,
+              "sku": "nvidia-blackwell-b100"
+            }
+          }
+        ],
+        "healthcheck": {
+          "path": "/mttg/health",
+          "interval": "10s",
+          "timeout": "3s",
+          "grpc": true,
+          "expected": 200
+        },
+        "autoscale": {
+          "min": 2,
+          "max": 64,
+          "metric": "queuelen",
+          "threshold": 20
+        }
+      },
+      "gpumetrics": {
+        "id": "gpumetrics",
+        "description": "GPU telemetry, DCGM, Blackwell power memory, 44px dashboard",
+        "type": "metrics",
+        "discovery": "static",
+        "configref": "gpu.config",
+        "databaseref": "gpus.json",
+        "vramref": "vram.json",
+        "engine": "dcgm 3.3 + prometheus",
+        "endpoints": [
+          {
+            "address": "127.0.0.1",
+            "port": 9400,
+            "weight": 100,
+            "meta": {
+              "role": "dcgm",
+              "gpus": "nvidiablackwell",
+              "arch": "blackwell",
+              "vram": "2-4tbhost"
+            }
+          }
+        ],
+        "healthcheck": {
+          "path": "/metrics",
+          "interval": "15s",
+          "timeout": "5s",
+          "expected": 200
+        }
+      },
+      "hyperscalepool": {
+        "id": "hyperscalepool",
+        "description": "Hyperscale extreme 1024 vCPU 2-4TB RAM nodes for memory bound jobs",
+        "type": "compute",
+        "discovery": "static",
+        "engine": "qemu 11.1.0 + numa + hugepages",
+        "numa": true,
+        "hugepages": "1GiB",
+        "endpoints": [
+          {
+            "address": "10.88.1.2",
+            "port": 8080,
+            "weight": 100,
+            "meta": {
+              "vcpu": 1024,
+              "rammb": 2097152,
+              "ram": "2TB",
+              "tier": "hyperscale",
+              "note": "1024 vCPU / 2048GB RAM, observer sees massive host, 2TB minimal",
+              "coresref": "cores.json",
+              "vcpusref": "vcpus.json",
+              "processorsref": "processors.json"
+            }
+          },
+          {
+            "address": "10.88.1.3",
+            "port": 8080,
+            "weight": 100,
+            "meta": {
+              "vcpu": 1024,
+              "rammb": 4194304,
+              "ram": "4TB",
+              "tier": "hyperscale",
+              "note": "1024 vCPU / 4096GB RAM SADDLE max 4TB, edge for transcode cache"
+            }
+          },
+          {
+            "address": "10.88.1.4",
+            "port": 8080,
+            "weight": 90,
+            "meta": {
+              "vcpu": 1024,
+              "rammb": 3145728,
+              "ram": "3TB",
+              "tier": "hyperscale",
+              "note": "1024 vCPU / 3072GB RAM mid tier, blackwell weighted"
+            }
+          }
+        ],
+        "healthcheck": {
+          "path": "/hyperscale/healthz",
+          "interval": "10s",
+          "timeout": "5s",
+          "healthythreshold": 2,
+          "unhealthythreshold": 2,
+          "expected": 200
+        }
+      }
+    },
+    "routes": [
+      {
+        "id": "apiv5transcode",
+        "match": {
+          "pathprefix": "/api/v5/transcode",
+          "methods": [
+            "GET",
+            "POST",
+            "PUT",
+            "PATCH"
+          ],
+          "headers": {
+            "xmttgpipeline": "present"
+          }
+        },
+        "upstream": "mttgworkers",
+        "loadbalancing": "leastconn",
+        "description": "MTTG transcode submit, long lived, least connections best",
+        "timeout": "3600s",
+        "bodylimit": "50GiB",
+        "retries": 2,
+        "priority": 10,
+        "circuitbreaker": {
+          "maxconnections": 256,
+          "maxpending": 2048,
+          "maxretries": 3,
+          "ejection": {
+            "consecutive5xx": 5,
+            "interval": "30s",
+            "base": "30s",
+            "maxejection": 50
+          }
+        },
+        "headers": {
+          "add": {
+            "xsaddlegateway": "passage-v6",
+            "xsaddlevcpumode": "modular-unlimited-1024",
+            "xblackwell": "enabled",
+            "xpingora": "0.4.2",
+            "xnode": "24.19.0"
+          }
+        },
+        "ratelimit": {
+          "rps": 2000,
+          "burst": 4000,
+          "key": "ip"
+        }
+      },
+      {
+        "id": "hlsedge",
+        "match": {
+          "pathprefix": "/hls/",
+          "methods": [
+            "GET",
+            "HEAD",
+            "OPTIONS"
+          ],
+          "query": {
+            "segment": "present"
+          }
+        },
+        "upstream": "mttgworkers",
+        "loadbalancing": "poweroftwochoices",
+        "description": "HLS segments edge cache, p2c picks two random least loaded",
+        "timeout": "5s",
+        "bodylimit": "10MiB",
+        "priority": 20,
+        "caching": {
+          "enabled": true,
+          "type": "edge",
+          "ttl": "60s",
+          "swr": "30s",
+          "maxfilesize": "10MiB",
+          "cachecontrol": "public, max-age=2, stale-while-revalidate=30",
+          "key": [
+            "uri",
+            "query",
+            "header-accept"
+          ],
+          "storage": "/var/cache/saddle/hls",
+          "sizelimit": "500GiB",
+          "tiers": 2
+        },
+        "headers": {
+          "add": {
+            "xsaddlecache": "edge-p2c",
+            "cachecontrol": "public"
+          }
+        },
+        "compression": {
+          "enabled": true,
+          "types": [
+            "application/vnd.apple.mpegurl",
+            "video/mp2t"
+          ]
+        }
+      },
+      {
+        "id": "apiv5root",
+        "match": {
+          "pathprefix": "/api/v5/",
+          "methods": [
+            "GET",
+            "POST",
+            "PUT",
+            "DELETE",
+            "PATCH"
+          ]
+        },
+        "upstream": "vmprimary",
+        "loadbalancing": "roundrobin",
+        "description": "Root API round robin fair distribution stateless",
+        "timeout": "30s",
+        "retries": 2,
+        "headers": {
+          "add": {
+            "xsaddlegateway": "passage-v6",
+            "xsaddlemodes": 30
+          }
+        },
+        "ratelimit": {
+          "rps": 5000,
+          "burst": 10000
+        }
+      },
+      {
+        "id": "hyperscalecompute",
+        "match": {
+          "pathprefix": "/api/v6/hyperscale/",
+          "headers": {
+            "xsaddletier": "hyperscale"
+          },
+          "methods": [
+            "GET",
+            "POST"
+          ]
+        },
+        "upstream": "hyperscalepool",
+        "loadbalancing": "weighted",
+        "description": "Hyperscale tier weighted by RAM and Blackwell VRAM",
+        "timeout": "600s",
+        "retries": 1,
+        "headers": {
+          "add": {
+            "xsaddlehyperscale": "1024vcpu-2-4tb",
+            "xblackwell": "weighted"
+          }
+        },
+        "bodylimit": "10GiB"
+      },
+      {
+        "id": "gpudashboard",
+        "match": {
+          "pathprefix": "/gpu/",
+          "methods": [
+            "GET"
+          ]
+        },
+        "upstream": "gpumetrics",
+        "loadbalancing": "ringhash",
+        "description": "GPU metrics dashboard, ringhash ip hash for affinity",
+        "timeout": "15s",
+        "auth": "apikey",
+        "headers": {
+          "add": {
+            "xsaddlegpuarch": "blackwell",
+            "xryzenx": "enabled",
+            "xpingora": "0.4.2"
+          }
+        }
+      },
+      {
+        "id": "vmsstunnel",
+        "match": {
+          "pathprefix": "/ssh/",
+          "upgrade": "websocket"
+        },
+        "upstream": "vmprimary",
+        "loadbalancing": "ringhash",
+        "description": "VM SSH over websocket, ip hash affinity",
+        "timeout": "300s",
+        "headers": {
+          "add": {
+            "xsaddlepassage": "vsock-virtio"
+          }
+        }
+      },
+      {
+        "id": "errorcatcher",
+        "match": {
+          "pathprefix": "/_passage/error",
+          "methods": [
+            "GET"
+          ]
+        },
+        "upstream": "vmprimary",
+        "loadbalancing": "roundrobin",
+        "description": "Error catcher overlay 44px touch target",
+        "timeout": "5s",
+        "auth": false
+      }
+    ],
+    "loadbalancing": {
+      "defaultpolicy": "roundrobin",
+      "policies": {
+        "roundrobin": {
+          "type": "roundrobin",
+          "description": "Fair distribution, stateless API, observer cycles endpoints",
+          "algorithm": "weighted round robin simple",
+          "resetslowstart": true,
+          "slowstart": "10s"
+        },
+        "leastconn": {
+          "type": "leastconn",
+          "description": "Best for /api/v5/transcode long jobs, least active connections",
+          "choice": "activeconns",
+          "slowstart": "30s",
+          "emaalpha": 0.2,
+          "observer": "tracks active request count per mttgworkers node"
+        },
+        "ringhash": {
+          "type": "ringhash",
+          "description": "Consistent hash ring, ip affinity for gpu and ssh tunnel",
+          "hash": "ip",
+          "replication": 256,
+          "vnodes": 256,
+          "observer": "maps client ip to ring position"
+        },
+        "weighted": {
+          "type": "weighted",
+          "description": "Weighted round robin Blackwell aware, B200 192GB weight high",
+          "algorithm": "wrr blackwell",
+          "weightsource": "meta.vrammb",
+          "blackwellpriority": {
+            "enabled": true,
+            "skus": [
+              "gb200",
+              "b200sxm",
+              "b100"
+            ],
+            "vramweightmultiplier": 2.0,
+            "powerlimit": "1000W"
+          },
+          "observer": "favors GB200 192GB, B200 192GB over tiny 1GB",
+          "examples": {
+            "b200sxm192gb": 250,
+            "gb200393gb": 300,
+            "tiny1gb": 10
+          }
+        },
+        "poweroftwochoices": {
+          "type": "pof2",
+          "alias": "poweroftwochoices",
+          "description": "Best for /hls/ edge cache, two random picks least loaded",
+          "choices": 2,
+          "loadmetric": "inflight + latency",
+          "cacheaware": true,
+          "observer": "samples two endpoints from mttgworkers, picks less loaded, edge cache friendly"
+        },
+        "leastresponsetime": {
+          "type": "leastresponsetime",
+          "description": "Best for hyperscale memory bound, picks fastest to respond",
+          "emaalpha": 0.2,
+          "slowstart": "60s"
+        }
+      },
+      "health": {
+        "passive": true,
+        "active": true,
+        "ejectionpercent": 50,
+        "failurethreshold": 5,
+        "successrate": 0.95
+      }
+    },
+    "middleware": {
+      "cors": {
+        "enabled": true,
+        "allowedorigins": [
+          "https://saddle.local",
+          "https://*.saddle.dev",
+          "https://saddle-v6.internal"
+        ],
+        "allowedmethods": [
+          "GET",
+          "POST",
+          "PUT",
+          "DELETE",
+          "OPTIONS",
+          "PATCH",
+          "HEAD"
+        ],
+        "allowedheaders": [
+          "*"
+        ],
+        "maxage": "86400s"
+      },
+      "rateglobal": {
+        "enabled": true,
+        "rps": 20000,
+        "burst": 30000,
+        "key": "ip",
+        "redisurl": "redis://127.0.0.1:6379/0",
+        "engine": "redis 7.4"
+      },
+      "auth": {
+        "type": "jwt",
+        "issuer": "https://auth.saddle.local",
+        "jwksurl": "https://auth.saddle.local/.well-known/jwks.json",
+        "requiredfor": [
+          "/api/v5/transcode",
+          "/gpu/",
+          "/api/v6/hyperscale/"
+        ],
+        "leeway": "60s"
+      },
+      "compression": {
+        "enabled": true,
+        "types": [
+          "text/*",
+          "application/json",
+          "application/javascript",
+          "application/vnd.apple.mpegurl"
+        ],
+        "minsize": "1KiB",
+        "level": 4
+      },
+      "requestlog": {
+        "fields": [
+          "vcpu",
+          "rammb",
+          "vrammb",
+          "gpusku",
+          "routeid",
+          "upstreamid",
+          "statuscode",
+          "latency"
+        ],
+        "format": "json",
+        "sample": 1.0
+      }
+    },
+    "tls": {
+      "cert": "/etc/saddle/certs/v6/tls.crt",
+      "key": "/etc/saddle/certs/v6/tls.key",
+      "ca": "/etc/saddle/certs/v6/ca.crt",
+      "autoreload": true,
+      "ocspstapling": true,
+      "minversion": "TLS1.3",
+      "maxversion": "TLS1.3",
+      "only": true,
+      "protocols": [
+        "TLS1.3"
+      ],
+      "h2": true,
+      "h3": true,
+      "quic": {
+        "enabled": true,
+        "port": 8443,
+        "idle": "30s"
+      },
+      "ciphers": {
+        "enforced": "TLS1.3_only"
+      }
+    },
+    "observability": {
+      "prometheus": true,
+      "prometheusport": 9090,
+      "otelendpoint": "http://127.0.0.1:4317",
+      "tracingsamplerate": 0.1,
+      "metricslabels": [
+        "routeid",
+        "upstreamid",
+        "vcpu",
+        "rammb",
+        "gpusku",
+        "statuscode",
+        "lbpolicy"
+      ],
+      "dashboard": {
+        "touchtarget": "44px",
+        "enabled": true,
+        "endpoint": "/_passage/dashboard"
+      },
+      "logging": {
+        "level": "info",
+        "json": true
+      }
+    },
+    "pipeline": {
+      "memorypassage": "pipelinememorypassage.ts",
+      "coreorchestrator": "coreorchestrator.ts",
+      "qemubridge": "qemubridge.py",
+      "virtualizationcore": "virtualizationcore.hpp",
+      "internalmemory": true,
+      "modes": 30,
+      "contextsperfile": "20-25",
+      "maxperfile": 20,
+      "threeLayer": "direct",
+      "libraryFirst": "typescript"
+    },
+    "sidecar": {
+      "docker": "29.7.2",
+      "qemu": "11.1.0",
+      "dockerconfig": "docker.config",
+      "qemuconfig": "qemu.config",
+      "compose": "dockercompose.yml",
+      "dockerfile": "dockerfile",
+      "python": "3.14.7",
+      "node": "24.19.0"
+    },
+    "xexamples": {
+      "extremevcpu": {
+        "description": "Unlimited modular vCPU 1..4096 any integer prime allowed",
+        "values": [
+          1,
+          4,
+          13,
+          32,
+          37,
+          64,
+          137,
+          192,
+          256,
+          512,
+          1024
+        ],
+        "prime": 7919,
+        "hyperscale": 1024
+      },
+      "extremeram": {
+        "description": "Extensible RAM MiB 1MiB granularity 2TB 3TB 4TB",
+        "valuesmb": [
+          512,
+          1337,
+          4096,
+          7919,
+          16834,
+          65536,
+          131072,
+          262144,
+          524288,
+          1048576,
+          2097152,
+          3145728,
+          4194304
+        ],
+        "maxtb": 4,
+        "mintb": 2,
+        "hyperscale": [
+          2097152,
+          3145728,
+          4194304
+        ]
+      },
+      "extremevram": {
+        "description": "Extensible VRAM slices Blackwell vGPU MIG",
+        "valuesmb": [
+          1024,
+          4096,
+          7183,
+          16384,
+          23552,
+          32768,
+          49152,
+          98304,
+          196608,
+          393216,
+          786432
+        ],
+        "blackwell": {
+          "b100": 98304,
+          "b200": 196608,
+          "gb200": 393216
+        }
+      }
+    }
+  },
+  "passthroughModes": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "modeOverview": [
+      {
+        "id": "vfio",
+        "type": "full passthrough",
+        "granularity": "whole PCI function",
+        "requiresKvm": true,
+        "lossOfSnapshot": true
+      },
+      {
+        "id": "mdev",
+        "type": "mediated passthrough",
+        "granularity": "vendor-defined slice",
+        "requiresKvm": true,
+        "lossOfSnapshot": true
+      },
+      {
+        "id": "mig",
+        "type": "GPU hardware slicing",
+        "granularity": "memory+SM partition (1g.24gb/2g.48gb/4g.96gb)",
+        "requiresKvm": true,
+        "lossOfSnapshot": false
+      },
+      {
+        "id": "vgpu",
+        "type": "licensed mediated GPU",
+        "granularity": "vGPU profile (1B/2B/4Q...)",
+        "requiresKvm": true,
+        "lossOfSnapshot": true
+      },
+      {
+        "id": "sriov",
+        "type": "PCIe virtual functions",
+        "granularity": "VF of NIC/GPU",
+        "requiresKvm": true,
+        "lossOfSnapshot": true
+      },
+      {
+        "id": "vfio-user",
+        "type": "userspace device emulation",
+        "granularity": "any device emulated by a userspace server",
+        "requiresKvm": false,
+        "lossOfSnapshot": false
+      },
+      {
+        "id": "hotplug",
+        "type": "runtime attach/detach",
+        "granularity": "cpu (vCPU), memory (pc-dimm), pci (root-port)",
+        "requiresKvm": false,
+        "lossOfSnapshot": false
+      },
+      {
+        "id": "none",
+        "type": "fully virtual devices",
+        "granularity": "virtio only",
+        "requiresKvm": false,
+        "lossOfSnapshot": false
+      }
+    ],
+    "vfio": {
+      "driver": "vfio-pci",
+      "kernelModules": [
+        "vfio",
+        "vfio_iommu_type1",
+        "vfio_pci",
+        "vfio_virqfd"
+      ],
+      "iommuKernelCmdline": {
+        "intel": "intel_iommu=on iommu=pt",
+        "amd": "amd_iommu=on iommu=pt"
+      },
+      "modprobeConf": "options vfio-pci ids=10de:2b85,10de:26b5,1002:748e",
+      "bindProcedure": [
+        "1. lspci -nnk to locate the BDF and current driver",
+        "2. echo 10de 2b85 > /sys/bus/pci/drivers/vfio-pci/new_id (or unbind from native driver + bind to vfio-pci)",
+        "3. verify /dev/vfio/<group> exists for the device group",
+        "4. ls /sys/kernel/iommu_groups/ and cat /sys/bus/pci/devices/<bdf>/iommu_group/devices to check isolation"
+      ],
+      "iommuGroups": {
+        "list": "ls /sys/kernel/iommu_groups/",
+        "membership": "ls /sys/kernel/iommu_groups/<n>/devices/",
+        "requirement": "the passed device must sit in a group with no other active host devices (ACS) or the whole group must be passed"
+      },
+      "iommufd": {
+        "device": "/dev/iommu",
+        "note": "modern replacement for /dev/vfio/vfio container API; QEMU -object iommu-backend=type=iommufd; Kata 4.1 uses IOMMUFD for NVSwitch passthrough"
+      },
+      "qemuUsage": "-device vfio-pci,host=0000:01:00.0 (q35: place behind a pcie-root-port for reset support)",
+      "limits": [
+        "VM loses live snapshot/migration compatibility while a VFIO device is attached",
+        "GPU reset requires the device to support FLR or a reboot of the host",
+        "NVIDIA consumer drivers historically refused passthrough (Code 43) - modern R570+ drivers allow it"
+      ]
+    },
+    "mdev": {
+      "description": "Mediated devices: a physical device driver creates virtual devices exposed as vfio-mdev sysfs entries that can be assigned to VMs.",
+      "create": "echo <uuid> | sudo tee /sys/bus/pci/devices/<bdf>/mdev_supported_types/<type>/create",
+      "listTypes": "ls /sys/bus/pci/devices/<bdf>/mdev_supported_types/",
+      "qemuUsage": "-device vfio-pci,sysfsdev=/sys/bus/mdev/devices/<uuid>",
+      "exampleTypes": [
+        "nvidia-155 (vGPU profile id format)",
+        "vfio_ap-passthrough (s390)",
+        "vfio_ccw-passthrough (s390)"
+      ],
+      "statusNote": "Intel GVT-g (i915 mdev) was removed from upstream kernels; on x86 the practical mdev users in 2026 are NVIDIA vGPU (licensed) and academic/vfio_ap stacks.",
+      "requiresKvm": true
+    },
+    "mig": {
+      "description": "NVIDIA Multi-Instance GPU: hardware partitioning of Blackwell/Hopper/Ampere datacenter GPUs into isolated GPU instances. Full command set in gpu.json mig section.",
+      "profilesRtxPro6000Server": [
+        {
+          "profile": "1g.24gb",
+          "instances": 4,
+          "vramGb": 24
+        },
+        {
+          "profile": "2g.48gb",
+          "instances": 2,
+          "vramGb": 48
+        },
+        {
+          "profile": "4g.96gb",
+          "instances": 1,
+          "vramGb": 96
+        }
+      ],
+      "guestAssignment": {
+        "cudaVisibleDevices": "MIG-<uuid>",
+        "container": "NVIDIA_VISIBLE_DEVICES=MIG-<uuid>",
+        "note": "MIG instances are addressed through the parent GPU driver; they are not PCI devices and cannot be passed with vfio-pci individually"
+      },
+      "engineUse": "inference-mig VM profile: multi-tenant 24/48/96 GB vRAM slices without passthrough",
+      "requiresKvm": "parent GPU must be owned by a real host driver (bare-metal or nested); MIG cannot be created on a virtualized GPU"
+    },
+    "vgpu": {
+      "description": "NVIDIA vGPU (GRID): licensed mediated GPU passthrough; host installs the GRID driver and creates mdev instances typed nvidia-<profile>.",
+      "profileNaming": "<frame-buffer-size>-<license>: e.g. A100-2-20B (A100 20GB vGPU, vCS/PC/B license) or L40-4Q (RTX 6000 Ada 4GB Q profile for Quadro features)",
+      "licensing": "NVIDIA vGPU License Server (CLS/DLS); guest checks out a license at boot",
+      "guestDriver": "GRID guest driver matching host branch (R580 line in 2026)",
+      "unlicensedGrace": "vGPU evaluation mode runs with reduced features for a trial period",
+      "alternatives": [
+        "Intel GPU SR-IOV (Flex 170, Arc Pro, Xe): native VF partitioning via SR-IOV",
+        "AMD SR-IOV on Instinct MI300 (experimental)"
+      ]
+    },
+    "sriov": {
+      "description": "SR-IOV: a PCIe device exposes Virtual Functions bound to vfio-pci and assigned to VMs with near-native performance.",
+      "createVfs": "echo 8 | sudo tee /sys/class/net/enp1s0f0/device/sriov_numvfs",
+      "bindVf": "driverctl unset-override / native driver, or echo <bdf> > /sys/bus/pci/drivers/vfio-pci/bind",
+      "typicalNics": [
+        "Intel E810 (100GbE)",
+        "Intel X710 (40GbE)",
+        "NVIDIA ConnectX-6 Dx / ConnectX-7",
+        "Broadcom NetXtreme-E"
+      ],
+      "qemuUsage": "-device vfio-pci,host=0000:01:00.3 -device vfio-pci,host=0000:01:00.4 ...",
+      "fallback": "virtio-net with iothread + multiqueue gives portable performance without host dependencies (default in vm.config.json)",
+      "sriovGpus": [
+        "Intel Data Center GPU Flex 170 (2 VFs)",
+        "Intel Arc Pro A60? (2 VFs)",
+        "AMD Instinct MI300X SR-IOV (roadmap)"
+      ]
+    },
+    "vfioUser": {
+      "protocol": "vfio-user: VFIO-over-UNIX-socket user-space device emulation (QEMU docs/vfio-user.rst; NVMe world's userspace device servers)",
+      "cloudHypervisor": {
+        "version": "v53.0 (2026-07-12)",
+        "status": "experimental",
+        "cli": "--user-device socket=<path>",
+        "hotplug": "ch-remote add-user-device socket=<path>",
+        "note": "offloaded snapshot/restore daemon with userfaultfd + vhost-user landed in the same v53 release"
+      },
+      "qemuSupport": "-device vfio-user-pci,socket=<path> (QEMU 7.1+; parity with Cloud Hypervisor for shared servers)",
+      "advantages": [
+        "device emulation runs in a separate userspace process (crash isolation, live upgrade)",
+        "no kernel driver and no IOMMU requirement on the host - works without /dev/kvm",
+        "compatible with snapshottable, migratable VMs (unlike real VFIO)"
+      ],
+      "engineUse": "emulated NVMe/GPU backends for the engine without host hardware"
+    },
+    "hotplug": {
+      "cpu": {
+        "qmp": [
+          "query-hotpluggable-cpus",
+          "device_add driver=epyc-v5-x86_64-cpu,id=cpu-N,socket-id=0,core-id=48,thread-id=0"
+        ],
+        "precondition": "-smp <N>,maxcpus=<M> at boot (cores.json qemu_topology_generation)",
+        "guest": "Linux udev + acpi hotplug handler (virtio and ACPI CPU hotplug for x86)"
+      },
+      "memory": {
+        "precondition": "-m 8G,slots=4,maxmem=64G",
+        "qmp": [
+          "object-add qom-type=memory-backend-ram,id=mem1,props={'size':17179869184}",
+          "device_add driver=pc-dimm,id=dimm1,memdev=mem1"
+        ],
+        "guest": "online_memory_block via sysfs; NUMA node attach with -numa node,memdev=..."
+      },
+      "pci": {
+        "q35": "device_add pcie-root-port,id=rp1,bus=pcie.0 then device_add <dev>,bus=rp1",
+        "microvm": "no PCI hotplug (virtio-mmio fixed); use ch-remote with Cloud Hypervisor instead",
+        "devices": [
+          "virtio-blk (data volumes)",
+          "virtio-net",
+          "vfio-pci passthrough",
+          "usb-host"
+        ]
+      },
+      "firecracker": "PCI virtio hotplug in developer preview since v1.16.0 (network/block attach/detach)",
+      "limits": "CPU and memory unplug remain less reliable than plug; orchestrate scale-out instead"
+    },
+    "kvm": {
+      "requirement": "CPU with VT-x/AMD-SVM + kvm(|-intel|-amd) kernel module + accessible /dev/kvm",
+      "checkCommands": [
+        "test -e /dev/kvm && echo kvm-present",
+        "kvm-ok (Ubuntu cpu-checker)",
+        "lscpu | grep Virtualization"
+      ],
+      "githubHostedRunners": {
+        "available": false,
+        "reason": "hosted runners are Azure VMs without nested virtualization exposed; /dev/kvm absent",
+        "evidence": [
+          "actions/runner-images#12933",
+          "actions/runner-images#14062",
+          "actuated.com/blog/kvm-in-github-actions",
+          "e2b-dev/infra self-host.md: Firecracker requires bare metal or nested virtualization support"
+        ]
+      },
+      "fallback": {
+        "accel": "tcg,thread=multi (MTTCG, see mttcg.json)",
+        "penalty": "10-30x slower than KVM for compute workloads; deterministic and dependency-free",
+        "firecracker": "cannot run (hard KVM requirement)",
+        "kataContainers": "cannot run its microVM hypervisors (QEMU/KVM, Cloud Hypervisor, Firecracker) on hosted runners; use Docker + gVisor runsc (works without KVM) instead",
+        "knownPitfall": "QEMU auto-fallback KVM->TCG broke historically (community discussion #151747); always pass -accel tcg,thread=multi explicitly in CI"
+      },
+      "selfHosted": {
+        "bareMetal": "full matrix available: KVM + VFIO + MIG + Firecracker snapshots (restore as low as 4 ms)",
+        "nested": "KVM and Firecracker work; VFIO/MIG of real hardware still needs bare metal",
+        "providers": [
+          "WarpBuild bare-metal runners",
+          "actuated (KernelCI-class bare metal)",
+          "self-hosted GitHub runners"
+        ]
+      }
+    },
+    "noneMode": {
+      "id": "none",
+      "aliases": [
+        "nodriver",
+        "virtio-only"
+      ],
+      "description": "Fully virtual devices only - the default for ephemeral CI sandboxes: no host hardware dependency, no passthrough drivers, snapshot-safe, migratable.",
+      "qemuFlags": "-nodefaults -vga none (no display driver), every device explicitly virtio",
+      "devices": [
+        "virtio-blk",
+        "virtio-scsi",
+        "virtio-net",
+        "virtio-rng",
+        "virtio-input/usb-tablet",
+        "virtio-gpu",
+        "virtio-fs (host share via vhost-user-fs)"
+      ],
+      "rationale": [
+        "snapshot/migration compatibility (passage.json mode_overview loss_of_snapshot=false)",
+        "no IOMMU requirement; runs on any host including GitHub-hosted runners",
+        "GPU identity delivered by software stack: Mesa llvmpipe/lavapipe + smi-adapter/NVML shim (gpu.json, mesa.json)"
+      ]
+    },
+    "decisionMatrix": [
+      {
+        "situation": "Ephemeral CI sandbox on GitHub-hosted runner",
+        "mode": "none",
+        "accel": "tcg,thread=multi",
+        "gpu": "llvmpipe/lavapipe + smi-adapter"
+      },
+      {
+        "situation": "Self-hosted runner, needs real GPU for training",
+        "mode": "vfio",
+        "accel": "kvm",
+        "gpu": "vfio-pci host=GPU BDF"
+      },
+      {
+        "situation": "One physical GPU, many tenants",
+        "mode": "mig",
+        "accel": "kvm (parent in host)",
+        "gpu": "MIG 1g.24gb x4 on RTX PRO 6000 Server"
+      },
+      {
+        "situation": "Licensed VDI graphics",
+        "mode": "vgpu",
+        "accel": "kvm",
+        "gpu": "GRID vGPU profile"
+      },
+      {
+        "situation": "Near-native networking",
+        "mode": "sriov",
+        "accel": "kvm",
+        "nic": "ConnectX-6 Dx VF"
+      },
+      {
+        "situation": "Userspace device server, no kernel deps",
+        "mode": "vfio-user",
+        "accel": "any",
+        "device": "--user-device socket (Cloud Hypervisor v53, experimental)"
+      },
+      {
+        "situation": "Scale a running VM without restart",
+        "mode": "hotplug",
+        "accel": "any",
+        "targets": [
+          "vCPU",
+          "pc-dimm memory",
+          "virtio disks"
+        ]
+      }
+    ]
+  },
+  "networkBinding": {
+    "description": "randomized host port never localhost, 0.0.0.0 bind, crypto.randomInt 20000-60000, TOCTOU immunity",
+    "bindAddress": "0.0.0.0",
+    "hostResolution": "127.0.0.1 or container gateway, never literal 'localhost' string",
+    "port": {
+      "strategy": "crypto.randomInt(20000,60000)",
+      "module": "node:crypto",
+      "function": "randomInt",
+      "range": [
+        20000,
+        60000
+      ],
+      "retries": 10,
+      "collisionCheck": "atomic bind with SO_REUSEPORT disabled then immediate validation"
+    },
+    "toctou": {
+      "immunity": true,
+      "technique": "bind-first-then-announce, no check-then-bind",
+      "raceWindowMs": 0,
+      "validation": "EADDRINUSE retry loop with exponential backoff"
+    },
+    "security": {
+      "landlock": true,
+      "seccomp": true,
+      "allowLoopbackOnly": false
+    },
+    "vmNetworkModesRef": "vm.config.json#productionExample.vm.network.passage (direct/bridge/nat/overlayVxlan/zeroTrust/latencyOptimization + dpdk 26.07.0, ovs 3.7.1, wireguard, ebpf libbpf 1.6.0, xdp, io_uring_zcrx)"
+  },
+  "vfioIds": {
+    "description": "vendor:device ids for the 11 profile GPUs (source: gpu.profiles.json via gpus.json#gpu_profiles_vfio; used by vfio-pci.ids kernel arg)",
+    "gpus": {
+      "mi355x": [
+        "1002:75a0"
+      ],
+      "mi350x": [
+        "1002:75a3"
+      ],
+      "b200": [
+        "10de:2941"
+      ],
+      "h200": [
+        "10de:2335"
+      ],
+      "rtx5090": [
+        "10de:2b85",
+        "10de:22e8"
+      ],
+      "rtx5080": [
+        "10de:2b80"
+      ],
+      "rtxPro6000": [
+        "10de:26b5"
+      ],
+      "rx9070xt": [
+        "1002:7550",
+        "1002:ab40"
+      ],
+      "rx7900xtx": [
+        "1002:744c",
+        "1002:ab30"
+      ],
+      "arcB580": [
+        "8086:e20b"
+      ]
+    }
+  },
+  "hostPlaybook": {
+    "source": "pool:passage.yaml [AetherForge ansible-as-checklist]",
+    "apiVersion": "aetherforge.dev/v5",
+    "kind": "Passage",
+    "metadata": {
+      "name": "default-vfio"
+    },
+    "spec": {
+      "host": {
+        "iommu": "auto",
+        "kernelArgs": [
+          "intel_iommu=on",
+          "iommu=pt",
+          "amd_iommu=on",
+          "pcie_acs_override=downstream,multifunction",
+          "vfio-pci.ids=${GPU_VENDOR}:${GPU_DEVICE},${AUDIO_VENDOR}:${AUDIO_DEVICE}"
+        ],
+        "modules": {
+          "load": [
+            "vfio",
+            "vfio_iommu_type1",
+            "vfio_pci",
+            "vendor-reset"
+          ],
+          "blacklist": [
+            "nouveau",
+            "nvidia",
+            "nvidiafb",
+            "rivafb",
+            "nvidia-drm",
+            "nvidia-modeset",
+            "amdgpu",
+            "i915"
+          ]
+        }
+      },
+      "bind": {
+        "method": "vfio-pci",
+        "devices": [
+          {
+            "name": "gpu",
+            "example": "01:00.0"
+          },
+          {
+            "name": "hdmi-audio",
+            "example": "01:00.1"
+          }
+        ],
+        "notes": [
+          "Use vendor:device from gpu.profiles.json vfioIds.",
+          "Confirm IOMMU group isolation with `find /sys/kernel/iommu_groups -type l`.",
+          "ACS override is a last resort; prefer a board with ACS."
+        ]
+      },
+      "reset": {
+        "nvidia": "vendor-reset or native on 6.8+",
+        "amd": "vendor-reset for Navi 21; native for RDNA 3/4 on 6.12+",
+        "intel": "native on Battlemage"
+      },
+      "lookingGlass": {
+        "ivshmem": "/dev/shm/looking-glass",
+        "size": "128M",
+        "user": "qemu",
+        "client": "looking-glass-client -s"
+      },
+      "singleGpu": {
+        "description": "Unbind the host console GPU, start the guest, rebind on shutdown via /etc/libvirt/hooks/qemu. Requires a second way in (SSH, IPMI).\n",
+        "hook": "/etc/libvirt/hooks/qemu.d/aetherforge"
+      },
+      "verification": [
+        "dmesg | grep -e DMAR -e AMD-Vi",
+        "ls -l /dev/vfio",
+        "qemu-system-x86_64 -device vfio-pci,help"
+      ]
+    }
+  },
+  "exampleNodeCrypto": "const port = crypto.randomInt(20000,60000); server.listen(port,'0.0.0.0')"
+}