feat(schema): declare a host hardware capability, hardware.gpu: intel-quicksync

A ServiceDefinition could not say it needs the host's Intel QuickSync render
device. The schema is `additionalProperties: false`, so there was no authorable
form for it at all, and `apps/` is generated — a hand-edit would be reverted by
the next render.

Adds optional top-level `hardware`, with one optional member `gpu`, an enum
whose only current value is `intel-quicksync` (schema 1.7.0 -> 1.8.0).

The enum is the point. The SD declares WHAT CLASS of device it needs; the
hostPath, the mount and the GID live only in catalog/render.py. Migrating to
the Intel GPU device plugin (`gpu.intel.com/i915` resource requests, no
hostPath) is then a renderer change with zero catalog edits. Letting an SD name
`/dev/dri` directly would look simpler and make that migration a catalog-wide
edit, so both the schema description and the renderer contract say so
explicitly.

When `hardware.gpu == intel-quicksync`, r_deployment emits, on the app
container / pod spec only:

  - a hostPath volume `dri` -> /dev/dri, type DirectoryOrCreate;
  - a read-write volumeMount of it at /dev/dri (VA-API opens the render node
    read-write, so deliberately not readOnly);
  - INTEL_RENDER_GID MERGED into podSecurityContext.supplementalGroups, never
    clobbering what the SD already declares.

`DirectoryOrCreate` is load-bearing. A node that comes back without the render
device (rebuild, BIOS change, driver regression, hardware swap) must degrade
the workload to software transcoding, not fail the mount: apps-wave-0 is
`wait: true` and apps-wave-1 dependsOn it, so a failed hostPath mount stalls
the whole app tier for a feature that is not load-bearing. /dev is tmpfs, so
the empty directory the kubelet creates leaves nothing durable behind. Its cost
— a missing device is silent, and no metric exists to alert on — is recorded in
the contract rather than papered over with an alert that could not fire.

Deliberately NOT emitted: no `privileged: true` (Kyverno restrict-host-
namespaces is Enforce and it is not needed), no nodeSelector (placement is a
separate concern with its own justification), no resource requests (there is no
app-container resource render path).

INTEL_RENDER_GID = 992 is a single named constant carrying its provenance:
measured on all three prod nodes on 2026-09-30, and a *systemd dynamic*
allocation rather than a static GID, so a node rebuild can move it.

No catalog entry uses the field. Re-rendering `--all catalog -o apps` is a zero
diff, which is the proof the change is inert until opted into.

Three self-test cases in the existing check(...) style: the positive, the
negative (an SD without `hardware` gains no volume, no mount, no
securityContext — mirroring the podSecurityContext negative) and the merge case
([44] + 992 -> [44, 992], fsGroup preserved). Note that NO gate stage runs
`render.py --selftest`; they were run by hand and the gap is recorded in the
handoff.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

schemas/renderer-contract.md

@@ -160,6 +160,45 @@ platform must render, and cites the requirement each mapping satisfies. Changing
 - **Requirements:** **R-STATE-01** (rebuild survival), **R-STATE-02** (Longhorn replication),
   **R-STATE-04** (bulk tier). (docs/04)
 
