left4me/docs/superpowers/plans/2026-05-10-l4d2-network-shaping.md

# L4D2 Network Shaping & Marking Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship a network-side player-experience baseline alongside the existing host perf baseline: nftables uid-based DSCP-EF + skb-priority marking for srcds UDP, rounding sysctls (`udp_rmem_min`/`wmem_min`, `default_qdisc=fq_codel`, `tcp_congestion_control=bbr`), and CAKE egress shaping via a systemd oneshot driven by an operator-edited env file. Production hosts running `systemd-networkd` consume an equivalent `[CAKE]` section documented in the README.

**Architecture:** Eight ship-ready artifacts under `deploy/files/...`, wired into `deploy-test-server.sh`, asserted in `deploy/tests/test_deploy_artifacts.py`, and documented in `deploy/README.md`. Each artifact is a separate, independently-testable file. The CAKE helper takes an `apply`/`clear` mode argument so the unit's `ExecStart`/`ExecStop` are clean shell calls without escape soup.

**Tech Stack:** sysctl, nftables (`inet` table, output hook, mangle priority), tc-cake, systemd oneshot units, POSIX `/bin/sh` for the helper, pytest substring assertions.

**Spec:** `docs/superpowers/specs/2026-05-10-l4d2-network-shaping-design.md`.

---

## File Structure

**New files (`deploy/files/...`):**
- `usr/local/lib/left4me/nft/left4me-mark.nft` — nftables ruleset, own `inet` table.
- `usr/local/lib/systemd/system/left4me-nft-mark.service` — applies/removes the table.
- `etc/left4me/cake.env` — operator-edited template (deploy preserves edits).
- `usr/local/libexec/left4me/left4me-apply-cake` — POSIX shell helper, `apply`/`clear` modes.
- `usr/local/lib/systemd/system/left4me-cake.service` — runs the helper at network-online, clears on stop.

**Modified files:**
- `deploy/files/etc/sysctl.d/99-left4me.conf` — append four new directives.
- `deploy/deploy-test-server.sh` — add `nftables iproute2` to apt/dnf install lines, copy the new artifacts, conditional cake.env copy, enable the two new units.
- `deploy/README.md` — Network shaping subsection + three new escape hatches (IFB ingress, busy_poll, GRO).
- `deploy/tests/test_deploy_artifacts.py` — add path constants and assertions.

Each task adds (or extends) one artifact and the matching test, ending in a commit. Order matters: sysctl extension first (smallest, isolated), then the nftables pair, then the CAKE pair, then deploy-script wiring (depends on every prior task), then README.

---

### Task 1: Sysctl additions to `99-left4me.conf`

**Files:**
- Modify: `deploy/files/etc/sysctl.d/99-left4me.conf` (append block)
- Modify: `deploy/tests/test_deploy_artifacts.py:199-211` (extend existing `test_sysctl_conf_present_with_perf_settings`)

- [ ] **Step 1: Extend the existing sysctl test with the new lines.**

In `deploy/tests/test_deploy_artifacts.py`, edit `test_sysctl_conf_present_with_perf_settings` to append four lines to the tuple it already iterates:

```python
def test_sysctl_conf_present_with_perf_settings():
    assert SYSCTL_CONF.is_file()
    text = SYSCTL_CONF.read_text()
    for line in (
        "net.core.rmem_max = 8388608",
        "net.core.wmem_max = 8388608",
        "net.core.rmem_default = 524288",
        "net.core.wmem_default = 524288",
        "net.core.netdev_max_backlog = 5000",
        "net.core.netdev_budget = 600",
        "vm.swappiness = 10",
        "net.ipv4.udp_rmem_min = 16384",
        "net.ipv4.udp_wmem_min = 16384",
        "net.core.default_qdisc = fq_codel",
        "net.ipv4.tcp_congestion_control = bbr",
    ):
        assert line in text, f"missing {line!r} in 99-left4me.conf"
```

