test(systemd): pin the arena value instead of accepting a range

Review follow-up. The range check accepted 1, 3 and 4, so a change to 4 --
which hands most of the resident saving back -- passed a test whose whole
purpose is to notice that.

Pinned to the value the unit ships, in one named constant. Raising it is still
a legitimate response to a frame-time regression, but it should be a visible
edit here rather than silent drift, and the failure message says so.

Mutation-checked: changing the unit to 4 now fails.

src/backup_manager.py

@@ -111,12 +111,6 @@ class RestoreOptions:
     """Which sections of a backup should be restored."""
 
     restore_config: bool = True
-    #: Whether to take the backup's display.hardware block as well.
-    #: Off by default: that block describes the panel physically wired to
-    #: *this* device -- its size, chain length, mapping, multiplexing and
-    #: refresh cap. A backup carries the panel of the machine it was taken
-    #: on, and restoring one onto a different rig drives the wrong geometry.
-    restore_hardware: bool = False
     restore_secrets: bool = True
     restore_wifi: bool = True
     restore_fonts: bool = True
@@ -555,72 +549,6 @@ def _copy_file(src: Path, dst: Path) -> None:
         raise
 
 
-_HARDWARE_PATH = ("display", "hardware")
-
-
-def _restore_config_preserving_hardware(src: Path, dst: Path, keep_hardware: bool) -> None:
-    """Copy a backed-up config.json, optionally keeping the local panel block.
-
-    display.hardware describes the panel physically attached to this device:
-    cols, rows, chain_length, hardware_mapping, panel_type, multiplexing and
-    the refresh-rate cap. None of that travels with a configuration -- it is a
-    property of the machine. Restoring a backup taken on a 512x64 rig onto a
-    128x32 one used to overwrite the smaller panel's geometry with the larger
-    one's, which is not a setting the user can see going wrong; the display
-    simply stops being right.
-
-    Falls back to a plain copy when either file cannot be parsed, so a restore
-    never fails because of this.
-    """
-    if not keep_hardware:
-        _copy_file(src, dst)
-        return
-    try:
-        incoming = json.loads(src.read_text(encoding="utf-8"))
-        local = json.loads(dst.read_text(encoding="utf-8")) if dst.exists() else {}
-    except (OSError, ValueError) as exc:
-        logger.warning(
-            "[Backup] Could not merge local panel config (%s); restoring the "
-            "backup's config.json as-is", exc)
-        _copy_file(src, dst)
-        return
-
-    section, key = _HARDWARE_PATH
-    local_hw = (local.get(section) or {}).get(key)
-    if not isinstance(local_hw, dict) or not local_hw:
-        _copy_file(src, dst)
-        return
-
-    if not isinstance(incoming.get(section), dict):
-        incoming[section] = {}
-    incoming_hw = incoming[section].get(key)
-    incoming[section][key] = local_hw
-    if isinstance(incoming_hw, dict) and incoming_hw != local_hw:
-        logger.info(
-            "[Backup] Kept this device's display.hardware; the backup's panel "
-            "was %sx%s chain %s, this one is %sx%s chain %s",
-            incoming_hw.get("cols"), incoming_hw.get("rows"),
-            incoming_hw.get("chain_length"),
-            local_hw.get("cols"), local_hw.get("rows"),
-            local_hw.get("chain_length"))
-
-    # Write the merged result to a scratch file and hand it to _copy_file
-    # rather than renaming it into place here. _copy_file preserves the
-    # destination's mode and owner on purpose -- these config files are
-    # installed root-owned while the web interface that runs a restore is not
-    # root -- and a bare write would have replaced a root-owned config.json
-    # with one owned by the web user at whatever the umask allows.
-    scratch = dst.with_suffix(dst.suffix + ".merged-tmp")
-    try:
-        scratch.write_text(json.dumps(incoming, indent=2) + "\n", encoding="utf-8")
-        _copy_file(scratch, dst)
-    finally:
-        try:
-            scratch.unlink()
-        except OSError:
-            pass
-
-
 def restore_backup(
     zip_path: Path,
     project_root: Path,
@@ -656,9 +584,7 @@ def restore_backup(
         # Main config.
         if options.restore_config and (tmp_dir / _CONFIG_REL).exists():
             try:
-                _restore_config_preserving_hardware(
+                _copy_file(tmp_dir / _CONFIG_REL, project_root / _CONFIG_REL)
-                    tmp_dir / _CONFIG_REL, project_root / _CONFIG_REL,
-                    keep_hardware=not options.restore_hardware)
                 result.restored.append("config")
             except OSError as e:
                 logger.error("[Backup] Failed to restore config.json: %s", e, exc_info=True)

systemd/ledmatrix.service

@@ -8,6 +8,18 @@ Type=simple
 User=root
 WorkingDirectory=__PROJECT_ROOT_DIR__
 Environment=PYTHONDONTWRITEBYTECODE=1
+# glibc gives each allocating thread its own malloc arena, up to 8 x CPU count,
+# and an arena that has grown is never handed back to the OS. This process runs
+# 9 threads on a 3-core Pi, so the ceiling is 24 arenas -- and a rig measured at
+# 1030 MB resident held 23 large anonymous mappings on 64 MB-aligned addresses,
+# 920 MB of them, while the live data it was actually holding (widest scroll
+# strip seen: 35,746 x 64) accounts for roughly 15 MB. That gap is arena bloat,
+# not leaked objects: RSS was flat across repeated sampling, not climbing.
+#
+# Capping the arenas trades a little allocator concurrency for a large amount of
+# resident memory on a device that has neither to spare. 2 is the usual value;
+# raise it if frame times regress.
+Environment=MALLOC_ARENA_MAX=2
 ExecStart=/usr/bin/python3 __PROJECT_ROOT_DIR__/run.py
 # Restart=always, not on-failure: run.py exiting 0 (a clean shutdown path taken
 # for a reason that no longer applies, e.g. a config reload) would otherwise leave

test/test_restore_keeps_panel_hardware.py

@@ -1,104 +0,0 @@
-#!/usr/bin/env python3
-"""A restore must not repoint this device at another machine's panel.
-
-display.hardware describes the panel physically wired to this device -- cols,
-rows, chain_length, hardware_mapping, panel_type, multiplexing, the refresh
-cap. A backup carries the panel of the machine it was taken on. Restoring a
-512x64 rig's backup onto a 128x32 one used to overwrite the smaller panel's
-geometry with the larger one's, and nothing on screen explains why: the
-display just stops being right.
-
-That is not hypothetical. It happened, and the rig it happened to had to be
-reflashed.
-"""
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from src.backup_manager import _restore_config_preserving_hardware  # noqa: E402
-
-BIG = {"display": {"hardware": {"cols": 128, "rows": 64, "chain_length": 4,
-                                "hardware_mapping": "adafruit-hat-pwm"},
-                   "runtime": {"gpio_slowdown": 4}},
-       "timezone": "America/New_York", "some-plugin": {"enabled": True}}
-SMALL = {"display": {"hardware": {"cols": 64, "rows": 32, "chain_length": 2,
-                                  "hardware_mapping": "regular"},
-                     "runtime": {"gpio_slowdown": 2}},
-         "timezone": "UTC"}
-
-
-def _run(tmp, keep):
-    src = tmp / "backup_config.json"; src.write_text(json.dumps(BIG))
-    dst = tmp / "config.json"; dst.write_text(json.dumps(SMALL))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=keep)
-    return json.loads(dst.read_text())
-
-
-def test_local_panel_survives(tmp_path):
-    out = _run(tmp_path, keep=True)
-    hw = out["display"]["hardware"]
-    assert (hw["cols"], hw["rows"], hw["chain_length"]) == (64, 32, 2), (
-        "the restore repointed this device at the backup's panel")
-    assert hw["hardware_mapping"] == "regular", "panel wiring came from the backup"
-
-
-def test_everything_else_is_restored(tmp_path):
-    out = _run(tmp_path, keep=True)
-    assert out["timezone"] == "America/New_York", "config was not restored"
-    assert out["some-plugin"] == {"enabled": True}, "plugin config was not restored"
-    assert out["display"]["runtime"] == {"gpio_slowdown": 4}, (
-        "only display.hardware should be held back")
-
-
-def test_opting_in_takes_the_backups_panel(tmp_path):
-    out = _run(tmp_path, keep=False)
-    hw = out["display"]["hardware"]
-    assert (hw["cols"], hw["rows"], hw["chain_length"]) == (128, 64, 4)
-
-
-def test_a_device_with_no_local_hardware_takes_the_backups(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps({"timezone": "UTC"}))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    out = json.loads(dst.read_text())
-    assert out["display"]["hardware"]["cols"] == 128, (
-        "nothing local to preserve, so the backup's panel should be used")
-
-
-def test_unparseable_local_config_still_restores(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text("{ not json")
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    assert json.loads(dst.read_text())["timezone"] == "America/New_York", (
-        "a restore must never fail because of this merge")
-
-
-def test_the_destination_mode_is_preserved(tmp_path):
-    """config.json is installed with a deliberate mode; a merge must not widen it.
-
-    _copy_file preserves the destination's mode and owner on purpose -- these
-    files are root-owned while the web interface running the restore is not.
-    Writing the merged result directly would have replaced that with whatever
-    the umask allowed.
-    """
-    import os
-    import stat as statmod
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps(SMALL))
-    os.chmod(dst, 0o600)
-
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-
-    mode = statmod.S_IMODE(os.stat(dst).st_mode)
-    assert mode == 0o600, f"restore widened config.json from 0600 to {oct(mode)}"
-    assert json.loads(dst.read_text())["display"]["hardware"]["cols"] == 64
-
-
-def test_no_scratch_file_is_left_behind(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps(SMALL))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    leftovers = [p.name for p in tmp_path.iterdir() if "tmp" in p.name]
-    assert not leftovers, f"scratch files left in place: {leftovers}"

test/test_systemd_malloc_arenas.py

@@ -0,0 +1,95 @@
+"""The display unit must cap glibc's malloc arenas.
+
+glibc hands each allocating thread its own malloc arena, up to 8 x CPU count,
+and an arena that has grown is never returned to the OS. This process runs
+threads for the render loop, the update workers and the background fetchers, so
+on a 3-core Pi the ceiling is 24 arenas.
+
+Measured on a live rig, 2.5 hours in:
+
+    RSS                 1030 MB
+    Private_Dirty        988 MB
+    anonymous mappings > 10 MB     23     (ceiling is 8 x 3 = 24)
+    largest few          104, 79, 66, 63, 63 MB, on 64 MB-aligned addresses
+
+against live data that accounts for perhaps 15 MB -- the widest scroll strip
+observed was 35,746 x 64, about 7 MB as RGB and the same again for its numpy
+mirror. Repeated sampling showed RSS flat between 990 and 1030 MB rather than
+climbing, so this is arena bloat rather than a leak: memory Python has freed
+but glibc is holding per-arena.
+
+The device had 59 MB free at the time.
+
+Capping the arena count trades a little allocator concurrency for that resident
+memory. The render loop is latency-sensitive, so if p99 frame time regresses the
+right response is to raise this rather than remove it.
+"""
+import re
+from pathlib import Path
+
+import pytest
+
+UNIT = (Path(__file__).resolve().parent.parent / "systemd" / "ledmatrix.service")
+
+#: The value the unit is expected to carry. 2 is the usual choice for a
+#: threaded Python process; 1-4 all keep some of the saving, but only one of
+#: them is what this project ships.
+EXPECTED_ARENA_MAX = 2
+
+
+def _environment(unit_text):
+    return dict(
+        line.split("=", 2)[1:3] if line.count("=") >= 2 else (line.split("=", 1)[1], "")
+        for line in unit_text.splitlines()
+        if line.startswith("Environment=")
+    )
+
+
+def test_the_unit_exists():
+    assert UNIT.is_file(), f"{UNIT} is missing"
+
+
+def test_malloc_arena_max_is_capped():
+    env = _environment(UNIT.read_text(encoding="utf-8"))
+    assert "MALLOC_ARENA_MAX" in env, (
+        "the display unit does not cap glibc arenas; on a 3-core Pi the default "
+        "ceiling is 24 and a measured rig held 23 of them, 920 MB"
+    )
+    value = int(env["MALLOC_ARENA_MAX"])
+    # Pinned, not a range. A range let a change to 4 -- which hands most of the
+    # saving back -- pass unnoticed, which was the point of the finding that
+    # prompted this. Raising it is a legitimate response to a frame-time
+    # regression, but it should be a visible edit here rather than a silent
+    # drift, so the number lives in one place and changing it shows up in
+    # review.
+    assert value == EXPECTED_ARENA_MAX, (
+        f"MALLOC_ARENA_MAX={value}, expected {EXPECTED_ARENA_MAX}. If this was "
+        "raised deliberately because frame times regressed, update "
+        "EXPECTED_ARENA_MAX here and say so in the commit."
+    )
+
+
+def test_the_reason_is_recorded_next_to_it():
+    """A bare tuning knob invites removal by whoever meets it next."""
+    text = UNIT.read_text(encoding="utf-8")
+    index = text.index("Environment=MALLOC_ARENA_MAX")
+    preamble = text[:index].splitlines()[-12:]
+    comment = "\n".join(line for line in preamble if line.startswith("#"))
+    assert "arena" in comment.lower(), "no explanation precedes the setting"
+    assert re.search(r"\d", comment), (
+        "the explanation cites no measurement, so a reader cannot tell whether "
+        "it still applies to their hardware"
+    )
+
+
+@pytest.mark.parametrize("unit", ["ledmatrix.service"])
+def test_the_unit_still_parses_as_ini(unit):
+    """systemd will refuse a malformed unit, and the panel stays dark."""
+    import configparser
+
+    path = UNIT.parent / unit
+    parser = configparser.ConfigParser(strict=False)
+    # systemd allows repeated keys; ConfigParser needs them merged, not rejected.
+    parser.read_string(path.read_text(encoding="utf-8"))
+    assert parser.has_section("Service")
+    assert parser.has_option("Service", "ExecStart")