From 39d351ade2e074951f7d371a59a244f05220e009 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:56:31 +0800 Subject: [PATCH] docs: group the workaround registry by type Split the single table into Pins / Workarounds / Known issues / WIP sections so the registry is readable by section instead of scanning a Type column. --- WORKAROUNDS.md | 71 +++++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/WORKAROUNDS.md b/WORKAROUNDS.md index c93a84c8..7c8a6931 100644 --- a/WORKAROUNDS.md +++ b/WORKAROUNDS.md @@ -1,49 +1,62 @@ # Workarounds & known gaps -Temporary workarounds, version pins, carried patches, and known gaps are collected here, each with -the condition under which it can be removed. Review the list periodically so obsolete workarounds -get rolled back instead of lingering. +Temporary workarounds, version pins, carried patches, and known gaps are collected here, grouped by +type, each with the condition under which it can be removed. Review the list periodically so +obsolete workarounds get rolled back instead of lingering. ## How to use - **Adding** — a change that introduces a workaround, pin, carried patch, or known gap adds a row - here in the same PR, with a concrete **removal condition**. + under the matching section below in the same PR, with a concrete **removal condition**. - **Removing** — once the removal condition is met, delete the change and set `Status` to `removed` (mention the ID in the commit), or delete the row. - **Reviewing** — re-evaluate rows whose `Revisit` trigger is due and refresh `Status`. -## Types +## Pins -| Type | Meaning | -| ------------- | --------------------------------------------------------------------------- | -| `patch` | Upstream code carried locally (an overlay, a patch file, or a fork branch). | -| `pin` | A version or revision pinned for a reason that can go away. | -| `workaround` | A setting that works around a bug or a hardware quirk. | -| `known-issue` | A known limitation with no fix yet. | -| `wip` | An unfinished feature or gap. | +A version or revision pinned for a reason that can go away. -## Registry +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------ | +| WA-001 | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | +| WA-002 | `nixpkgs-2505` — `flake.nix`; consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | +| WA-003 | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | +| WA-004 | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | +| WA-005 | `tuios` input — `flake.nix`; `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active | +| WA-006 | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active | +| WA-007 | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active | -| ID | Type | What & where | Why | Removal condition | Added | Revisit | Status | -| ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | -| WA-001 | `pin` | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | -| WA-002 | `pin` | `nixpkgs-2505` — `flake.nix`, consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | -| WA-003 | `pin` | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | -| WA-004 | `pin` | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | -| WA-005 | `pin` | `tuios` input — `flake.nix`, `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active | -| WA-006 | `pin` | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active | -| WA-007 | `pin` | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active | -| WA-008 | `workaround` | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | -| WA-009 | `workaround` | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | -| WA-010 | `workaround` | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | -| WA-011 | `workaround` | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | -| WA-012 | `known-issue` | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | -| WA-013 | `wip` | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active | +## Workarounds + +A setting that works around a bug or a hardware quirk. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | +| WA-008 | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | +| WA-009 | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | +| WA-010 | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | +| WA-011 | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | + +## Known issues + +A known limitation with no fix yet. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | ----- | ---------------- | ------ | +| WA-012 | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | + +## WIP + +An unfinished feature or gap. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------- | --------- | ------ | +| WA-013 | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active | ## Related - Unmerged **nixpkgs** PRs are carried via the `nixpkgs-patched` input and the [`.agents/skills/nixpkgs-patched`](./.agents/skills/nixpkgs-patched/SKILL.md) workflow (that input - currently carries nothing; the `patch` rows above are per-package overlays instead). + currently carries nothing; package-level carries are recorded under `Pins`). - Routine version pins (colmena, agenix, disko, lanzaboote, haumea, home-manager, `nixpkgs-stable`, `nixpkgs-darwin`, …) are the versions in use, not workarounds, so they are not listed here.