- [ ] **Step 2: Run the test to verify it fails.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_sysctl_conf_present_with_perf_settings -v
```
Expected: FAIL — `AssertionError: missing 'net.ipv4.udp_rmem_min = 16384' in 99-left4me.conf`.

- [ ] **Step 3: Append the new block to `99-left4me.conf`.**

Open `deploy/files/etc/sysctl.d/99-left4me.conf` and append (after the existing `vm.swappiness = 10` line):

```
# Per-socket UDP buffer floors: protect game-server sockets that don't bump
# their own SO_RCVBUF/SO_SNDBUF when softirq drains lag briefly.
net.ipv4.udp_rmem_min = 16384
net.ipv4.udp_wmem_min = 16384

# Default qdisc for ifaces we don't explicitly shape with CAKE. Debian Trixie
# already defaults to fq_codel; setting it explicitly is belt-and-suspenders
# and survives kernel-default churn.
net.core.default_qdisc = fq_codel

# TCP congestion control: BBR for any bulk TCP egress on the host (admin SSH,
# backups, package fetches, web-app responses) so a long flow does not push
# the bottleneck queue ahead of game UDP. UDP srcds is unaffected.
net.ipv4.tcp_congestion_control = bbr
```

- [ ] **Step 4: Run the test again to verify it passes.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_sysctl_conf_present_with_perf_settings -v
```
Expected: PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/etc/sysctl.d/99-left4me.conf deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): extend sysctls with udp_*_min, fq_codel default, BBR"
```

---

### Task 2: nftables marking file

**Files:**
- Create: `deploy/files/usr/local/lib/left4me/nft/left4me-mark.nft`
- Modify: `deploy/tests/test_deploy_artifacts.py` (add path constant + new test function)

- [ ] **Step 1: Add the path constant and a failing test.**

In `deploy/tests/test_deploy_artifacts.py`, add the constant near the existing path constants block (around line 26, after `DEPLOY_SCRIPT`):

```python
NFT_MARK_FILE = DEPLOY / "files/usr/local/lib/left4me/nft/left4me-mark.nft"
```

Append this test function to the bottom of the file:

```python
def test_nft_mark_file_marks_left4me_udp_with_dscp_ef_and_priority():
    assert NFT_MARK_FILE.is_file()
    text = NFT_MARK_FILE.read_text()

    # Own table in the inet family so it cannot conflict with operator nftables config.
    assert "table inet left4me_mark" in text
    assert "chain mangle_output" in text
    assert "type filter hook output priority mangle" in text

    # Match by uid (every srcds runs as `left4me`) restricted to UDP.
    assert 'meta skuid "left4me"' in text
    assert "meta l4proto udp" in text

    # DSCP EF for both L3 families; in `inet` tables, `ip` only fires on v4
    # and `ip6` only on v6.
    assert "ip dscp set ef" in text
    assert "ip6 dscp set ef" in text

    # skb->priority class 6:0, set inline alongside DSCP.
    assert "meta priority set 0006:0000" in text
```

- [ ] **Step 2: Run the new test and confirm it fails.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_nft_mark_file_marks_left4me_udp_with_dscp_ef_and_priority -v
```
Expected: FAIL — `AssertionError: assert False` on `NFT_MARK_FILE.is_file()`.

- [ ] **Step 3: Create the directory and write the nftables file.**

```
mkdir -p deploy/files/usr/local/lib/left4me/nft
```

Write `deploy/files/usr/local/lib/left4me/nft/left4me-mark.nft`:

```nft
# left4me — uid-based DSCP/priority marking for srcds UDP egress.
# Loaded by left4me-nft-mark.service into its own `inet` table so it cannot
# conflict with whatever the operator already runs in /etc/nftables.conf.
# See docs/superpowers/specs/2026-05-10-l4d2-network-shaping-design.md.

table inet left4me_mark {
    chain mangle_output {
        type filter hook output priority mangle; policy accept;
        meta skuid "left4me" meta l4proto udp ip dscp set ef meta priority set 0006:0000
        meta skuid "left4me" meta l4proto udp ip6 dscp set ef meta priority set 0006:0000
    }
}
```

- [ ] **Step 4: Re-run the test and confirm it passes.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_nft_mark_file_marks_left4me_udp_with_dscp_ef_and_priority -v
```
Expected: PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/usr/local/lib/left4me/nft/left4me-mark.nft deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): nftables uid-based DSCP-EF + skb-priority marking for srcds"
```

