# Patch Policy — the contributor contract for load-bearing patches (v0.8.0, #141)

This is the **durable contract** for anyone (human or agent) adding,
modifying, or removing a patch that the v0.8.0 compose generator
([`scripts/generate-compose.sh`](../scripts/generate-compose.sh)) consumes.
It is prescriptive and self-contained: follow it exactly, and
`scripts/tests/test-patch-attribution.sh` + `scripts/tests/test-generate-compose.sh`
will gate your PR cleanly.

It exists for one reason, stated up front so it frames every rule below:

> ### The #145 lesson
> A patch can be present in the repo, declared "load-bearing", and *still
> never reach the running engine* — silently. That is the
> `#72` / `#145`-class failure: a load-bearing fix that the compose does not
> actually deliver, with no error, just a quietly-wrong server. **Every
> mechanism in this document exists to make a silently-undelivered
> load-bearing patch impossible to introduce without it failing loud.**

For the data model these rules sit on, see
[`docs/PATCH_ATTRIBUTION.md`](PATCH_ATTRIBUTION.md). For how the generator
*uses* this metadata, see [`docs/COMPOSE_GENERATOR.md`](COMPOSE_GENERATOR.md).

---

## 1. Where patches and metadata live

| File | Role |
|---|---|
| `models/<model>/<engine>/patches/<patch-dir>/` | the patch artifact itself (overlay file(s), sidecar `.py`, or `install.sh`) |
| `scripts/lib/profiles/patches.yml` | the patch entry — what it fixes, how it is delivered, where it is load-bearing, its drift-guard |
| `scripts/lib/profiles/arch_patches.yml` | declarative arch → engine-pin / valid-TP / trc gate (C0 authority; **strict closed key-set** — do not add keys) |
| `scripts/lib/profiles/profile_runtime.yml` | per-profile captured template + `genesis_equipped`; `arch_model_xref` trc evidence ledger |

**Add the `patches.yml` entry in the same change as the patch artifact.**
Never land a patch file without its entry, and never land an entry that
points at a missing artifact.

---

## 2. Required per-patch metadata

A load-bearing patch entry in `patches.yml` MUST carry all of:

| Field | Requirement |
|---|---|
| `id` | unique, stable, descriptive |
| `model` | list of model slugs the patch applies to |
| `files` | repo-relative path(s) to the patch artifact |
| `load_bearing_when[].composes` | the **exact** list of profile keys this patch is load-bearing for. This is the *only* thing the generator keys patch selection off (`X ∈ P.load_bearing_when[].composes`). Each entry also carries `reason` + `evidence`. |
| `delivery_mechanism` | one of `python_sidecar`, `site_package_overlay`, `install_script`, `chat_template` (vendored `.jinja` override — see §3.1), or `none` (diagnostics / negative-result / Genesis-env patches) |
| `delivery_spec` | the concrete wiring: mount target(s) (`overlay_files[].dest`, `overlay_dir`+`dest_root`, `mounted_at`), sidecar/script path, `invoke` command, and `wired_at` (`volumes`, `entrypoint`, or both). This is the **single source** both the generator's emit and `reaches()`'s reachability validation read — they must agree by construction. |
| `drift_guard` | **mandatory** for any load-bearing patch (`kind`, `check`, `on_fail`). See §4. |
| `capability` | the capability the patch delivers (e.g. `tp-weight-load`, `tool-choice-required`, `tool-call-stream`, `dflash-spec-decode`) |
| `foundational` | `true` if weights/boot cannot proceed without it; `false` if absence merely loses a capability. Drives the §4.1 grade. |
| `upstream` | `ref` + `status` + `drop_when` — the condition under which the patch should be removed |
| `status` | `verified`, `unverified`, or `suspect`. Use `unverified` honestly — never claim `verified` without evidence. The `load_bearing_when[].evidence` string must point at a real doc/README anchor. |
| `delivery_gaps[]` | declare here, do **not** silently fix, any profile where the patch is load-bearing but cannot reach the compose today (the #145-class boundary). Each gap carries `composes` + an `issue` string. |

The legacy `delivery:` boolean block
(`dockerfile_bake`/`entrypoint_invoke`/`genesis`) is **DEPRECATED and
READ-ONLY** — retained verbatim only because `test-patch-attribution.sh`
still reads it. Do **not** put new wiring decisions there; use
`delivery_mechanism` / `delivery_spec`.

Diagnostics / no-op / negative-local-result / Genesis-env patches set
`delivery_mechanism: none` and have no `delivery_spec`.

---

## 3. Hard rule: guarded `python_sidecar` is the default delivery mechanism

Choose the delivery mechanism in this order of preference:

1. **`python_sidecar` (DEFAULT).** A guarded sidecar `.py` invoked from the
   entrypoint before `vllm` imports/serves. This is the locked default for
   any new patch unless there is a concrete reason it cannot work.
2. **`install_script`.** A mounted `install.sh` invoked from the entrypoint
   (`invoked_before: vllm-import`). Use when the change is a multi-step
   install rather than a single Python shim.
3. **`site_package_overlay` (LAST RESORT).** A bind-mount over a
   `dist-packages/...` file. Permitted **only** for an isolated, single-file
   emergency. It carries the **#145-class risk** (a stale/conflicting overlay
   silently shadows upstream — overlays of `speculative.py` /
   `gpu_model_runner.py` etc. conflict with each other; only one variant can
   run at a time) and **must be re-homed** to a sidecar or upstream fix as
   soon as the emergency is over. A multi-file overlay must record its
   `file_count` and a `note` flagging the #145-risk and any conflicting
   overlay it is mutually exclusive with.

