club-3090/docs/PATCH_ATTRIBUTION.md

Patch Attribution Profiles

v0.8.0 Phase A adds three data-only profile files:

• scripts/lib/profiles/patches.yml records every local patch bundle and Genesis env-gated patch, what it fixes, how it is delivered, and any known compose coverage gaps.
• scripts/lib/profiles/arch_patches.yml is the declarative input for the locked C0 engine-support gate: arch, loadable engine pins, required patches, valid TP flags, trust-remote-code tri-state, and kernel constraints.
• scripts/lib/profiles/calibration_seed.yml seeds the calibration backbone from directly measured BENCHMARKS.md rows.

These files support the v0.8.x scope: evaluate any safetensors HF repo; pull only vLLM-loadable supported ones, and only when the gates pass (or an explicit override is accepted).

When adding a local patch, add a patches.yml entry in the same change. Declare all delivery channels: Dockerfile bake, compose mount/invoke, or Genesis env gate. If the patch gates an architecture or engine path, add or extend the matching arch_patches.yml row. If a patch is known to be load-bearing but cannot reach a compose today, record it under delivery_gaps rather than silently fixing runtime files in the audit change.

When adding measured results that should seed the cold-start predictor, add a calibration_seed.yml anchor only for directly measured configs. confidence: exact applies only to capabilities listed in smoked_capabilities; everything else stays in unsmoked_capabilities.

If no seeded or community calibration anchor matches a future pull target, the verdict must say: no calibration data for this config class -- prediction is an unvalidated lower bound. Also surface the boot-fit caveat: static fit does not guarantee stability under accumulated-context workloads; run or request a continuous soak before treating a config as production-stable.

v0.8.0 Phase A-prime fold-ins (#359 / PR #147)

Phase A-prime is a discrete prerequisite commit that enriches the Phase A data for the #141 compose generator. It does not reopen Phase A and keeps test-patch-attribution.sh green.

Storage choice — scripts/lib/profiles/profile_runtime.yml

The per-profile captured template, the genesis_equipped discriminator, the arch→model-slug cross-reference, and per-model trust-remote-code evidence are stored in a new scripts/lib/profiles/profile_runtime.yml, not in COMPOSE_REGISTRY fields and not as new top-level keys on arch_patches.yml.

Rationale:

• arch_patches.yml has a strict closed key-set enforced by test-patch-attribution.sh (arch_allowed_keys). The brief scopes model_slugs "onto arch rows", but adding a new top-level arch key would trip the "unknown keys" guard, and the test is the contract (it is not edited in this commit). The fold-in therefore lives in profile_runtime.yml under arch_model_xref, keyed by the same arch: string, so the arch schema stays clean and the existing test stays green. arch_patches.yml remains the C0 authority for requires_trust_remote_code; arch_model_xref is the evidence ledger the generator's trc gate reads. The two MUST agree for in-scope arches (they do: the four on-stack arches were set to evidence-cited false).
• COMPOSE_REGISTRY is a thin param-value bridge imported as a Python module by the test; the captured templates are large structured blocks, so keeping them out of the registry avoids import-surface churn.

profile_runtime.yml contents

• profiles.<name> — for every in-scope vLLM profile (40): compose_path, genesis_equipped (locked v6 discriminator: compose contains _genesis/GENESIS_PIN/GENESIS_ENABLE OR kv_format starts turboquant) + its evidence, and compose_service_template — the token classification the generator applies to the whole shipped service definition: param_slots (env-substituted from the registry), governed_slots (--trust-remote-code — captured, flagged governed, never blind-passthrough, per locked design v6 §88), constants (verbatim — including the ${VLLM_IMAGE:-…} expression, which is NOT substituted), and the two named insertion_points (volumes:, entrypoint:). extends:-based profiles record extends_base and their anchors are inherited-from-extends-base.
• arch_model_xref.<arch> — model_slugs (compose_registry models served by that arch), trust_remote_code, and trust_remote_code_evidence derived from each model's own config.json on this stack.

Per-load-bearing-patch delivery metadata (patches.yml)

Only the ~10 patches with a non-empty load_bearing_when carry a real delivery_mechanism ∈ python_sidecar | site_package_overlay | install_script, plus delivery_spec, a mandatory drift_guard, capability, and foundational. Diagnostics / negative-local-result / Genesis-env patches are delivery_mechanism: none. foundational: true patches hard-refuse on drift-guard failure (weights won't load/boot without them); capability-scoped patches degrade (omit + DEGRADED).

The legacy delivery: boolean block (dockerfile_bake/entrypoint_invoke/genesis) is DEPRECATED and READ-ONLY: it is retained verbatim only because test-patch-attribution.sh still reads it. The generator and all new tooling MUST read delivery_mechanism/delivery_spec instead — do not add new compose-wiring decisions to the boolean block.

Drafter fold-ins (drafters/*.yml)

Each drafter carries speculative_config_template (the verbatim --speculative-config JSON form from the shipped composes, with {N} / {LOCAL_MODEL_PATH} substitution points) and local_model_path (the container path the compose passes; null for the built-in MTP head and for the llama.cpp-scoped GGUF drafter, which the vLLM generator never selects).

Citations

BENCHMARKS.md carries explicit <a id="…"> anchors (#gemma-4-31b-community-experimental, #moe-models) so the patch/profile citations resolve on GitHub even though the rendered heading slug differs (## MoE models (v0.7.3 — preview track) would otherwise slug to #moe-models-v073-preview-track).

Run the audit with:

bash scripts/tests/test-patch-attribution.sh

Reusable core: scripts/lib/profiles/patch_attribution.py (v0.8.0 STEP 2)

The attribution logic that used to live embedded inside test-patch-attribution.sh is extracted into scripts/lib/profiles/patch_attribution.py so the #141 generator (STEP 3) and the test share one implementation. The test now imports it (load, compose_text, gap_declared, reaches, c0_state, the schema/coverage helpers, and the schema key-sets) and asserts identically — same PASS: 61 patch entries, 11 arch rows, 18 calibration seeds summary and the same known-delivery-gaps list.

reaches(root, patch, name_or_abs_path) is now sound (brief v9 correction #4): it probes the comment-stripped service body only (everything from the top-level services: key onward, with whole-line and inline # comments removed) and validates the patch's actual delivery_spec wiring — the declared volume-mount target(s) and/or entrypoint invoke at the wired_at insertion point(s) — instead of a bare patch["id"] in text substring. A patch ID merely named in the file-header banner or the generator's own header WARNING block can no longer register as reached. It accepts a COMPOSE_REGISTRY profile name or an arbitrary absolute path to a compose file.