---

### Task 3: nftables systemd unit

**Files:**
- Create: `deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service`
- Modify: `deploy/tests/test_deploy_artifacts.py` (path constant + test)

- [ ] **Step 1: Add the path constant and a failing test.**

Append the constant near the existing systemd-unit constants (around line 16):

```python
NFT_MARK_UNIT = DEPLOY / "files/usr/local/lib/systemd/system/left4me-nft-mark.service"
```

Append the test:

```python
def test_nft_mark_unit_loads_and_clears_left4me_table():
    assert NFT_MARK_UNIT.is_file()
    text = NFT_MARK_UNIT.read_text()

    # Loads the rules early so the very first packet srcds emits is marked.
    assert "After=network-pre.target" in text
    assert "Before=network.target" in text
    assert "Wants=network-pre.target" in text

    # Oneshot lifecycle: load on start, drop on stop.
    assert "Type=oneshot" in text
    assert "RemainAfterExit=yes" in text
    assert (
        "ExecStart=/usr/sbin/nft -f /usr/local/lib/left4me/nft/left4me-mark.nft"
        in text
    )
    assert "ExecStop=/usr/sbin/nft delete table inet left4me_mark" in text
    assert "WantedBy=multi-user.target" in text
```

- [ ] **Step 2: Run the test and confirm FAIL.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_nft_mark_unit_loads_and_clears_left4me_table -v
```
Expected: FAIL — `assert False` on `NFT_MARK_UNIT.is_file()`.

- [ ] **Step 3: Write the unit file.**

`deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service`:

```ini
[Unit]
Description=left4me nftables packet marking (DSCP EF + priority for srcds)
After=network-pre.target
Before=network.target
Wants=network-pre.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/sbin/nft -f /usr/local/lib/left4me/nft/left4me-mark.nft
ExecStop=/usr/sbin/nft delete table inet left4me_mark

[Install]
WantedBy=multi-user.target
```

- [ ] **Step 4: Re-run the test and confirm PASS.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_nft_mark_unit_loads_and_clears_left4me_table -v
```
Expected: PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): systemd unit to load/clear left4me_mark nftables table"
```

---

### Task 4: CAKE env template

**Files:**
- Create: `deploy/files/etc/left4me/cake.env`
- Modify: `deploy/tests/test_deploy_artifacts.py` (path constant + test)

- [ ] **Step 1: Add path constant and failing test.**

Append the constant near the other `/etc/left4me` constants (around line 22):

```python
CAKE_ENV = DEPLOY / "files/etc/left4me/cake.env"
```

Append the test:

```python
def test_cake_env_template_documents_required_knobs():
    assert CAKE_ENV.is_file()
    text = CAKE_ENV.read_text()

    # Both knobs are documented and present (commented OK; the deploy preserves
    # operator edits, so the template must not bake in a wrong value).
    assert "LEFT4ME_UPLINK_MBIT" in text
    assert "LEFT4ME_UPLINK_IFACE" in text
    # Empty defaults: shaper unit no-ops with a journal warning when unset.
    assert "LEFT4ME_UPLINK_MBIT=" in text
    assert "LEFT4ME_UPLINK_IFACE=" in text
```

- [ ] **Step 2: Run and confirm FAIL.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_cake_env_template_documents_required_knobs -v
```
Expected: FAIL on `CAKE_ENV.is_file()`.

- [ ] **Step 3: Write the env template.**

`deploy/files/etc/left4me/cake.env`:

```
# left4me — CAKE egress shaper config. Consumed by left4me-cake.service via
# its EnvironmentFile=. Edit then `systemctl restart left4me-cake.service`.
# See docs/superpowers/specs/2026-05-10-l4d2-network-shaping-design.md.

# Uplink bandwidth in Mbit/s. Set to ~95% of the smaller of measured upload
# and measured download. CAKE only shapes correctly when its declared
# bandwidth sits below the real bottleneck. If unset, the shaper unit logs
# a warning and exits 0 (no shaping).
LEFT4ME_UPLINK_MBIT=

# Egress interface. If unset, auto-detected from the IPv4 default route.
LEFT4ME_UPLINK_IFACE=
```