If you reach for `site_package_overlay`, justify it in the PR and file the
re-home follow-up.

### 3.1 The `chat_template` delivery class

A **model chat-template override** (a vendored `.jinja` mounted into the
container) is its own delivery class — `delivery_mechanism: chat_template`.
A bad/regressed/re-vendored template is exactly the **#145 silent-break
class** (tool-call XML / reasoning delimiters / streaming), so it MUST be
attributed and drift-guarded like any other load-bearing patch, not left
invisible to the generator and `test-patch-attribution`.

`delivery_spec` for a `chat_template` patch carries:

- `jinja` — repo-relative path to the vendored `.jinja` (it is also the
  patch's `files[]` entry; an orphan `.jinja` under a model `patches/`
  tree with no `chat_template` patch is a hard test failure);
- `mounted_at` — the container path the `.jinja` is bind-mounted to;
- `mount_mode` — typically `ro`;
- `invoke` — the serving wiring. Two in-tree styles:
  - **explicit** `--chat-template <mounted_at>` (e.g. froggeric):
    `wired_at: [volumes, entrypoint]`;
  - **mount-only** (e.g. carnice mounts over the model dir's
    `chat_template.jinja` and vLLM auto-loads it): `wired_at: [volumes]`,
    no `--chat-template` arg;
- `wired_at` — as above.

