> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

## The Problem

The Docker host vm4006 has 12 GiB of RAM booked and said `fits` on 2026-09-19.
Its RAM peak over eleven days was 7.04 GiB, the median 1.8 GiB, and no quarter hour ever stalled.
RAM is the expensive resource of that booking.

A downsize was considered only when the peak stayed below 40 % of the visible RAM (`DOWNSIZE_RATIO`).
7.04 of 11.69 GiB is 60 %, so the question was never asked.
The rule behind the gate would have answered it: 7.04 / 0.8 plus the 0.31 GiB the host keeps is 9.11, so 10 GiB holds the peak at 73 %.
The gate demanded a peak below 4.7 GiB before Werkator said anything.

The second condition of RFC 0004 D1 already carries the protection the gate was meant to give.
A downsize is advised only when a smaller bookable size holds the peak with the target headroom.
With RAM booked in whole GiB that condition is fine-grained enough to stand alone.

## Non-Goals

- The RAM peak stays the window maximum, not a percentile as for disks (PR#78).
  A moment without memory is a build that stalls, which is the moment the machine exists for.
- The headroom stays 20 % (`TARGET_RATIO`), the same line the RAM gauge turns amber at.
  Booking below the advice, 8 GiB on that host, remains the operator's experiment; stalled quarter hours would turn the advice to `tight` or `upgrade`.
- CPU and disk keep the 40 % gate.
  Their steps are coarse or their peaks short, and nothing asked for a change there.

## The Scenarios

### Feature: a RAM downsize is advised as soon as a smaller bookable size holds the peak

#### Scenario#79.01: A peak at 60 % still leaves a smaller size

- **Given** 12 GiB booked, 11.69 GiB visible, a peak of 7.04 GiB in eleven days and no stalled quarter hour
- **When** the capacity advice is computed with the Hostsharing steps
- **Then** RAM reads `downsize` with 10 GiB recommended
- **And** the reason names the peak, the booked size and that nothing stalled

##### Verified by

- [CapacitySizingTest](../../src/test/kotlin/de/hoennig/werkator/metrics/CapacitySizingTest.kt) — "the Docker host of 2026-09-19 …"

#### Scenario#79.02: No downsize without the headroom, and none while memory stalls

- **Given** the same host with a peak of 8.73 GiB
- **When** the advice is computed
- **Then** RAM reads `fits`, because the 11 GiB below would put the peak above the target
- **And** a host whose memory stalled reads `tight` or `upgrade`, however low its peak

##### Verified by

- [CapacitySizingTest](../../src/test/kotlin/de/hoennig/werkator/metrics/CapacitySizingTest.kt) — "a RAM peak the next smaller size would not hold …", "stalled memory is never downsized …"

## The Solution

`CapacitySizing.ram` drops `roomy` from the downsize condition and keeps `recommended <= smaller`, guarded by `smaller > 0`.
`DOWNSIZE_RATIO` still decides whether a refused downsize is explained in the reason, since that text exists for a gauge that looks empty.

Two existing tests described a well-sized machine with 3.0 and 2.4 of 4.8 GiB.
Under the new rule 4 GiB holds those peaks, so they now use 3.2 GiB, which needs the booked 5.

## Open Questions

- A JVM without `-Xmx` takes a quarter of the visible RAM as its heap limit.
  Part of a measured peak may therefore shrink with the booking, which the advice cannot know.

## Additional Changes

- `docs/deployment.md` and the architecture skill describe the RAM downsize rule.
- Version 1.21.2 with its release note.