- [ ] **Step 4: Re-run and confirm PASS.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_cake_env_template_documents_required_knobs -v
```
Expected: PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/etc/left4me/cake.env deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): cake.env template with documented uplink knobs"
```

---

### Task 5: CAKE helper script

**Files:**
- Create: `deploy/files/usr/local/libexec/left4me/left4me-apply-cake`
- Modify: `deploy/tests/test_deploy_artifacts.py` (path constant + tests)

- [ ] **Step 1: Add path constant and failing tests.**

Append the constant near the libexec helper constants (around line 21):

```python
APPLY_CAKE_HELPER = DEPLOY / "files/usr/local/libexec/left4me/left4me-apply-cake"
```

Append two test functions:

```python
def test_apply_cake_helper_supports_apply_and_clear_modes():
    assert APPLY_CAKE_HELPER.is_file()
    text = APPLY_CAKE_HELPER.read_text()

    assert text.startswith("#!/bin/sh")
    # Both knobs are read from the env file.
    assert "LEFT4ME_UPLINK_MBIT" in text
    assert "LEFT4ME_UPLINK_IFACE" in text
    assert ". /etc/left4me/cake.env" in text
    # Iface fallback to default route.
    assert "ip -4 route show default" in text
    # Two modes; default to apply.
    assert "mode=${1:-apply}" in text
    assert 'apply)' in text and 'clear)' in text
    # Apply: idempotent `tc qdisc replace` with the documented flags.
    assert "tc qdisc replace" in text
    assert "cake" in text
    assert "bandwidth" in text
    assert "internet" in text
    assert "diffserv4" in text
    assert "dual-dsthost" in text
    # Clear: tolerates a missing qdisc.
    assert "tc qdisc del" in text
    assert "|| true" in text
    # Fail-soft on missing config.
    assert "LEFT4ME_UPLINK_MBIT unset" in text


def test_apply_cake_helper_passes_shell_syntax_check():
    subprocess.run(["sh", "-n", str(APPLY_CAKE_HELPER)], check=True)
```

- [ ] **Step 2: Run and confirm FAIL.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_apply_cake_helper_supports_apply_and_clear_modes deploy/tests/test_deploy_artifacts.py::test_apply_cake_helper_passes_shell_syntax_check -v
```
Expected: both FAIL.

- [ ] **Step 3: Write the helper.**

`deploy/files/usr/local/libexec/left4me/left4me-apply-cake`:

```sh
#!/bin/sh
# left4me — apply or clear CAKE egress shaper on the configured uplink.
# Driven by left4me-cake.service. See spec
# docs/superpowers/specs/2026-05-10-l4d2-network-shaping-design.md.
set -eu

mode=${1:-apply}

if [ -r /etc/left4me/cake.env ]; then
    . /etc/left4me/cake.env
fi

resolve_iface() {
    if [ -n "${LEFT4ME_UPLINK_IFACE:-}" ]; then
        printf '%s' "$LEFT4ME_UPLINK_IFACE"
        return
    fi
    ip -4 route show default | awk '/default/ {print $5; exit}'
}

case "$mode" in
    apply)
        if [ -z "${LEFT4ME_UPLINK_MBIT:-}" ]; then
            echo "left4me-cake: LEFT4ME_UPLINK_MBIT unset; skipping shaper" >&2
            exit 0
        fi
        iface=$(resolve_iface)
        if [ -z "$iface" ]; then
            echo "left4me-cake: cannot determine egress iface; skipping" >&2
            exit 0
        fi
        exec tc qdisc replace dev "$iface" root cake \
            bandwidth "${LEFT4ME_UPLINK_MBIT}mbit" \
            internet diffserv4 dual-dsthost
        ;;
    clear)
        iface=$(resolve_iface)
        if [ -z "$iface" ]; then
            exit 0
        fi
        tc qdisc del dev "$iface" root 2>/dev/null || true
        ;;
    *)
        echo "usage: $0 [apply|clear]" >&2
        exit 2
        ;;