**Effective coverage is computed from the REAL merged compose graph.**
A `chat_template` patch's reachability is resolved with **Docker Compose
`extends:` merge semantics** (`docker compose -f <child> config`, or a
deterministic offline merge that applies the same rules), **never a raw
single-base text concat**. This is mandatory because a child compose can
`!reset` the base's mount/command or simply stop extending a
template-bearing base — a text concat would still "see" the base's mount
line and report coverage that no longer exists (a **false negative** —
the dangerous direction; the #377 silent-drift mode). Note Compose merges
`extends:` *sequences* additively: a plain re-declared `volumes: []` does
**not** drop a base mount; only the `!reset` tag (or not extending the
base at all) removes it. `test-patch-attribution.sh` carries a fixture
asserting a `!reset` child and a stopped-extending child both lose
coverage.

The `drift_guard` for a `chat_template` patch is `kind: behavioral` and
its `check` MUST encode the **self-contained symmetric restart+settle
protocol**: identical `docker restart <container>` on BOTH arms → wait
for `/v1/models` healthy → fixed 60 s settle → ≥3 `bench.sh` runs/arm →
compare the **grand mean** of the SAME canonical bench segment (NARRATIVE
800-word essay + CODE; never mix segments, never a single run); flag
ONLY a deterministic regression reproduced across all 3 runs. A
non-symmetric guard fabricates phantom regressions (the asymmetric-restart
"−7%" artifact) and gets ignored. The same guard must clear the *next*
template re-vendor.

---

## 4. Hard rule: no `drift_guard` ⇒ not load-bearing in a generated compose

A patch with **no `drift_guard`** is, by definition, **not load-bearing in a
generated compose**. The generator only wires a patch whose state is
"applies cleanly" — and "applies cleanly" *means* drift-guard-tested (a
locked decision). If you believe a patch is load-bearing, you MUST give it a
`drift_guard`; if you cannot articulate a guard, the patch is not eligible to
be wired by the generator.

`drift_guard` fields:

- `kind` — `import-and-boot` or `behavioral`.
- `check` — a concrete, testable statement of what "still applies" means on
  the selected nightly.
- `on_fail` — the §4.1 grade (see below).

### 4.1 Drift fails loud — never silently repaired

The drift-guard is a runtime probe. The generator **cannot** run it at
generation time (no engine container), so it wires the maintainer-tested
patch and surfaces the guard for the boot leg / operator to re-run. When a
guard **fails**, the outcome is graded — and the generator **never repairs**:

| `on_fail` / `foundational` | Outcome | Rationale |
|---|---|---|
| `capability-degraded` (foundational: false) | patch **OMITTED**, compose flagged **DEGRADED**; run needs `--accept-degraded` (else exit 3). Patch is **never wired**. | The model still serves, minus one capability. Honest degradation beats a silently-broken capability. |
| `hard-refuse` / `foundational: true` | **hard-refuse** (exit 2), even *with* `--accept-degraded`. | Weights/boot depend on it; there is nothing safe to emit. |

**Gap-before-guard ordering:** a declared `delivery_gaps[]` entry covering
the profile is evaluated *before* the drift-guard — the patch is
selected-but-undelivered (wiring omitted, header WARNING) and the guard is
skipped. This is the structural acknowledgement of a known coverage
boundary; it is loud (header category [2]) by construction, never silent.

The contract: **drift never gets repaired, only flagged.** A failed
capability-scoped guard degrades; a failed foundational guard refuses;
neither edits the patch.

---

## 5. Hard rule: Genesis patches are arch-data only, never generator-emitted

The compose generator is **non-Genesis, vLLM-only** (a permanently locked
v0.8.x scope decision). Genesis patches:

- live in `patches.yml`/`arch_patches.yml` as **data only** (so the
  attribution audit stays complete);
- set `delivery_mechanism: none` (they are env-gated, not generator-wired);
- are **never emitted** by the generator — any profile that is
  `genesis_equipped: true` (compose has a `GENESIS_*` / `_genesis` token, or
  `kv_format` starts `turboquant`) is a clean refusal.

Do not add a Genesis patch expecting the generator to wire it. It will not,
and that is intentional.

---

## 6. Contributor workflow

1. **Land the artifact + entry together.** Add the patch under
   `models/<model>/<engine>/patches/<patch-dir>/` and its `patches.yml`
   entry (all §2 fields) in the same commit.
2. **Pick the delivery mechanism per §3** (default `python_sidecar`).
   Write the `delivery_spec` so `wired_at` and the mount/invoke markers
   describe the *actual* wiring in the compose(s) you list under
   `load_bearing_when[].composes`.
3. **Write a real `drift_guard` (§4).** No guard ⇒ the generator will not
   wire it (§4 hard rule) — that is a design signal, not a workaround.
4. **Wire it into the shipped compose(s)** you declared, OR — if you cannot
   reach a listed compose today — declare a `delivery_gaps[]` entry with an
   honest `issue` string. **Do not silently fix runtime files instead of
   declaring the gap** (that *is* the #145 failure mode).
5. **If the patch gates an arch/engine path**, extend the matching
   `arch_patches.yml` row (`required_patches`, `engine_pin`, `valid_tp`,
   `requires_trust_remote_code`). Do **not** add new top-level keys —
   `arch_patches.yml` is a strict closed key-set; arch-scoped fold-ins go in
   `profile_runtime.yml`'s `arch_model_xref`.
6. **Run the gates** (next section). Both must be green; the
   patch-attribution summary must stay exactly
   `61 patch / 11 arch / 18 calibration` *plus your delta* (the audit
   re-counts — keep the known-gaps list intentional).

---

## 7. How the tests gate a patch PR

Two tests are the contract. They are the contract; patches are fixed to them,
never the reverse.

### `scripts/tests/test-patch-attribution.sh`

Imports `scripts/lib/profiles/patch_attribution.py` and audits every
`patches.yml` / `arch_patches.yml` / `calibration_seed.yml` entry. It checks:
schema (all §2 required keys present, valid `status`/`confidence`/trc
tri-state), the closed arch key-set, artifact coverage, and **reachability**:

> `reaches(root, patch, name_or_path)` parses the **comment-stripped service
> body only** (everything from the top-level `services:` key onward, header
> banner and `#` comments removed) and validates the patch's **actual
> `delivery_spec` wiring** — the declared mount target(s) and/or entrypoint
> invoke at the `wired_at` insertion point(s) — *not* a substring of the
> patch ID.

Consequences for a contributor:

- A patch ID merely *named in a comment/header* does **not** count as
  reached — you must wire the real `delivery_spec` artifact.
- A patch declared load-bearing for a compose it does not actually reach
  fails the audit **unless** you declared the `delivery_gaps[]` entry. The
  audit prints the gap list explicitly — a silently-undelivered load-bearing
  patch cannot pass.

### `scripts/tests/test-generate-compose.sh`

Generates the five golden triples and asserts the golden-parity invariant
(semantic diff confined to the two insertion points; constants + image
expression verbatim), that wired patches `reaches()` the *generated* compose,
that selected-but-undelivered patches are **not** reachable, that no
`--trust-remote-code` is emitted, and the full refusal/degraded matrix.

If your patch is load-bearing for a golden triple, it must wire cleanly into
the generated compose (or be a correctly-declared gap). If it changes the
captured service body of a golden profile, update the shipped compose so the
parity invariant holds — the generator captures, it never synthesizes.

**Both tests must be RC=0 before a patch PR merges.** A silently-undelivered
load-bearing patch is precisely the failure these gates exist to prevent — if
either test goes red, the contract has caught exactly what it is for.