+### `hardware` (`gpu`) — host device capability
+- **The field is INTENT, never MECHANISM.** `hardware.gpu` is an **enum of capability classes**
+  (today: `intel-quicksync`), not a device path, not a hostPath, not a resource request. The
+  ServiceDefinition says *what class of host device this workload needs*; how the platform hands it
+  over is `catalog/render.py`'s business and lives nowhere else. **Do not "simplify" this into a raw
+  `/dev/...` path.** The entire payoff is that migrating from the hostPath mechanism below to the
+  Intel GPU device plugin (`resources.limits: gpu.intel.com/i915`) is a renderer change with **zero**
+  catalog edits and zero re-review of per-service device wiring. Extend the enum for a genuinely
+  different capability class (e.g. `nvidia-nvenc`); never to name a second route to the same one.
+- `gpu: intel-quicksync` → on the **app container / pod spec only** (never a sidecar):
+  1. a **hostPath volume** `dri` → `/dev/dri`, **`type: DirectoryOrCreate`**;
+  2. a **read-write volumeMount** of `dri` at `/dev/dri` on the app container (VA-API opens the
+     render node read-write, so it is deliberately not `readOnly`);
+  3. the host `render` **GID merged into `podSecurityContext.supplementalGroups`** — merged, never
+     clobbered, so an SD that declares its own supplemental groups keeps all of them and gains one.
+     `/dev/dri/renderD128` is `root:render` mode `0660`, so a non-root container needs the group.
+     The GID is the single constant `INTEL_RENDER_GID` in `catalog/render.py` (992, **measured
+     2026-09-30 on all three prod nodes**; it is a *systemd dynamic* allocation, not a static GID,
+     so a node rebuild can move it — re-measure `getent group render` before assuming).
+- **`DirectoryOrCreate` is load-bearing — do not tighten it to `Directory`.** A node that comes back
+  without the render device (rebuild, BIOS change, driver regression, hardware swap) must degrade the
+  workload to **software transcoding**, not fail the mount. `apps-wave-0` is `wait: true` and
+  `apps-wave-1` `dependsOn` it, so a failed hostPath mount stalls the **whole app tier** for the sake
+  of a feature that is not load-bearing. `/dev` is tmpfs, so the empty directory the kubelet creates
+  on such a node leaves nothing durable behind.
+  - **The cost of that choice, stated plainly:** a missing device is **silent**. The workload
+    software-transcodes and nothing reports it. There is no metric to alert on — media apps here
+    render no `metricsEndpoint`, so no ServiceMonitor exists — and an alert that cannot fire is worse
+    than none (see §`observability`'s 2026-09-13 correction). The only proof of hardware transcode is
+    an operator observing it in the application's own dashboard.
+- **Deliberately NOT rendered** from this field: no `privileged: true` (Kyverno
+  `restrict-host-namespaces` is Enforce on app namespaces and would reject it, and the render node
+  does not need it); no `nodeSelector` (placement is a separate concern with its own justification —
+  this field is about the device, not about where the pod lands); no resource requests/limits (there
+  is no app-container resource render path, and inventing one here would be scope creep).
+- Absent ⇒ **nothing at all** is rendered; every service that does not opt in stays byte-identical.
+  Ignored for `kind: vm` — a VM receives devices through KubeVirt's own `domain.devices`.
+- **Requirements:** **R-PLAT-02** (the PaaS provides the host capability; the app declares need).
+
 ### `ingressRoutes[]` (`host` / `port`) — HTTPRoute + Certificate + DNS
 - Each entry renders an **HTTPRoute** attaching `host` → the service `port` on the shared Gateway.
 - TLS: the Gateway terminates with the cert-manager **wildcard `*.home.keithjackson.dev`** certificate
@@ -286,6 +325,11 @@ platform must render, and cites the requirement each mapping satisfies. Changing
    `external-dns.alpha.kubernetes.io/controller: none`, and no `public` service's route carries it.
    Derived from `exposure` alone; enforced on every gate run by
    `conformance/tests/l0-static/internal-services-publish-no-public-dns` (R-DNS-03).
+8. **`hardware` is inert until opted into, and its mechanism is renderer-local.** An SD with no
+   `hardware` key renders no volume, no volumeMount and no `securityContext` — proven by
+   `render.py --selftest`. The `/dev/dri` hostPath, the `DirectoryOrCreate` type and
+   `INTEL_RENDER_GID` appear in `catalog/render.py` and nowhere else, so the capability's
+   implementation can be replaced without touching a single ServiceDefinition.
 
 ## Requirement traceability (contract-level)
 Primary **R-GITOPS-02** (single reviewable object wires every requirement). Field-level: R-NET-01/02