esac
```

Make it executable in the repo (the deploy script also `chmod 0755`s the destination, but executable mode in the source tree is conventional here):

```
chmod 0755 deploy/files/usr/local/libexec/left4me/left4me-apply-cake
```

- [ ] **Step 4: Re-run and confirm PASS.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_apply_cake_helper_supports_apply_and_clear_modes deploy/tests/test_deploy_artifacts.py::test_apply_cake_helper_passes_shell_syntax_check -v
```
Expected: both PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/usr/local/libexec/left4me/left4me-apply-cake deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): left4me-apply-cake helper with apply/clear modes"
```

---

### Task 6: CAKE systemd unit

**Files:**
- Create: `deploy/files/usr/local/lib/systemd/system/left4me-cake.service`
- Modify: `deploy/tests/test_deploy_artifacts.py` (path constant + test)

- [ ] **Step 1: Add path constant and failing test.**

Append the constant near the existing systemd-unit constants (around line 16):

```python
CAKE_UNIT = DEPLOY / "files/usr/local/lib/systemd/system/left4me-cake.service"
```

Append the test:

```python
def test_cake_unit_runs_helper_in_apply_and_clear_modes():
    assert CAKE_UNIT.is_file()
    text = CAKE_UNIT.read_text()

    assert "After=network-online.target" in text
    assert "Wants=network-online.target" in text
    assert "Type=oneshot" in text
    assert "RemainAfterExit=yes" in text
    # `-` prefix: missing env file is non-fatal (deploy ships one, but be safe).
    assert "EnvironmentFile=-/etc/left4me/cake.env" in text
    assert (
        "ExecStart=/usr/local/libexec/left4me/left4me-apply-cake apply" in text
    )
    assert (
        "ExecStop=/usr/local/libexec/left4me/left4me-apply-cake clear" in text
    )
    assert "WantedBy=multi-user.target" in text
```

- [ ] **Step 2: Run and confirm FAIL.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_cake_unit_runs_helper_in_apply_and_clear_modes -v
```
Expected: FAIL on `CAKE_UNIT.is_file()`.

- [ ] **Step 3: Write the unit.**

`deploy/files/usr/local/lib/systemd/system/left4me-cake.service`:

```ini
[Unit]
Description=left4me CAKE egress shaper
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
EnvironmentFile=-/etc/left4me/cake.env
ExecStart=/usr/local/libexec/left4me/left4me-apply-cake apply
ExecStop=/usr/local/libexec/left4me/left4me-apply-cake clear

[Install]
WantedBy=multi-user.target
```

- [ ] **Step 4: Re-run and confirm PASS.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_cake_unit_runs_helper_in_apply_and_clear_modes -v
```
Expected: PASS.

- [ ] **Step 5: Commit.**

```
git add deploy/files/usr/local/lib/systemd/system/left4me-cake.service deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): left4me-cake.service oneshot wrapping apply-cake helper"
```

---

### Task 7: Wire artifacts into `deploy-test-server.sh`

**Files:**
- Modify: `deploy/deploy-test-server.sh`
- Modify: `deploy/tests/test_deploy_artifacts.py` (new test)

This task adds: `nftables` to apt/dnf install lines, copies the four new artifact files into their target paths, conditionally copies `cake.env` only if absent, and `systemctl enable --now`s the two new units. Each piece gets its own assertion in a single new test function.

- [ ] **Step 1: Add the new test.**

Append to `deploy/tests/test_deploy_artifacts.py`:

```python
def test_deploy_script_installs_network_shaping_artifacts():
    script = DEPLOY_SCRIPT.read_text()

    # nftables: package install on both apt and dnf paths.
    apt_lines = [l for l in script.splitlines() if "apt-get install" in l]
    dnf_lines = [l for l in script.splitlines() if "dnf install" in l]
    assert apt_lines and dnf_lines
    for line in apt_lines:
        assert "nftables" in line, line
    for line in dnf_lines:
        assert "nftables" in line, line

    # nft rules + unit copied to system paths.
    assert "/usr/local/lib/left4me/nft/left4me-mark.nft" in script
    assert (
        "/usr/local/lib/systemd/system/left4me-nft-mark.service" in script
    )
    assert "systemctl enable --now left4me-nft-mark.service" in script

    # CAKE helper + unit copied; helper made executable.
    assert "/usr/local/libexec/left4me/left4me-apply-cake" in script
    assert (
        "/usr/local/lib/systemd/system/left4me-cake.service" in script
    )
    assert "chmod 0755" in script and "left4me-apply-cake" in script
    assert "systemctl enable --now left4me-cake.service" in script

    # cake.env: copied only if absent (operator edits survive re-deploys).
    assert "/etc/left4me/cake.env" in script
    assert "[ -e /etc/left4me/cake.env ]" in script
