@wenathlan/saddle 1.8.18 → 2.0.3

package/mttg.config

@@ -0,0 +1,1549 @@
+{
+  "meta": {
+    "name": "mttg.config",
+    "title": "saddle - MTTG Multi-Tenant Task Groups (cgroups v2 + tenants + transcode) with MTTCG (QEMU TCG) section",
+    "version": "2.0.0",
+    "date": "2026-08-22",
+    "language": "en",
+    "conceptSeparation": "MTTG = Multi-Tenant Task Groups (cgroup v2 cpu.weight/cpuset/memory/io/pids/hugetlb/rdma + tenants + transcode pipelines). MTTCG = QEMU Multi-Threaded TCG (one host thread per vCPU under TCG). Both live here as DISTINCT sections; MTTCG accel flags also in qemu.config#mttcg.",
+    "sources": [
+      "pool:mttg.config [S6 TOML, 28 sections: transcode/nvenc/codecs/pipelines/modes]",
+      "pool:mttcg.json [V5 - MTTCG spec: architecture/enablement/scaling_192/tuning/limitations/flags_matrix]",
+      "pool:mttg.json [OMNI 20.7KB - cgroups v2 complete: cpu.weight 1-10000/burst/cpuset/memory/io/pids/hugetlb/rdma + systemd omni.slice + tenants + qos_classes]",
+      "pool:nested_mttcg.json [tcg-accel-ops-mttcg.c functions + overhead <8%]",
+      "pool:vm.config.toml [vm.mttg tenants/qos/scheduler EEVDF+BORE+sched_ext - identical values, unified]"
+    ],
+    "mergeReport": {
+      "s6Sections": 15,
+      "modesCount": 5,
+      "resourceProfiles": 5,
+      "cgroupsControllers": [
+        "cpu",
+        "cpuset",
+        "memory",
+        "io",
+        "pids",
+        "hugetlb",
+        "rdma"
+      ],
+      "tenants": [
+        "gold",
+        "silver",
+        "bronze",
+        "_envelope"
+      ],
+      "qosClasses": [
+        "count",
+        "description",
+        "classes"
+      ],
+      "schedulers": [
+        "EEVDF (default since 6.6; kernel 7.1.9)",
+        "BORE-6.12.15",
+        "sched_ext-bp-1.2.0"
+      ],
+      "conflictResolution": "tenants gold/silver/bronze identical in mttg.json and vm.config.toml -> unified once; legacy qemu 11.1.0 pins -> 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",
+      "v4fix3PipelineSection": {
+        "stageCount": 24,
+        "policy": "create_optimal scheduling policy only; stage table delegated to media.ts (transcode domain)",
+        "skipRules": 5,
+        "passageMtu": 65536
+      }
+    }
+  },
+  "mttg": {
+    "stack": {
+      "priority": [
+        "typescript",
+        "node",
+        "python",
+        "docker",
+        "qemu",
+        "ffmpeg"
+      ],
+      "nodeVersion": "26.7.0",
+      "nodeAltVersion": "24.19.0",
+      "typescriptVersion": "7.0.2",
+      "pythonVersion": "3.14.7",
+      "dockerVersion": "29.7.2",
+      "qemuVersion": "11.1.0",
+      "ffmpegVersion": "7.1.1",
+      "nativeNode": [
+        "node:fs",
+        "node:path",
+        "node:crypto",
+        "node:http",
+        "node:os",
+        "node:worker_threads",
+        "node:child_process",
+        "node:stream",
+        "node:buffer"
+      ],
+      "githubActions": [
+        "actions/checkout@v7.0.1",
+        "actions/setup-node@v7.0.0",
+        "actions/setup-python@v7.0.0",
+        "docker/setup-qemu-action@v4.2.0",
+        "docker/setup-buildx-action@v4.3.0",
+        "docker/build-push-action@v7.3.0"
+      ],
+      "node": "26.7.0 Current",
+      "nodeAlt": "24.19.0 LTS",
+      "typescript": "7.0.2",
+      "python": "3.14.7",
+      "docker": "29.7.2",
+      "qemu": "11.1.0",
+      "legacyPinsSaddleV6": {
+        "priority": [
+          "typescript",
+          "node",
+          "python",
+          "docker",
+          "qemu",
+          "ffmpeg"
+        ],
+        "nodeVersion": "22.12.3",
+        "nodeAltVersion": "23.5.0",
+        "typescriptVersion": "5.6.3",
+        "pythonVersion": "3.13.5",
+        "dockerVersion": "27.3.1",
+        "qemuVersion": "9.1.2",
+        "ffmpegVersion": "7.1.1",
+        "nativeNode": [
+          "node:fs",
+          "node:path",
+          "node:crypto",
+          "node:http",
+          "node:os",
+          "node:worker_threads",
+          "node:child_process",
+          "node:stream",
+          "node:buffer"
+        ],
+        "githubActions": [
+          "actions/checkout@v4.2.2",
+          "actions/setup-node@v4.1.0",
+          "actions/setup-python@v5.4.0",
+          "docker/setup-qemu-action@v3.6.0",
+          "docker/setup-buildx-action@v3.7.1",
+          "docker/build-push-action@v6.10.0"
+        ]
+      }
+    },
+    "resources": {
+      "minVcpu": 1,
+      "maxVcpu": 1024,
+      "minRamMb": 512,
+      "maxRamMb": 2097152,
+      "minVramMb": 1024,
+      "maxVramMb": 196608,
+      "unitCpu": "vCPU",
+      "unitRam": "MB",
+      "unitVram": "MB",
+      "allocator": "vcpus.json + vram.json + gpus.json + boards.json",
+      "overcommitCpu": 1.25,
+      "overcommitRam": 1.1,
+      "isolation": "cgroupv2 + qemu cpuset + nvidia vgpu time-sliced",
+      "enforcement": "strict",
+      "profiles": {
+        "tiny": {
+          "vcpus": 1,
+          "ramMb": 512,
+          "vramMb": 1024,
+          "useCase": "edge preview, healthcheck, thumbnail",
+          "qos": "bronze",
+          "schedulingClass": "best-effort",
+          "ffmpegThreads": 1,
+          "notes": "minimal viable transcode, h264 baseline only"
+        },
+        "oddprime": {
+          "vcpus": 37,
+          "ramMb": 7919,
+          "vramMb": 7183,
+          "useCase": "prime stride validation, anti-alias cache test, jitter injection",
+          "qos": "silver+prime",
+          "schedulingClass": "latency-sensitive",
+          "ffmpegThreads": 37,
+          "isPrimeValidated": true,
+          "primePurpose": "memory fragmentation and NUMA distribution resilience"
+        },
+        "creator": {
+          "vcpus": 32,
+          "ramMb": 65536,
+          "vramMb": 23552,
+          "useCase": "creator 4k av1 rtx 5090, davinci, premiere, blender",
+          "qos": "gold",
+          "schedulingClass": "realtime",
+          "ffmpegThreads": 32,
+          "gpuProfile": "rtx5090 creator",
+          "referenceHardware": "nvidia blackwell rtx 5090 24GB"
+        },
+        "ml": {
+          "vcpus": 192,
+          "ramMb": 262144,
+          "vramMb": 98304,
+          "useCase": "svt-av1 2.3 two-pass, vvc research, stable diffusion video + transcode fused",
+          "qos": "gold+ml",
+          "schedulingClass": "gpu-bound",
+          "ffmpegThreads": 96,
+          "gpuProfile": "4x pro 6000 96GB or 2x b200 192GB split",
+          "nvlinkRequired": true
+        },
+        "hyperscale": {
+          "vcpus": 1024,
+          "ramMb": 2097152,
+          "vramMb": 196608,
+          "useCase": "film8k mezzanine 96GB PRO 6000, hyperscale batch",
+          "qos": "platinum-dedicated",
+          "schedulingClass": "dedicated-node",
+          "ffmpegThreads": 512,
+          "gpuProfile": "2x pro 6000 workstation 96GB unified OR 1x gb200 superchip 192GB+64k",
+          "maxTenants": 1
+        }
+      }
+    },
+    "cgroups": {
+      "version": "v2",
+      "mount": "/sys/fs/cgroup",
+      "mountOptions": "cgroup2",
+      "unified": true,
+      "controllers": [
+        "cpu",
+        "cpuset",
+        "memory",
+        "io",
+        "pids",
+        "hugetlb",
+        "rdma"
+      ],
+      "controllersAvailable": "cat /sys/fs/cgroup/cgroup.controllers",
+      "controllersEnabled": "cpu cpuset memory io pids",
+      "rootPath": "/sys/fs/cgroup",
+      "omniSlice": "/sys/fs/cgroup/omni.slice",
+      "vmPathTemplate": "/sys/fs/cgroup/omni.slice/{vm_id}",
+      "systemdIntegration": true,
+      "systemdDriver": "systemd",
+      "systemdSlice": "omni.slice",
+      "cpu": {
+        "weight": {
+          "description": "CPU weight - proportional share 1-10000, default 100",
+          "file": "cpu.weight",
+          "min": 1,
+          "max": 10000,
+          "default": 100,
+          "range": "1-10000",
+          "type": "weight",
+          "example": "echo 5000 > /sys/fs/cgroup/omni.slice/vm-001/cpu.weight"
+        },
+        "max": {
+          "description": "cpu.max quota period burst - hard limit quota per period microsec",
+          "file": "cpu.max",
+          "format": "$MAX $PERIOD",
+          "formatBurst": "$MAX $PERIOD with burst",
+          "quota": {
+            "description": "quota in microseconds - max time cgroup can be scheduled per period",
+            "default": "max",
+            "unit": "usec",
+            "example": "1600000 100000 = 16 CPUs max"
+          },
+          "period": {
+            "description": "period in microseconds",
+            "min": 1000,
+            "max": 1000000,
+            "default": 100000,
+            "unit": "usec"
+          },
+          "burst": {
+            "description": "burst - ability to burst beyond quota for short time (kernel 6.12+)",
+            "min": 0,
+            "default": 0,
+            "unit": "usec",
+            "kernelSupport": "6.2+",
+            "example": "1600000 100000 burst 320000",
+            "since": "kernel 6.2 cgroup v2 cpu burst"
+          },
+          "example": "echo '1600000 100000' > cpu.max"
+        },
+        "weightNice": {
+          "description": "cpu.weight.nice - nice value based weight -20 to 19",
+          "file": "cpu.weight.nice",
+          "min": -20,
+          "max": 19,
+          "default": 0
+        },
+        "idle": {
+          "description": "cpu.idle - if 1, cgroup only runs when no other cgroup is runnable",
+          "file": "cpu.idle",
+          "default": 0,
+          "qos": "idle"
+        },
+        "stat": {
+          "file": "cpu.stat",
+          "fields": [
+            "usage_usec",
+            "user_usec",
+            "system_usec",
+            "nr_periods",
+            "nr_throttled",
+            "throttled_usec",
+            "nr_bursts",
+            "burst_usec"
+          ]
+        }
+      },
+      "cpuset": {
+        "description": "cpuset - pin cgroup to specific CPUs and memory nodes",
+        "files": {
+          "cpus": "cpuset.cpus",
+          "mems": "cpuset.mems",
+          "effectiveCpus": "cpuset.cpus.effective",
+          "effectiveMems": "cpuset.mems.effective"
+        },
+        "cpus": {
+          "description": "cpuset.cpus - list of CPUs allowed",
+          "example": "0-15 or 0,2,4-7",
+          "file": "cpuset.cpus",
+          "effectiveFile": "cpuset.cpus.effective"
+        },
+        "mems": {
+          "description": "cpuset.mems - list of memory nodes allowed",
+          "example": "0 or 0-1",
+          "file": "cpuset.mems"
+        },
+        "exclusive": true,
+        "example": "echo '0-15' > cpuset.cpus && echo '0' > cpuset.mems"
+      },
+      "memory": {
+        "description": "memory controller - high and max limits",
+        "files": {
+          "high": "memory.high",
+          "max": "memory.max",
+          "swapMax": "memory.swap.max",
+          "current": "memory.current",
+          "events": "memory.events"
+        },
+        "high": {
+          "description": "memory.high - soft limit, throttling and reclaim starts above high",
+          "file": "memory.high",
+          "type": "bytes",
+          "default": "max",
+          "example": "60G",
+          "behavior": "throttle allocations, reclaim aggressively"
+        },
+        "max": {
+          "description": "memory.max - hard limit, OOM if exceeded above max",
+          "file": "memory.max",
+          "type": "bytes",
+          "default": "max",
+          "example": "64G",
+          "behavior": "OOM kill or allocation failure"
+        },
+        "swapMax": {
+          "description": "memory.swap.max - swap limit",
+          "file": "memory.swap.max",
+          "default": "max",
+          "example": "0 disables swap"
+        },
+        "low": {
+          "description": "memory.low - protection low limit",
+          "file": "memory.low"
+        },
+        "min": {
+          "description": "memory.min - hard protection",
+          "file": "memory.min"
+        }
+      },
+      "io": {
+        "description": "io controller - block IO weight and max",
+        "files": {
+          "weight": "io.weight",
+          "max": "io.max",
+          "stat": "io.stat",
+          "bfqWeight": "io.bfq.weight (BFQ)"
+        },
+        "weight": {
+          "description": "io.weight - proportional IO weight 1-10000",
+          "file": "io.weight",
+          "min": 1,
+          "max": 10000,
+          "default": 100
+        },
+        "max": {
+          "description": "io.max - absolute IO max rbps wbps riops wiops per device",
+          "file": "io.max",
+          "example": "254:0 rbps=1073741824 wbps=1073741824",
+          "format": "major:minor rbps=N wbps=N riops=N wiops=N"
+        },
+        "bfqWeight": {
+          "description": "BFQ scheduler weight when using BFQ",
+          "file": "io.bfq.weight",
+          "min": 1,
+          "max": 10000
+        }
+      },
+      "pids": {
+        "description": "pids controller - limit number of processes",
+        "file": "pids.max",
+        "current": "pids.current",
+        "events": "pids.events",
+        "default": "max",
+        "example": "4096",
+        "maxLimit": "4194304"
+      },
+      "hugetlb": {
+        "description": "hugetlb controller - hugepages accounting",
+        "enabled": true,
+        "files": [
+          "hugetlb.1GB.current",
+          "hugetlb.1GB.max"
+        ]
+      }
+    },
+    "cgroupVmRuntime": {
+      "engine": "mttg",
+      "version": "5.0.0",
+      "cgroupVersion": "v2",
+      "cgroupPath": "/sys/fs/cgroup/omni.slice/omni-vm-prod-001",
+      "cpuWeightMin": 1,
+      "cpuWeightMax": 10000,
+      "cpuWeightDefault": 100,
+      "cpuMaxQuota": "max",
+      "cpuMaxPeriod": 100000,
+      "cpuMaxBurst": 0,
+      "cpuset": "0-15",
+      "cpusetMems": "0",
+      "memoryHigh": "60G",
+      "memoryMax": "64G",
+      "memorySwapMax": "0",
+      "ioWeight": 100,
+      "ioMax": "rbps=1073741824 wbps=1073741824 rbps=1000 wiops=1000",
+      "pidsMax": 4096,
+      "numaBalancing": true,
+      "scheduler": "EEVDF",
+      "schedulerVersion": "kernel-7.1.9-eevdf",
+      "schedulerAlt": [
+        "BORE-6.12.15",
+        "sched_ext-bp-1.2.0"
+      ],
+      "qosClassesList": [
+        "guaranteed",
+        "burstable",
+        "besteffort",
+        "idle"
+      ],
+      "tenants": {
+        "gold": {
+          "weight": 10000,
+          "cpuMax": "1600000 100000",
+          "memoryHigh": "60G",
+          "memoryMax": "64G",
+          "ioWeight": 1000,
+          "pidsMax": 8192,
+          "qos": "guaranteed",
+          "cpuset": "0-15"
+        },
+        "silver": {
+          "weight": 5000,
+          "cpuMax": "800000 100000",
+          "memoryHigh": "30G",
+          "memoryMax": "32G",
+          "ioWeight": 500,
+          "pidsMax": 4096,
+          "qos": "burstable",
+          "cpuset": "0-7"
+        },
+        "bronze": {
+          "weight": 100,
+          "cpuMax": "200000 100000",
+          "memoryHigh": "8G",
+          "memoryMax": "16G",
+          "ioWeight": 100,
+          "pidsMax": 1024,
+          "qos": "besteffort",
+          "cpuset": "0-3"
+        }
+      },
+      "qosClasses": {
+        "guaranteed": {
+          "cpuWeight": 10000,
+          "cpuGuarantee": "100%",
+          "memoryPolicy": "no-overcommit",
+          "ioPolicy": "high-priority",
+          "description": "Guaranteed QoS: full CPU reservation, no memory overcommit, high-priority IO"
+        },
+        "burstable": {
+          "cpuWeight": 5000,
+          "cpuGuarantee": "50%",
+          "memoryPolicy": "bounded-overcommit",
+          "ioPolicy": "normal",
+          "description": "Burstable: baseline 50% CPU with burst to 100%, bounded memory overcommit"
+        },
+        "besteffort": {
+          "cpuWeight": 100,
+          "cpuGuarantee": "0%",
+          "memoryPolicy": "overcommit",
+          "ioPolicy": "low-priority",
+          "description": "Best-effort: opportunistic scheduling, full overcommit allowed"
+        },
+        "idle": {
+          "cpuWeight": 1,
+          "cpuGuarantee": "0%",
+          "memoryPolicy": "reclaim-first",
+          "ioPolicy": "idle",
+          "description": "Idle: lowest priority, first to be reclaimed under pressure"
+        }
+      }
+    },
+    "systemd": {
+      "slice": "omni.slice",
+      "sliceFile": "/etc/systemd/system/omni.slice",
+      "description": "saddle root slice for all VMs",
+      "exampleSlice": "[Unit]\nDescription=saddle Root Slice\nBefore=slices.target\n[Slice]\nCPUAccounting=yes\nMemoryAccounting=yes\nIOAccounting=yes\nTasksAccounting=yes",
+      "controllerDelegation": "Delegate=cpu cpuset memory io pids"
+    },
+    "scheduler": {
+      "default": "EEVDF",
+      "description": "CPU Scheduler - EEVDF is default since kernel 6.6, with BORE and sched_ext alternatives",
+      "schedulers": [
+        {
+          "name": "EEVDF",
+          "fullName": "Earliest Eligible Virtual Deadline First",
+          "since": "kernel 6.6",
+          "status": "default since kernel 6.6",
+          "version": "kernel-7.1.9-eevdf",
+          "description": "Fair scheduling with proportional weight, replaces CFS 6.6+",
+          "cgroupInterface": "cpu.weight 1-10000",
+          "features": [
+            "lag-based",
+            "virtual deadline",
+            "proportional fairness"
+          ],
+          "tuning": {
+            "sysctl": [
+              "kernel.sched_bore=0",
+              "kernel.sched_min_granularity_ns=4000000"
+            ]
+          }
+        },
+        {
+          "name": "BORE",
+          "fullName": "Burst-Oriented Response Enhancer",
+          "version": "BORE-6.12.15",
+          "since": "kernel 6.8 custom patch",
+          "status": "alternative patch",
+          "description": "BORE scheduler patch - burst-oriented, reduces latency for interactive workloads",
+          "patchUrl": "https://github.com/firelzrd/bore-scheduler",
+          "features": [
+            "burst-awareness",
+            "interactive priority",
+            "low latency"
+          ],
+          "binary": "kernel with BORE patch"
+        },
+        {
+          "name": "sched_ext",
+          "fullName": "Extensible Scheduler (eBPF Schedulers)",
+          "version": "sched_ext-bp-1.2.0",
+          "since": "kernel 6.12",
+          "status": "stable in 6.12+",
+          "description": "eBPF based extensible scheduler - load custom BPF scheduler programs",
+          "tools": {
+            "scxSimple": "Simple scheduler",
+            "scxBpfland": "Userland-inspired scheduler",
+            "scxRusty": "Rust scheduler",
+            "scxCentral": "Central scheduler"
+          },
+          "bpfProgramsPath": "/usr/share/sched_ext/",
+          "loadCommand": "scx_simple or scx_bpfland",
+          "kernelConfig": "CONFIG_SCHED_EXT=y",
+          "libbpf": "1.6.0",
+          "features": [
+            "BPF schedulers",
+            "user-defined policies",
+            "hot-reload"
+          ]
+        }
+      ],
+      "numa": {
+        "balancing": true,
+        "description": "NUMA balancing via kernel",
+        "sysctl": "kernel.numa_balancing=1",
+        "scanPeriod": "kernel.numa_balancing_scan_period_ms=1000",
+        "options": [
+          "numa_balancing=1 enables automatic NUMA placement"
+        ]
+      }
+    },
+    "tenants": {
+      "gold": {
+        "name": "gold",
+        "id": "tenant-gold",
+        "tier": "gold",
+        "priority": 1,
+        "weight": 10000,
+        "cpuWeight": 10000,
+        "cpuMax": "1600000 100000",
+        "cpuMaxCores": 16,
+        "cpuset": "0-15",
+        "cpusetMems": "0",
+        "memoryHigh": "60G",
+        "memoryMax": "64G",
+        "memorySwapMax": "0",
+        "ioWeight": 1000,
+        "ioMax": "rbps=1073741824 wbps=1073741824 riops=10000 wiops=10000",
+        "pidsMax": 8192,
+        "qos": "guaranteed",
+        "numaBalancing": true,
+        "color": "#FFD700",
+        "description": "Gold tier - guaranteed QoS, 16 vCPUs full reservation, 64G",
+        "sla": {
+          "cpuGuarantee": "100% - 16 cores",
+          "memoryGuarantee": "64G no overcommit",
+          "availability": "99.99%",
+          "latencyP99": "<10ms"
+        },
+        "cgroupPath": "/sys/fs/cgroup/omni.slice/tenant-gold",
+        "systemdUnit": "omni-tenant-gold.slice",
+        "vmConfigTomlConfirmation": "identical values present in vm.config.toml [vm.mttg.tenants.gold] - unified here"
+      },
+      "silver": {
+        "name": "silver",
+        "id": "tenant-silver",
+        "tier": "silver",
+        "priority": 2,
+        "weight": 5000,
+        "cpuWeight": 5000,
+        "cpuMax": "800000 100000",
+        "cpuMaxCores": 8,
+        "cpuset": "0-7",
+        "cpusetMems": "0",
+        "memoryHigh": "30G",
+        "memoryMax": "32G",
+        "memorySwapMax": "4G",
+        "ioWeight": 500,
+        "ioMax": "rbps=536870912 wbps=536870912 riops=5000 wiops=5000",
+        "pidsMax": 4096,
+        "qos": "burstable",
+        "numaBalancing": true,
+        "color": "#C0C0C0",
+        "description": "Silver tier - burstable QoS, 8 vCPUs baseline with burst to 16, 32G",
+        "sla": {
+          "cpuGuarantee": "50% - 8 cores baseline, burst to 16",
+          "memoryGuarantee": "30G guaranteed, 32G max",
+          "availability": "99.9%",
+          "latencyP99": "<50ms"
+        },
+        "cgroupPath": "/sys/fs/cgroup/omni.slice/tenant-silver",
+        "systemdUnit": "omni-tenant-silver.slice",
+        "vmConfigTomlConfirmation": "identical values present in vm.config.toml [vm.mttg.tenants.silver] - unified here"
+      },
+      "bronze": {
+        "name": "bronze",
+        "id": "tenant-bronze",
+        "tier": "bronze",
+        "priority": 3,
+        "weight": 100,
+        "cpuWeight": 100,
+        "cpuMax": "200000 100000",
+        "cpuMaxCores": 2,
+        "cpuset": "0-3",
+        "cpusetMems": "0",
+        "memoryHigh": "8G",
+        "memoryMax": "16G",
+        "memorySwapMax": "8G",
+        "ioWeight": 100,
+        "ioMax": "rbps=134217728 wbps=134217728 riops=1000 wiops=1000",
+        "pidsMax": 1024,
+        "qos": "besteffort",
+        "numaBalancing": false,
+        "color": "#CD7F32",
+        "description": "Bronze tier - besteffort, 2 vCPUs opportunistic, 16G max",
+        "sla": {
+          "cpuGuarantee": "0% best-effort - 2 cores opportunistic",
+          "memoryGuarantee": "8G soft, 16G hard limit",
+          "availability": "99.0%",
+          "latencyP99": "best-effort"
+        },
+        "cgroupPath": "/sys/fs/cgroup/omni.slice/tenant-bronze",
+        "systemdUnit": "omni-tenant-bronze.slice",
+        "vmConfigTomlConfirmation": "identical values present in vm.config.toml [vm.mttg.tenants.bronze] - unified here"
+      },
+      "envelope": {
+        "description": "Multi-tenant resource pools gold/silver/bronze with weights and QoS",
+        "count": 3,
+        "isolation": "cgroup v2 per tenant"
+      }
+    },
+    "qosClasses": {
+      "count": 4,
+      "description": "4 QoS classes - guaranteed/burstable/besteffort/idle mapped to cpu.weight and policies",
+      "classes": [
+        {
+          "name": "guaranteed",
+          "priority": 1,
+          "cpuWeight": 10000,
+          "cpuWeightNice": -10,
+          "cpuGuarantee": "100%",
+          "cpuMax": "1600000 100000",
+          "description": "Guaranteed QoS: full CPU reservation, no overcommit, high-priority IO, reserved memory",
+          "memoryPolicy": "no-overcommit",
+          "ioPolicy": "high-priority",
+          "ioWeight": 1000,
+          "memoryHigh": "60G",
+          "memoryMax": "64G",
+          "pidsMax": 8192,
+          "behavior": "Guaranteed CPU, memory protection, never throttled below guarantee",
+          "useCase": "Production critical workloads, databases, latency-sensitive",
+          "exampleTenant": "gold",
+          "cgroupAnnotations": {
+            "cpu.weight": 10000,
+            "cpu.max": "1600000 100000",
+            "memory.high": "60G",
+            "memory.max": "64G",
+            "io.weight": 1000,
+            "pids.max": 8192,
+            "cpu.idle": 0
+          }
+        },
+        {
+          "name": "burstable",
+          "priority": 2,
+          "cpuWeight": 5000,
+          "cpuWeightNice": -5,
+          "cpuGuarantee": "50%",
+          "cpuMax": "800000 100000",
+          "description": "Burstable: baseline 50% CPU with burst to 100%, bounded memory overcommit",
+          "memoryPolicy": "bounded-overcommit",
+          "ioPolicy": "normal",
+          "ioWeight": 500,
+          "memoryHigh": "30G",
+          "memoryMax": "32G",
+          "pidsMax": 4096,
+          "behavior": "Baseline guarantee plus burst capability via cpu.max burst",
+          "useCase": "General production, web services which need burst",
+          "exampleTenant": "silver",
+          "cgroupAnnotations": {
+            "cpu.weight": 5000,
+            "cpu.max": "800000 100000 burst 1600000",
+            "memory.high": "30G",
+            "memory.max": "32G",
+            "io.weight": 500,
+            "pids.max": 4096
+          }
+        },
+        {
+          "name": "besteffort",
+          "priority": 3,
+          "cpuWeight": 100,
+          "cpuWeightNice": 0,
+          "cpuGuarantee": "0%",
+          "cpuMax": "200000 100000",
+          "description": "Best-effort: opportunistic scheduling, full overcommit allowed, lowest guarantee",
+          "memoryPolicy": "overcommit",
+          "ioPolicy": "low-priority",
+          "ioWeight": 100,
+          "memoryHigh": "8G",
+          "memoryMax": "16G",
+          "pidsMax": 1024,
+          "behavior": "Only runs when spare capacity exists, first to be reclaimed",
+          "useCase": "Batch jobs, dev environments, non-critical",
+          "exampleTenant": "bronze",
+          "cgroupAnnotations": {
+            "cpu.weight": 100,
+            "cpu.max": "200000 100000",
+            "memory.high": "8G",
+            "memory.max": "16G",
+            "io.weight": 100,
+            "pids.max": 1024
+          }
+        },
+        {
+          "name": "idle",
+          "priority": 4,
+          "cpuWeight": 1,
+          "cpuWeightNice": 19,
+          "cpuGuarantee": "0%",
+          "cpuMax": "50000 100000",
+          "description": "Idle: cpu.idle=1, lowest priority, only when system fully idle, first reclaim",
+          "memoryPolicy": "reclaim-first",
+          "ioPolicy": "idle",
+          "ioWeight": 1,
+          "memoryHigh": "2G",
+          "memoryMax": "4G",
+          "pidsMax": 256,
+          "behavior": "cpu.idle=1, runs ONLY when no other cgroup wants CPU",
+          "useCase": "Background cleanup, idle batch, scavenger workloads",
+          "exampleTenant": "idle-pool",
+          "cgroupAnnotations": {
+            "cpu.weight": 1,
+            "cpu.idle": 1,
+            "cpu.max": "50000 100000",
+            "memory.high": "2G",
+            "memory.max": "4G",
+            "io.weight": 1,
+            "pids.max": 256
+          }
+        }
+      ]
+    },
+    "transcode": {
+      "ffmpeg": {
+        "version": "7.1.1",
+        "releaseDate": "2025-05-11",
+        "buildConfig": "--enable-gpl --enable-nonfree --enable-cuda --enable-cuvid --enable-nvenc --enable-cuda-llvm --enable-libsvtav1 --enable-libvvenc --enable-libvmaf --enable-libnpp --enable-nvdec --enable-ffnvcodec --enable-vulkan",
+        "cudaSdk": "12.9",
+        "ffnvcodec": "13.0.19",
+        "driverMinimum": "570.144",
+        "hardwareAccel": [
+          "cuda",
+          "vdpau",
+          "vulkan",
+          "qsv_stub_disabled"
+        ],
+        "libPriority": [
+          "libsvtav1",
+          "hevc_nvenc_blackwell",
+          "av1_nvenc_blackwell",
+          "libvvenc",
+          "h264_nvenc"
+        ]
+      },
+      "nvenc": {
+        "generation": "8th Gen",
+        "architecture": "blackwell",
+        "chipList": [
+          "gb202",
+          "gb203",
+          "gb100",
+          "gb200",
+          "rtx pro 6000"
+        ],
+        "sdkVersion": "13.0.19",
+        "capabilities": [
+          "av1_444_10bit",
+          "hevc_444_10bit",
+          "h264_444",
+          "av1_bframes",
+          "hevc_bframes_refmode2",
+          "split-frame-8k60",
+          "temporal_filter_8k"
+        ],
+        "encoderInstancesRtx5090": 7,
+        "encoderInstancesPro6000": 7,
+        "decoderInstances": 7,
+        "maxResolution": "8192x8192",
+        "maxFps8k": 60,
+        "hdrSupport": [
+          "hdr10",
+          "hdr10plus",
+          "dolbyvision_8.4_ll",
+          "hlg"
+        ],
+        "rateControl": [
+          "cbr",
+          "vbr",
+          "cq",
+          "constqp",
+          "cbr_hq",
+          "vbr_hq",
+          "cqp",
+          "icq"
+        ],
+        "lowLatency": [
+          "ultra_low",
+          "low",
+          "high_quality"
+        ],
+        "qualityPreset": "p7"
+      },
+      "codecs": {
+        "supported": [
+          "h264",
+          "hevc",
+          "av1",
+          "svt-av1",
+          "vvc",
+          "prores",
+          "dnxhr"
+        ],
+        "h264": {
+          "encoder": "h264_nvenc",
+          "decoder": "h264_cuvid",
+          "profile": "high444",
+          "pixFmt": "yuv444p10le",
+          "presetDefault": "p7",
+          "tier": "legacy"
+        },
+        "hevc": {
+          "encoder": "hevc_nvenc",
+          "decoder": "hevc_cuvid",
+          "profile": "main10",
+          "pixFmt": "yuv420p10le",
+          "presetDefault": "p7",
+          "bframes": 4,
+          "tier": "mezzanine"
+        },
+        "av1": {
+          "encoder": "av1_nvenc",
+          "decoder": "av1_cuvid",
+          "profile": "main",
+          "pixFmt": "yuv420p10le",
+          "presetDefault": "p7",
+          "enableBframes": true,
+          "tier": "distribution"
+        },
+        "svtav1": {
+          "version": "2.3.0",
+          "encoder": "libsvtav1",
+          "encoderAlt": "av1_nvenc",
+          "presetRange": "0-13",
+          "presetDefault": 6,
+          "presetFast1080pHls": 8,
+          "presetQuality4k": 4,
+          "crfRange": "20-55",
+          "crfDefault": 33,
+          "keyint1080p": 72,
+          "tune": "subjective, psnr, ssim, vmaf",
+          "usage": "cpu fallback + high quality vod when nvenc saturated",
+          "installVia": "native apt + pipelinememorypassage.ts"
+        },
+        "vvc": {
+          "versionVvenc": "1.12.0",
+          "versionVvdec": "3.0.0",
+          "encoder": "libvvenc",
+          "decoder": "vvdec",
+          "preset": "medium",
+          "tier": "archival_future",
+          "resolutions": [
+            "8k",
+            "4k",
+            "1080p"
+          ],
+          "main10": true,
+          "hdr10": true,
+          "maxGop": 64,
+          "note": "experimental mezzanine for film8k archival, 40% bitrate saving vs hevc reference"
+        }
+      },
+      "pipelines": {
+        "active": [
+          "hls1080p",
+          "creator4kav1",
+          "film8kmezzanine"
+        ],
+        "defaultPipeline": "hls1080p",
+        "errorPolicy": "retry_3 + fallback_cpu_svtav1",
+        "hls1080p": {
+          "name": "hls1080p",
+          "description": "adaptive hls ladder 1080p->144p with blackwell nvenc p5 balanced",
+          "vcpusRequired": 4,
+          "ramMbRequired": 2048,
+          "vramMbRequired": 2048,
+          "ffmpegCmdFragment": "-hwaccel cuda -hwaccel_output_format cuda -i {input} -c:v h264_nvenc -preset p5 -rc vbr_hq -cq 23 -multipass qres -b:v 5M -maxrate 6M -g 48 -c:a aac -b:a 128k -hls_time 4 -hls_playlist_type vod",
+          "ladder": [
+            {
+              "width": 1920,
+              "height": 1080,
+              "bitrate": "5000k",
+              "codec": "h264_nvenc"
+            },
+            {
+              "width": 1280,
+              "height": 720,
+              "bitrate": "2800k",
+              "codec": "h264_nvenc"
+            },
+            {
+              "width": 854,
+              "height": 480,
+              "bitrate": "1400k",
+              "codec": "h264_nvenc"
+            },
+            {
+              "width": 640,
+              "height": 360,
+              "bitrate": "800k",
+              "codec": "h264_nvenc"
+            },
+            {
+              "width": 256,
+              "height": 144,
+              "bitrate": "300k",
+              "codec": "h264_nvenc"
+            }
+          ],
+          "segmentDuration": 4,
+          "targetLatency": "low",
+          "gpuProfile": "any blackwell >= 8GB"
+        },
+        "creator4kav1": {
+          "name": "creator4kav1",
+          "description": "creator 4k av1 hdr10 10bit nvenc p7 quality + svt-av1 fallback",
+          "hardwareAnchor": "rtx 5090",
+          "vcpusRequired": 32,
+          "ramMbRequired": 65536,
+          "vramMbRequired": 23552,
+          "ffmpegCmdFragment": "-hwaccel cuda -hwaccel_output_format cuda -i {input} -c:v av1_nvenc -preset p7 -tune hq -rc vbr_hq -cq 28 -b:v 12M -maxrate 15M -profile:v main -pix_fmt p010le -multipass fullres -2pass 1 -g 120 -colorspace bt2020nc -color_trc smpte2084 -color_primaries bt2020 -c:a libopus -b:a 160k",
+          "codecPrimary": "av1_nvenc",
+          "codecFallback": "libsvtav1",
+          "resolution": "3840x2160",
+          "fps": [
+            24,
+            30,
+            60
+          ],
+          "hdr": "hdr10",
+          "tenBit": true,
+          "bframesEnabled": true,
+          "gpuRequired": "rtx5090 0.5 share",
+          "vmafTarget": 93,
+          "pipelineMemory": "pipelinememorypassage.ts",
+          "referenceBoard": "boards.json rtx5090 entry"
+        },
+        "film8kmezzanine": {
+          "name": "film8kmezzanine",
+          "description": "film8k mezzanine 8192x4320 prores/vvc archive tier on pro 6000 96GB",
+          "hardwareAnchor": "rtx pro 6000 workstation 96GB",
+          "vcpusRequired": 96,
+          "ramMbRequired": 196608,
+          "vramMbRequired": 98304,
+          "ramMinFor8k": 98304,
+          "vramOptimal": 98304,
+          "ffmpegCmdFragmentPrimary": "-hwaccel cuda -i {input} -c:v hevc_nvenc -preset p7 -rc constqp -qp 18 -profile:v main10 -pix_fmt p010le -g 1 -c:a pcm_s24le",
+          "ffmpegCmdFragmentVvc": "-i {input} -c:v libvvenc -preset medium -qp 22 -tier high -profile main_10 -g 32 -vvenc_params highbitrate",
+          "codecPrimary": "hevc_nvenc",
+          "codecMezzanine": "prores_ks",
+          "codecFuture": "libvvenc",
+          "resolution": "8192x4320",
+          "fps": 24,
+          "colorspace": "bt2020nc",
+          "pixFmtMezzanine": "yuv444p12le",
+          "storageTier": "mezzanine",
+          "gpuRequired": "pro6000 full or pro6000 96GB unified memory",
+          "temporalIsolation": true,
+          "maxConcurrentJobs": 1,
+          "note": "observer enforces dedicated node when vram > 96GB to avoid time-slice jitter"
+        }
+      }
+    },
+    "hardware": {
+      "nvidia": {
+        "rtx5090": {
+          "model": "geforce rtx 5090",
+          "architecture": "blackwell gb202",
+          "vramGb": 32,
+          "vramActualMb": 32768,
+          "vramType": "gddr7",
+          "bus": "pcie 5.0 x16",
+          "cudaCores": 21760,
+          "tensorGen": "5th",
+          "rtGen": "4th",
+          "nvencGen": "8th gen",
+          "nvencCount": 3,
+          "nvdecCount": 2,
+          "tdpW": 575,
+          "powerConnector": "12v-2x6 600W",
+          "displayport": "2.1b",
+          "driverCurrent": "570.144",
+          "releaseDate": "2025-01-30",
+          "msrpUsd": 1999,
+          "saddleProfile": "creator 32/65536/23552",
+          "compatiblePipeline": "creator4kav1"
+        },
+        "pro6000": {
+          "model": "rtx pro 6000 workstation edition",
+          "architecture": "blackwell gb202 ws",
+          "formerName": "rtx 6000 ada successor",
+          "vramGb": 96,
+          "vramActualMb": 98304,
+          "vramType": "gddr7 ecc",
+          "bus": "pcie 5.0 x16",
+          "cudaCores": 24064,
+          "tensorGen": "5th",
+          "rtGen": "4th",
+          "nvencGen": "8th gen 2x concurrent",
+          "nvdecGen": "6th gen",
+          "nvencCount": 3,
+          "nvdecCount": 4,
+          "tdpW": 600,
+          "powerConnector": "12v-2x6",
+          "ecc": true,
+          "driverCurrent": "570.144",
+          "releaseDate": "2025-04-15",
+          "msrpUsd": 8435,
+          "saddleProfile": "ml 192/262144/98304 and film8k mezzanine 96GB",
+          "compatiblePipeline": "film8kmezzanine",
+          "migEnabled": false,
+          "vGPUSupported": true,
+          "unifiedMemory": "96GB gddr7 + host unified via nvlink-c2c on gb200"
+        }
+      }
+    },
+    "scheduling": {
+      "scheduler": "cfs+eevdf+time-sliced-nvenc",
+      "timeSliceUs": 5000,
+      "burstSliceUs": 10000,
+      "fairnessQuantum": 200,
+      "jitterToleranceUs": 100,
+      "temporalIsolation": true,
+      "maxTenants": 128,
+      "overcommitPolicy": "conservative",
+      "qosWeights": {
+        "gold": 1024,
+        "silver": 512,
+        "bronze": 128,
+        "platinum": 2048
+      },
+      "latencyBoost": 2.0,
+      "deadlineScheduler": true,
+      "sliceAccounting": true,
+      "preemption": true
+    },
+    "memory": {
+      "model": "pipelinememorypassage.ts",
+      "implementation": "src pipeline memory passage with passage.config channel",
+      "priorityInternal": true,
+      "pageSize": "2MB hugepages",
+      "numaBalancing": true,
+      "eviction": "lru + qos aware",
+      "cacheTier": [
+        "vram",
+        "ram",
+        "virtiofs"
+      ]
+    },
+    "dockerIntegration": {
+      "cgroupDriver": "systemd",
+      "engineVersion": "29.7.2",
+      "integration": "Docker containers run inside MTTG cgroups for unified accounting",
+      "dockerCgroupParent": "omni.slice",
+      "exampleDaemonJson": "{ \"cgroup-parent\": \"omni.slice\", \"exec-opts\": [\"native.cgroupdriver=systemd\"] }"
+    },
+    "monitoringOmni": {
+      "cpuStat": "/sys/fs/cgroup/omni.slice/*/cpu.stat",
+      "memoryCurrent": "/sys/fs/cgroup/omni.slice/*/memory.current",
+      "ioStat": "/sys/fs/cgroup/omni.slice/*/io.stat",
+      "pidsCurrent": "/sys/fs/cgroup/omni.slice/*/pids.current",
+      "prometheusExporter": "cgroups_exporter 1.6.0",
+      "grafanaDashboard": "MTTG cgroups v2 dashboard"
+    },
+    "observability": {
+      "metricsPort": 9092,
+      "tracing": "otlp",
+      "logLevel": "info",
+      "dashboards": [
+        "grafana mttg scheduler",
+        "nvidia dcgm",
+        "ffmpeg transcode throughput"
+      ],
+      "exportPath": "/var/log/mttg/metrics.jsonl",
+      "pprofEnabled": true,
+      "vmafEnabled": true
+    },
+    "ui": {
+      "touchTargetPx": 44,
+      "compliantWith": "wcag 2.2 aa + apple hmi 44pt",
+      "scaleFactor": 1.0,
+      "observerNote": "third person observer validates 44px min tap target in renderer",
+      "components": [
+        "pipeline selector",
+        "resource slider",
+        "preset dropdown",
+        "gpu monitor"
+      ]
+    },
+    "modes": {
+      "modes": [
+        "transcode-h264",
+        "transcode-hevc",
+        "transcode-av1-nvenc",
+        "transcode-svtav1-cpu",
+        "transcode-vvc",
+        "mezzanine-prores",
+        "mezzanine-dnxhr",
+        "pipeline-hls1080p",
+        "pipeline-creator4kav1",
+        "pipeline-film8k",
+        "resource-tiny",
+        "resource-oddprime",
+        "resource-creator",
+        "resource-ml",
+        "resource-hyperscale",
+        "gpu-rtx5090",
+        "gpu-pro6000-96gb",
+        "gpu-b200-192gb",
+        "gpu-gb200-super",
+        "scheduling-cfs-eevdf",
+        "errorcatcher-circuit",
+        "ui-44px-observer",
+        "forge-mirror-cuda",
+        "forge-mirror-ffmpeg",
+        "vm-qemu-kvm",
+        "docker-nvidia-runtime",
+        "passage-protocol",
+        "memory-passage",
+        "vram-management",
+        "vcpu-scheduling",
+        "benchmark-vmaf"
+      ],
+      "maxPerFile": 20,
+      "groupingRule": "20-25 contexts per file, logic grouped by correlated category",
+      "subagentsGrouped": true,
+      "maxTasksPerGroup": 10
+    },
+    "forge": {
+      "mirrors": [
+        "https://registry.saddle.dev/ffmpeg",
+        "https://registry.saddle.dev/nvidia",
+        "https://registry.saddle.dev/svtav1"
+      ],
+      "rootConfigFixed": true,
+      "rootDirectFiles": [
+        "mttg.config",
+        "vm.config",
+        "gpu.config",
+        "passage.config",
+        "qemu.config",
+        "docker.config",
+        "boards.json",
+        "cores.json",
+        "processors.json",
+        "gpus.json",
+        "vcpus.json",
+        "vram.json"
+      ],
+      "modeFolders": [
+        "saddle-modes-ffmpeg",
+        "saddle-modes-gpu",
+        "saddle-modes-pipeline"
+      ],
+      "registryAuth": "ecr + ghcr mirror"
+    },
+    "validation": {
+      "validationDate": "2026-08-22",
+      "examplesValidated": [
+        {
+          "name": "tiny",
+          "vcpu": 1,
+          "ramMb": 512,
+          "vramMb": 1024
+        },
+        {
+          "name": "oddprime",
+          "vcpu": 37,
+          "ramMb": 7919,
+          "vramMb": 7183
+        },
+        {
+          "name": "creator",
+          "vcpu": 32,
+          "ramMb": 65536,
+          "vramMb": 23552
+        },
+        {
+          "name": "ml",
+          "vcpu": 192,
+          "ramMb": 262144,
+          "vramMb": 98304
+        },
+        {
+          "name": "hyperscale",
+          "vcpu": 1024,
+          "ramMb": 2097152,
+          "vramMb": 196608
+        }
+      ],
+      "pipelinesValidated": [
+        "hls1080p",
+        "creator4kav1 rtx 5090",
+        "film8k mezzanine 96GB pro 6000"
+      ],
+      "versionsVerified": [
+        "ffmpeg 7.1.1",
+        "nvenc blackwell 8th gen sdk 13.0.19",
+        "svt-av1 2.3.0",
+        "vvenc 1.12.0 vvdec 3.0.0",
+        "node 26.7.0 current",
+        "typescript 7.0.2",
+        "python 3.14.7",
+        "docker 29.7.2",
+        "qemu 11.1.0",
+        "github actions checkout@v7.0.1 setup-node@v7.0.0 setup-python@v7.0.0"
+      ],
+      "thirdPersonObserver": "the observer confirms compliance with v6 skill architecture root-first flat 44px errorcatcher"
+    },
+    "errorcatcher": {
+      "enabled": true,
+      "mode": "observer-catcher + circuit-breaker",
+      "catchList": [
+        "nvenc init failure",
+        "cuda out of memory",
+        "svt-av1 segfault fallback",
+        "vvenc gop overrun",
+        "qemu vfio reset",
+        "docker cdi spec missing",
+        "vram allocation denied",
+        "ffmpeg filter graph invalid"
+      ],
+      "fallbackChain": [
+        "retry cuda",
+        "fallback svt-av1 cpu",
+        "fallback libx264",
+        "emit error json"
+      ],
+      "logSink": "stderr + otlp trace",
+      "metricsCounter": "mttg_errors_total",
+      "touchFile": "/tmp/mttg_error.json"
+    },
+    "omniMeta": {
+      "version": "5.0.0",
+      "generated": "2026-08-22T00:00:00Z",
+      "engine": "mttg",
+      "kernelStable": "7.1.9",
+      "kernelLts": "6.18.45",
+      "qemuVersion": "11.1.0",
+      "libvirtVersion": "12.5.0",
+      "dockerVersion": "29.7.2",
+      "nodeLts": "24.19.0",
+      "nodeCurrent": "26.7.0",
+      "typescript": "7.0.2",
+      "runner": "2.336.0",
+      "description": "Multi-Tenant Task Groups - cgroups v2 based resource isolation and QoS"
+    },
+    "omniToolchain": {
+      "kernelStable": "7.1.9",
+      "kernelLts": "6.18.45",
+      "qemu": "11.1.0",
+      "libvirt": "12.5.0",
+      "docker": "29.7.2",
+      "buildx": "0.36.0",
+      "compose": "5.3.0",
+      "nodeLts": "24.19.0",
+      "nodeCurrent": "26.7.0",
+      "typescript": "7.0.2",
+      "runner": "2.336.0",
+      "checkout": "v6",
+      "setupNode": "v6",
+      "libbpf": "1.6.0",
+      "bpftool": "7.5.0",
+      "schedExt": "bp-1.2.0",
+      "bore": "6.12.15-bore"
+    },
+    "pipeline": {
+      "description": "The 24-stage GPU-accelerated transcode pipeline of the pool pipelinememorypassage family. The stages are media/transcode domain and live canonically in media.ts (stagecatalog + stageorderv5 for the alternate v5 ordering provenance); this section keeps only the MTTG scheduling policy that drives them.",
+      "implementation": "media.ts (mediapipeline + createoptimal + buildffmpegcommand + passagesecurechannel)",
+      "stageCount": 24,
+      "stageNames": [
+        "01_ingest_audit",
+        "02_probe_ffprobe71",
+        "03_tieredmemory_reserve",
+        "04_hugepage_alloc_2m1g",
+        "05_zram_lzorle_zstd",
+        "06_cxl_map_v2_v3",
+        "07_vcpu_pin_ccd_x3d",
+        "08_hwaccel_detect_blackwell",
+        "09_hwupload_cuda",
+        "10_deinterlace_bwdif_cuda",
+        "11_scale_cuda_npp",
+        "12_tonemap_bt2020_cuda",
+        "13_denoise_cuda",
+        "14_color_mgmt",
+        "15_nvenc_blackwell_encode",
+        "16_qsv_fallback",
+        "17_audio_transcode",
+        "18_subtitle_burn",
+        "19_mux_container",
+        "20_passage_message_vsock",
+        "21_qemu_balloon_notify",
+        "22_tiered_reclaim",
+        "23_mttg_slice_report",
+        "24_artifact_gc_finalize"
+      ],
+      "stageOrderingProvenance": {
+        "v6": "pipelinememorypassage.ts — memory stages 03-07 precede GPU work; CCD0 V-Cache carries the video filter chain",
+        "v5": "src_pipeline_memory_passage.ts (src_mttg_pipeline) — demux/decode walk with sharpen, crop_pad, overlay_logo, thumbnail and upload_egress kept in stageorderv5"
+      },
+      "policy": {
+        "name": "create_optimal",
+        "source": "pool:src_virtualization_core.cpp EncodingOptimizationManager::create_optimal",
+        "mediaTsRef": "media.ts createoptimal()",
+        "encoderSelection": [
+          "AV1 at width>=3840 and height>=2160 forces the Blackwell dual NVENC encoder (best AV1 quality of 2026)",
+          "H264 ultra-low-latency (cbr_low_latency mode) prefers Intel QuickSync",
+          "AMD hosts prefer AMF for 1080p power efficiency",
+          "no hardware match falls back to software x265 4.1 + SVT-AV1 (max 32 instances)"
+        ],
+        "presetRecommendation": {
+          "ultraLowLatency": "p1",
+          "lowLatency": "p2",
+          "live": "p3",
+          "vodAv1": "p5",
+          "vodHevc": "p6",
+          "default": "p4"
+        },
+        "instanceRecommendation": "pixel-count throttle: base 5 (av1) / 8 (nvenc other) / 6 (qsv-amf) divided by megapixels/2, floor 1",
+        "failFast": "first non-recoverable stage failure stops the walk; recoverable failures continue when mttg fail_fast=false",
+        "skipRules": {
+          "10DeinterlaceBwdifCuda": "skip when probe.interlaced is false",
+          "12TonemapBt2020Cuda": "skip when not (probe.hdr and job.tonemap)",
+          "13DenoiseCuda": "skip when mode lacks denoise/hqdn",
+          "16QsvFallback": "skip when a hardware backend won the create_optimal policy",
+          "18SubtitleBurn": "skip when no subtitle path"
+        }
+      },
+      "stage20PassageContract": {
+        "transport": "vsock+virtio-serial",
+        "encryption": "chacha20-poly1305",
+        "auth": "ed25519",
+        "mtu": 65536,
+        "control": "vsock://2:1024",
+        "implementation": "media.ts passagesecurechannel (seal/open over the RFC 8439 AEAD of security.ts)"
+      },
+      "mergedFrom": [
+        "pool:pipelinememorypassage.ts [S6 v6 — 24 stages + policy, UNIQUE]",
+        "pool:src_pipeline_memory_passage.ts [V5 — stage ordering + skip rules]",
+        "pool:src_virtualization_core.cpp [create_optimal encoder policy]"
+      ]
+    }
+  },
+  "mttcg": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "summary": {
+      "what": "MTTCG runs each vCPU on its own host thread, each executing translated code from a shared translation block cache.",
+      "oneLine": "1 vCPU = 1 host pthread executing TCG-translated guest code.",
+      "since": "QEMU 2.8 (2016); default for supported host/guest pairs since QEMU 3.0",
+      "relevance": "the entire VHE CI strategy on GitHub-hosted runners (no /dev/kvm) rests on MTTCG"
+    },
+    "architecture": {
+      "perVcpuThread": {
+        "description": "QEMU spawns one QEMUThread per vCPU; each thread runs its own TCG translator loop and executes translated host code for that vCPU.",
+        "threadNaming": "vCPU threads appear as qemu-system-x86_64 processes/threads in /proc/<pid>/task; map via QMP query-cpus-fast",
+        "exit": "vCPU hot-unplug parks the thread (cpu->exit_request)"
+      },
+      "translationBlockCache": {
+        "description": "Translated guest code (TranslationBlocks) lives in one shared code buffer sized by tb-size (MiB).",
+        "sizeFlag": "-accel tcg,tb-size=<MiB> (512-1024 recommended for builds)",
+        "flush": "cache full triggers a full flush and retranslation - larger tb-size reduces flush frequency on big code footprints",
+        "shared": "all vCPU threads share the cache; a block translated by vCPU 0 is reused by vCPU 1"
+      },
+      "qht": {
+        "name": "QEMU Hash Table (QHT)",
+        "description": "lockless (RCU-protected) hash table mapping guest PC -> TranslationBlock; readers scale without contention on the lookup fast path",
+        "source": "util/qht.c in the QEMU tree"
+      },
+      "tbInvalidation": {
+        "description": "when guest code modifies itself or memory mappings change, TBs must be invalidated across all vCPU threads; performed via RCU lists + tb_lock coordination",
+        "cost": "self-modifying-code-heavy workloads (JITs inside the guest, e.g. V8/CPython JIT) suffer invalidation storms - expect lower speedups"
+      },
+      "memoryModelRule": {
+        "description": "MTTCG is enabled only when the guest memory model is compatible with the host memory model (strongly-ordered guest on weakly-ordered host requires barriers that TCG cannot provide cheaply).",
+        "x8664OnX8664": "allowed and DEFAULT",
+        "aarch64OnX8664": "allowed (weak-on-strong)",
+        "x8664OnAarch64": "not allowed - single-threaded TCG fallback",
+        "check": "QEMU prints 'MTTCG is enabled' / uses thread=multi automatically; force with -accel tcg,thread=multi"
+      }
+    },
+    "enablement": {
+      "flagRecommended": "-accel tcg,thread=multi",
+      "defaultBehavior": "thread=multi is chosen automatically for supported pairs (x86_64 guest on x86_64 host)",
+      "forcesSingleThread": [
+        "-icount (instruction counting / deterministic virtual time / record & replay) - MTTCG is incompatible with icount determinism",
+        "cross-arch memory-model mismatch (e.g. x86_64 guest on weakly ordered ARM host)",
+        "explicit -accel tcg,thread=single"
+      ],
+      "verifyInsideProcess": "query the accelerator with QMP query-accels or observe the count of vCPU threads: ps -T -p <qemu-pid> | grep -c qemu-system"
+    },
+    "scalingTo192Vcpus": {
+      "epyc9965Identity": "192 vCPU VM = 192 host threads (MTTCG), plus 1 main loop thread + async worker threads (AIO, vhost, etc.)",
+      "fullSmt2Identity": "384 vCPUs (EPYC 9965 with SMT2) = 384 host threads - only sensible on >= 96-core hosts",
+      "oversubscriptionGuidance": [
+        "vCPUs <= host logical CPUs: full parallel translation and execution",
+        "2x oversubscription: acceptable for I/O-bound sandboxes (edge profiles), CPU-bound builds degrade linearly",
+        ">=4x oversubscription: use it only for topology-visible spoofing (lscpu inside guest), not for throughput"
+      ],
+      "hostThreadPlacement": "pin vCPU threads to host cores with taskset -pc <hostcpu> <tid> or cgroup cpuset (docker.json cpuset) to avoid migration cost",
+      "githubRunnerReality": "ubuntu-latest provides 4 vCPUs: profiles above 8 vCPus on hosted CI are for identity tests, not throughput (cores.json host_sizing)"
+    },
+    "performanceTuning": {
+      "tbSize": {
+        "small": "128 MiB - dev profiles, fast start",
+        "medium": "512 MiB - build profiles",
+        "large": "1024 MiB - buildfarm/buildfarm-max, LLVM-class builds",
+        "tradeoff": "tb-size is allocated from host RAM per VM process; 1024 MiB x N VMs adds up"
+      },
+      "avoidIcount": "never combine -icount with performance profiles; icount forces single-thread TCG and caps throughput at roughly 1/N of MTTCG on N cores",
+      "jitHeavyGuests": "guest-side JITs (Node V8, PyPy, JVM) trigger TB invalidation storms; prefer running those directly in Docker (docker.json) and use QEMU only for topology/OS-level identities",
+      "hostPinning": "taskset QEMU as a whole (taskset -c 0-191 qemu-system-x86_64 ...) so the scheduler cannot place 192 threads on 8 cores with cache thrash",
+      "memoryBackend": "use memory-backend-ram with prealloc=on for large RAM identities to avoid zero-page faults during boot (-object memory-backend-ram,id=mem0,size=512G,prealloc=on -numa node,memdev=mem0)",
+      "iothread": "add -object iothread,id=io0 and attach virtio-blk (iothread=io0) so disk I/O leaves vCPU threads free",
+      "directKernelBoot": "-kernel/-initrd/-append skips firmware: seconds of boot time saved per VM (qemu.json microvm recipe)"
+    },
+    "benchmarksReference": {
+      "methodology": "relative numbers; absolute speed depends on host and workload mix",
+      "observations": [
+        {
+          "workload": "guest kernel/LLVM build",
+          "mttcgVsStcg": "near-linear scaling up to host core count (e.g. 8 vCPUs on 8 host cores approx 7x vs thread=single)"
+        },
+        {
+          "workload": "I/O-bound sandbox (npm install, API calls)",
+          "mttcgVsStcg": "2-4x (bottleneck is slirp + disk, not translation)"
+        },
+        {
+          "workload": "single-threaded guest program",
+          "mttcgVsStcg": "1x (one vCPU active; MTTCG adds nothing)"
+        },
+        {
+          "workload": "guest-side JIT compilation",
+          "mttcgVsStcg": "1.5-3x (TB invalidation limits scaling)"
+        }
+      ],
+      "kvmReferencePoint": "KVM is 10-30x faster than MTTCG for CPU-bound guests; MTTCG at 192 vCPUs on matching hardware reaches only a fraction of native speed - plan CI timeouts accordingly (vm.config.json lifecycle.timeout_s)",
+      "microvmBoot": "microvm machine + TCG boots ~4x faster than default PC machine; still ~3x slower than Firecracker (which requires KVM)"
+    },
+    "limitations": [
+      "x86_64 guest on x86_64 host: MTTCG OK (VHE case)",
+      "cross-arch guests (e.g. running aarch64 guest on x86_64 host) fall back to single-threaded TCG where the memory model requires it",
+      "-icount and record/replay force thread=single",
+      "TB invalidation storms from guest self-modifying code (JITs) erode scaling",
+      "MTTCG performance never approaches KVM; it is a portability tool, not a performance tool",
+      "192 vCPU identities spawn 192 host threads - check RLIMIT_NPROC and cgroup pids.max on CI hosts (docker.json pids-limit)"
+    ],
+    "recommendedFlagsMatrix": {
+      "dev": "-accel tcg,thread=multi,tb-size=128",
+      "build": "-accel tcg,thread=multi,tb-size=512",
+      "buildfarm": "-accel tcg,thread=multi,tb-size=1024",
+      "buildfarmMax": "-accel tcg,thread=multi,tb-size=1024 (+ host pinning, prealloc memory backend, iothread for virtio-blk)",
+      "edge": "-accel tcg,thread=multi -machine microvm -kernel ... (boot latency first)",
+      "selfHostedKvm": "-accel kvm -cpu host (MTTCG not used; keep tcg fallback configured)"
+    },
+    "relatedModules": {
+      "qemu.json": "accelerator flags, tb-size guidance, EPYC-v5 model, QMP lifecycle",
+      "cores.json": "vCPU presets -> -smp topology and host thread counts",
+      "passage.json": "KVM availability ladder and CI fallback policy",
+      "vm.config.json": "per-profile accel field (preferred kvm / fallback tcg,thread=multi)"
+    },
+    "sourceRefs": {
+      "file": "tcg-accel-ops-mttcg.c",
+      "functions": [
+        "qemu_thread_create",
+        "mttcg_qemu_thread_new",
+        "tcg_register_thread"
+      ],
+      "queues": "2 * vCPU count",
+      "performance": {
+        "scaling": "near-linear up to 192 vCPUs",
+        "overhead": "<8%"
+      },
+      "compat": {
+        "requires": "TCG",
+        "notWith": "KVM",
+        "host": "any"
+      },
+      "qemuArgs": "--accel tcg,thread=multi",
+      "targetSupportsMttcg": true,
+      "fullConfigRef": "qemu.config#mttcg (accel flags)"
+    }
+  }
+}