```

- [ ] **Step 2: Run and confirm FAIL.**

```
pytest deploy/tests/test_deploy_artifacts.py::test_deploy_script_installs_network_shaping_artifacts -v
```
Expected: FAIL on the first missing string.

- [ ] **Step 3: Edit `deploy-test-server.sh`.**

Make these targeted edits — do not rewrite the script.

(a) **Append `nftables` to both package-install lines (line 88 and line 90 in the current file).**

Old (line 88):
```
    $sudo_cmd apt-get install -y python3 python3-venv python3-pip curl ca-certificates tar gzip util-linux sudo coreutils p7zip-full
```
New:
```
    $sudo_cmd apt-get install -y python3 python3-venv python3-pip curl ca-certificates tar gzip util-linux sudo coreutils p7zip-full nftables
```

Old (line 90):
```
    $sudo_cmd dnf install -y python3 python3-pip curl ca-certificates tar gzip util-linux sudo coreutils p7zip p7zip-plugins
```
New:
```
    $sudo_cmd dnf install -y python3 python3-pip curl ca-certificates tar gzip util-linux sudo coreutils p7zip p7zip-plugins nftables
```

(b) **Add the nft-rules-dir creation to the `mkdir -p` block (currently lines 96-106).**

Append `/usr/local/lib/left4me/nft` to the existing `mkdir -p` invocation:

Old (lines 96-106):
```
$sudo_cmd mkdir -p \
    /etc/left4me \
    /opt/left4me \
    /usr/local/lib/systemd/system \
    /usr/local/libexec/left4me \
    /var/lib/left4me/installation \
    /var/lib/left4me/overlays \
    /var/lib/left4me/instances \
    /var/lib/left4me/runtime \
    /var/lib/left4me/workshop_cache \
    /var/lib/left4me/tmp
```
New (insert one line after `/usr/local/libexec/left4me`):
```
$sudo_cmd mkdir -p \
    /etc/left4me \
    /opt/left4me \
    /usr/local/lib/systemd/system \
    /usr/local/libexec/left4me \
    /usr/local/lib/left4me/nft \
    /var/lib/left4me/installation \
    /var/lib/left4me/overlays \
    /var/lib/left4me/instances \
    /var/lib/left4me/runtime \
    /var/lib/left4me/workshop_cache \
    /var/lib/left4me/tmp
```

(c) **Copy the new systemd units alongside the existing ones (after line 140's `l4d2-build.slice` copy).**

Insert immediately after the `l4d2-build.slice` copy (the existing line that ends `l4d2-build.slice`):

```
$sudo_cmd cp /opt/left4me/deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service /usr/local/lib/systemd/system/left4me-nft-mark.service
$sudo_cmd cp /opt/left4me/deploy/files/usr/local/lib/systemd/system/left4me-cake.service /usr/local/lib/systemd/system/left4me-cake.service
```

(d) **Copy the nftables rules file alongside the existing `install`-mode copies (next to the sandbox-resolv.conf install at lines 189-191).**

Insert after the sandbox-resolv install block:

```
# Network packet marking + shaping. See spec
# docs/superpowers/specs/2026-05-10-l4d2-network-shaping-design.md.
$sudo_cmd install -m 0644 -o root -g root \
    /opt/left4me/deploy/files/usr/local/lib/left4me/nft/left4me-mark.nft \
    /usr/local/lib/left4me/nft/left4me-mark.nft
```

(e) **Copy the CAKE helper alongside the other libexec helpers (after the existing `cp` block at lines 175-179).**

Find the existing `cp` block that copies `left4me-systemctl`, `left4me-journalctl`, `left4me-overlay`, `left4me-script-sandbox`. Add a new `cp` line for `left4me-apply-cake`, and add it to the `chmod 0755` line on line 179:

Old (line 178):
```
$sudo_cmd cp /opt/left4me/deploy/files/usr/local/libexec/left4me/left4me-script-sandbox /usr/local/libexec/left4me/left4me-script-sandbox
```
After it, insert:
```
$sudo_cmd cp /opt/left4me/deploy/files/usr/local/libexec/left4me/left4me-apply-cake /usr/local/libexec/left4me/left4me-apply-cake
```

Old (line 179):
```
$sudo_cmd chmod 0755 /usr/local/libexec/left4me/left4me-systemctl /usr/local/libexec/left4me/left4me-journalctl /usr/local/libexec/left4me/left4me-overlay /usr/local/libexec/left4me/left4me-script-sandbox
```
New (append `left4me-apply-cake`):
```
$sudo_cmd chmod 0755 /usr/local/libexec/left4me/left4me-systemctl /usr/local/libexec/left4me/left4me-journalctl /usr/local/libexec/left4me/left4me-overlay /usr/local/libexec/left4me/left4me-script-sandbox /usr/local/libexec/left4me/left4me-apply-cake
```

(f) **Conditionally copy `cake.env` (after the existing sysctl install/apply block at lines 193-198).**

Insert immediately after `$sudo_cmd sysctl --system >/dev/null`:

```
# CAKE config: ship the template only if the operator hasn't created one
# (their LEFT4ME_UPLINK_MBIT value must survive re-deploys).
if [ ! -e /etc/left4me/cake.env ]; then
    $sudo_cmd install -m 0644 -o root -g root \
        /opt/left4me/deploy/files/etc/left4me/cake.env \
        /etc/left4me/cake.env
fi
```

(g) **Enable the new units alongside the existing `systemctl enable --now left4me-web.service`.**

Find the existing block (around line 315-316):
```
$sudo_cmd systemctl daemon-reload
$sudo_cmd systemctl enable --now left4me-web.service
```

Insert two lines between them:
```
$sudo_cmd systemctl daemon-reload
$sudo_cmd systemctl enable --now left4me-nft-mark.service
$sudo_cmd systemctl enable --now left4me-cake.service
$sudo_cmd systemctl enable --now left4me-web.service
```

- [ ] **Step 4: Re-run all existing tests + the new one to make sure nothing regressed.**

```
pytest deploy/tests/test_deploy_artifacts.py -v
```
Expected: every test passes, including the new `test_deploy_script_installs_network_shaping_artifacts` and the unmodified `test_deploy_script_shell_syntax` (the latter validates `sh -n` on the modified script).

- [ ] **Step 5: Commit.**

```
git add deploy/deploy-test-server.sh deploy/tests/test_deploy_artifacts.py
git commit -m "feat(deploy): wire nft marking + CAKE shaper into deploy script"
```

---

### Task 8: README documentation

**Files:**
- Modify: `deploy/README.md`

This is documentation only — no test asserts the README contents. Run an `sh -n` of the deploy script one more time after editing, just as a hygiene check (the README change can't affect it, but the test suite is fast).

- [ ] **Step 1: Open `deploy/README.md` and locate the existing Performance tuning section.**

The previous perf-baseline spec added a "Performance tuning" section (entries for CPU governor, CPU affinity, NIC tuning, and real-time scheduling opt-in). Find it.

- [ ] **Step 2: Add a "Network shaping" subsection.**

Add this subsection at the top of "Performance tuning" (before the existing entries; network-shaping covers the universal artifacts that ship by default, while the existing entries are escape hatches):

```markdown
### Network shaping

The deploy ships three things that affect player-experience network behaviour:

1. **Per-flow marking.** `left4me-nft-mark.service` loads a small nftables
   table (`inet left4me_mark`) that marks every UDP packet from uid `left4me`
   with DSCP EF and `skb->priority` 6. srcds doesn't set these itself, so
   without this rule its UDP is indistinguishable from any other flow.
2. **Sysctl baseline.** `99-left4me.conf` sets `udp_rmem_min=16384`,
   `udp_wmem_min=16384`, `default_qdisc=fq_codel`, and
   `tcp_congestion_control=bbr`. Reduces head-of-line blocking when bulk
   TCP egress (backups, package fetches, web responses) coexists with
   game UDP.
3. **CAKE egress shaping.** `left4me-cake.service` runs
   `tc qdisc replace dev <iface> root cake bandwidth Xmbit internet
   diffserv4 dual-dsthost` from `/etc/left4me/cake.env`. CAKE only shapes
   if its declared bandwidth is **below** the real bottleneck, so set
   `LEFT4ME_UPLINK_MBIT` to ≈95% of measured uplink:

       sudoedit /etc/left4me/cake.env
       # set LEFT4ME_UPLINK_MBIT=480 (or whatever ~95% of your uplink is)
       sudo systemctl restart left4me-cake.service

   `LEFT4ME_UPLINK_IFACE` is auto-detected from the IPv4 default route;
   override only on hosts with multi-homed setups.

   At idle 500 Mbit with no competing egress, CAKE shapes nothing — that's
   expected, not a bug. The win materialises when bulk traffic on the
   same uplink would otherwise bufferbloat the link the players share.

**Production hosts running `systemd-networkd`** should NOT use the
`left4me-cake.service` oneshot. Instead, configure the equivalent in the
matching `.network` file, which systemd-networkd reapplies across iface
lifecycle events:

    # /etc/systemd/network/<your-uplink>.network
    [CAKE]
    Bandwidth=480M
    OverheadKeyword=internet
    PriorityQueueingPreset=diffserv4
    EgressHostIsolation=yes

The nftables marking from (1) is qdisc-installer-agnostic and ships
unchanged on production.
```

- [ ] **Step 3: Append the three new escape hatches to the existing Performance tuning section.**

Add after the existing escape-hatch entries (CPU governor / CPU affinity / NIC tuning / real-time scheduling):

```markdown
### Additional opt-in network knobs

- **Ingress shaping via IFB.** Egress CAKE alone does not protect srcds
  receive against ingress saturation (large workshop downloads, package
  fetches arriving at line rate). One-liner:

      sudo modprobe ifb && sudo ip link set ifb0 up
      sudo tc qdisc add dev <uplink> handle ffff: ingress
      sudo tc filter add dev <uplink> parent ffff: protocol ip u32 \
          match u32 0 0 action mirred egress redirect dev ifb0
      sudo tc qdisc add dev ifb0 root cake bandwidth Xmbit ingress \
          diffserv4 dual-srchost

  Worth flipping only when measurement shows ingress hurting receive.

- **`net.core.busy_poll = 50` / `net.core.busy_read = 50`.** Reduces UDP
  receive median latency by polling for incoming packets briefly at
  syscall boundaries. Cost: measurable CPU per syscall under load. Worth
  flipping if a host is dedicated to game serving and CPU headroom is
  plentiful.

- **`ethtool -K <iface> gro off`.** Some Source-engine ops disable
  generic receive offload to avoid receive-side coalescing latency.
  Hardware/driver dependent; document only.
```

- [ ] **Step 4: Re-run the full test suite.**

```
pytest deploy/tests/test_deploy_artifacts.py -v
```
Expected: every test passes, including `test_deploy_script_shell_syntax`.

- [ ] **Step 5: Commit.**

```
git add deploy/README.md
git commit -m "docs(deploy): document network-shaping defaults + opt-in network knobs"
```

---

## Final verification

After all eight tasks land, run the whole suite once more and verify the new files are tracked:

```
pytest deploy/tests/test_deploy_artifacts.py -v
git status
git log --oneline -10
```

Every test should pass. `git status` should be clean. The last 8 commits should match the eight tasks above.

The new files in the tree:

```
deploy/files/etc/left4me/cake.env
deploy/files/usr/local/lib/left4me/nft/left4me-mark.nft
deploy/files/usr/local/lib/systemd/system/left4me-cake.service
deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service
deploy/files/usr/local/libexec/left4me/left4me-apply-cake
```

Modified files:

```
deploy/files/etc/sysctl.d/99-left4me.conf
deploy/deploy-test-server.sh
deploy/README.md
deploy/tests/test_deploy_artifacts.py
```