# Pull-Gate — `scripts/pull.sh` (v0.8.0, #147)

Contributor/maintainer guide for the v0.8.0 Pull-Gate. `pull` takes one HF
repo slug, derives a ModelProfile-shaped spec from the repo's own files,
runs it through the **locked 6-stratum abort taxonomy**, and — only for a
curated, `[D]`-emittable model — hands the validated profile to the #141
compose generator. It is honest about confidence and **never silently
gate-passes**.

The honest scope of this phase is exactly:

> evaluate any safetensors HF repo; pull-and-emit only curated
> (Tier-1) models — and only when the gates pass (or an explicit
> override is accepted)

> ### The authoritative spec is the test, not this doc
> Per the locked v0.8.0 stop-condition, **`scripts/tests/test-pull.sh` is
> the canonical state-machine specification** — an exhaustive,
> network-mocked truth table over the §4.1 nine cells, all six strata,
> stratum ordering, every flag interaction, and golden cases g0–g15. This
> document is an explanatory companion. Where this prose and the test ever
> disagree, **the test is correct**; fix the doc.

For the `[D]` substrate this hands off to, see
[`docs/COMPOSE_GENERATOR.md`](COMPOSE_GENERATOR.md). For the underlying
patch/arch/profile data model see
[`docs/PATCH_ATTRIBUTION.md`](PATCH_ATTRIBUTION.md); for the locked design,
the v0.8.x consolidated design (§3/§4.1/§5.1/§5.2/§7).

---

## 1. Purpose & scope — the two paths

`pull` runs in exactly one of two paths. Path selection in
`run_pull` (`scripts/lib/profiles/pull.py`): an explicit driver `path=`
wins; else `--dry-run` forces Path B; else Path A iff the deriver returns a
Tier-1 curated hit **and** an `--out` target is given; otherwise Path B.

| Path | Trigger | What it does | Calls `[D]`? | Downloads? |
|---|---|---|---|---|
| **A — curated pull-and-emit** | curated (Tier-1) slug + `--out`, not `--dry-run` | full gate → stratum-6 `[D]` dry-run → real `[D]` emit of the validated registry key | yes (read-only dry-run, then real `gc.generate`) | no (download itself deferred — see below) |
| **B — universal evaluate** | any slug, or `--dry-run` | full gate → print the §7-caveated verdict → **STOP** | never | never |

Path A is the only path that ever invokes the #141 generator, and it does
so only after a download-eligible `[C1]` terminal **and** a clean stratum-6
`[D]` dry-run. Path B evaluates *any* safetensors repo (curated or not) and
stops at a verdict — it is structurally incapable of emit/download
(`test-pull.sh` sweeps `vllm/minimal`/`vllm/dual`/`vllm/tools-text` to
assert `emitted` and `compose_text` stay unset on Path B).

### Explicitly OUT of v0.8.0 Pull-Gate (named deferred phases)

| Deferred capability | Deferred to |
|---|---|
| Pull-Emit-Derived: dynamic-`[D]`-from-derived, the `[E]` weight download, static-route fallback for non-emittable profiles | **Pull-Emit-Derived** phase |
| `[F]` capture / classify / trust / loop; `override-accepted` telemetry capture; `--experimental-arch` outcome capture | **Loop** phase |
| The two UX doc tracks + the end-user `recommend` nudge | **post-Pull-Gate** (after this phase) |
| GGUF / `.bin` backend, multi-quant auto-pick, whichllm hardware slice | **v0.8.1** |
| `derived` confidence tier (override-registry promotion/consensus) | **Loop** phase (the `derived` row is RESERVED, still total in §4.1) |

`override-accepted` is a first-class terminal but **not** a gate-pass: this
phase records the state + a telemetry notice and downloads nothing
(`run_pull` returns `ok=True` with a "download deferred to the Loop phase"
notice). `--force-download` is therefore a **NO-OP + notice** this phase.

---

## 2. CLI reference

Observed from `python3 scripts/lib/profiles/pull.py --help` (`pull.sh` is a
thin argv pass-through to it):

```
pull.sh [-h] --profile-like PROFILE_LIKE [--dry-run] [--yes]
        [--force-download] [--experimental-arch] [--trust-remote-code]
        [--hf-home HF_HOME] [--out OUT] [--hardware HARDWARE]
        slug
```

| Flag / arg | Required | Semantics (as shipped) |
|---|---|---|
| `slug` (positional) | yes | HF repo slug, e.g. `org/Model-Name`. |
| `--profile-like PROFILE_LIKE` | **yes** | A curated `COMPOSE_REGISTRY` key supplying the runtime shape. Path A: must name the curated model+variant **and** be `[D]`-emittable. Path B: any vLLM profile, runtime *shape only*. |
| `--dry-run` | no | Force Path B (evaluate only; never emit/download). |
| `--yes` | no | Accept a `confirm→proceed` terminal (§4.1). Without it, a `confirm→proceed` cell is an honest non-pass. |
| `--force-download` | no | Advisory low-confidence `wont-fit` → `override-accepted`. **NO-OP + notice this phase**; the download is deferred to the Loop phase. |
| `--experimental-arch` | no | Bypass **ONLY** `[C0] engine-support-unknown/no-arch-row`. Never bypasses `runtime-incompatible`; Path B only this phase. |
| `--trust-remote-code` | no | Bypass `[C0] needs-trust-remote-code-ack`. |
| `--hf-home HF_HOME` | no | Override the `HF_HOME` resolution chain (`--hf-home > $HF_HOME > $XDG_CACHE_HOME/huggingface > ~/.cache/huggingface`). |
| `--out OUT` | no | Path A only: write the emitted compose here. Its presence (with a curated slug, no `--dry-run`) is what selects Path A. |
| `--hardware HARDWARE` | no | Override detected GPU compute capability (e.g. `8.6` for RTX 3090). Default = `nvidia-smi --query-gpu=compute_cap` detection (the **min** SM across visible GPUs). |

### Exit codes (CLI `main`)

| Code | Meaning |
|---|---|
| `0` | `ok` — download-eligible (Path A emitted, or Path-B clean verdict, or `override-accepted`). |
| `2` | Any honest hard-stop: a stratum-1→6 abort, or a `[C1]` `hard-block`. |
| `3` | A `confirm→proceed` / `override-accepted` terminal not yet satisfied (re-run adding the named flag). |
| `64` | argparse usage error. |

If no GPU is detected and no `--hardware` is given, `run_pull` **fails
closed** at stratum-3 with `hardware-sm-undetermined` rather than fabricate
a fit (the §1 honesty rule).

---

## 3. The 6-stratum abort taxonomy

Evaluated **strictly in order** and **monotonically**: each stratum depends
only on prior strata; nothing downstream rewrites an upstream verdict. The
earliest applicable stratum wins (`test-pull.sh` Section 8 stacks failing
conditions and asserts earliest-wins). `Stratum.DECIDED` (value `0`) means
the run reached a `[C1]` terminal / Path-B verdict with no abort.

| # | Stratum | Code | States / sub-reasons | Bypass flag (if any) |
|---|---|---|---|---|
| 1 | Deriver structured errors | `deriver.derive` | `repo-not-found`, `gated-no-token`, `unsupported-format`, `ambiguous-weight-set`, `quant-dtype-unknown` | none — pick a different repo |
| 2 | `--profile-like` validity precondition | `gates.stratum2_profile_like` | `unknown-profile-like`, `unsupported-runtime-engine`, `profile-not-emittable` (Path A), `profile-mismatch` (Path A) | none — pick another profile |
| 3 | `[C0]` engine-support / runtime / SM | `gates.c0_engine_support` | `engine-supported` · `engine-support-unknown` (+ sub-reason `no-arch-row` \| `runtime-incompatible`) · `needs-trust-remote-code-ack` | see below |
| 4 | `[C2a]` disk pre-gate | `gates.c2a_disk` | `disk-ok` \| `disk-short` | **none — non-negotiable** |
| 5 | Pre-`[B]` generic-dense eligibility | `pull.run_pull` (P4) | `no-fit-model` | **none — non-bypassable** |
| 6 | Path-A `[D]` dry-run | `pull.run_pull` (P4) | `d-refused:<pin-mismatch \| tp-or-kv \| trc \| foundational-drift \| degraded-drift \| scope \| other>` | none |

Then `[B]` (`kv-calc raw_verdict`) produces the raw fit verdict and `[C1]`
(§4.1) maps it to a terminal. On Path A only, a download-eligible terminal
is followed by stratum-6.

### Stratum-3 `[C0]` bypass scoping (exact)

`[C0]` tags which flags (if any) can bypass each non-`engine-supported`
verdict on `.bypassable_by`; `run_pull` only bypasses when **every** tagged
condition is covered by a provided flag (`tags.issubset(provided)`).

| `[C0]` outcome | `.bypassable_by` | Cleared by |
|---|---|---|
| `engine-support-unknown/no-arch-row` | `(--experimental-arch,)` | `--experimental-arch` (Path B only this phase) |
| `engine-support-unknown/runtime-incompatible` | `()` — empty | **nothing** (non-bypassable; includes hardware-SM mismatch) |
| `needs-trust-remote-code-ack` (known arch + `auto_map`) | `(--trust-remote-code,)` | `--trust-remote-code` only |
| `needs-trust-remote-code-ack` + no arch row | `(--trust-remote-code, --experimental-arch)` | **both** flags (subset rule) |

`--experimental-arch` therefore bypasses **only** `no-arch-row`. It does
**not** bypass `runtime-incompatible` (`bypassable_by=()`, asserted by g10
and g14), and it does **not** bypass stratum-5 `no-fit-model` (g11 runs
*with* the flag and still aborts). `disk-short` (stratum-4) and
`no-fit-model` (stratum-5) are non-negotiable: there is no flag, and for
stratum-5 "there is no model to force."

---

## 4. `[C0]` and `[C1]` are design-locked state sets

`[C0]` emits **exactly three** top-level states —
`engine-supported`, `engine-support-unknown`,
`needs-trust-remote-code-ack` (locked design §5.1). `no-arch-row` and
`runtime-incompatible` are **sub-reasons** carried on `C0Result.sub_reason`
(a structured *side field*), **not** new top-level states. Likewise `[C1]`
has **exactly four** terminals — `proceed`, `confirm→proceed`,
`hard-block`, `override-accepted` — frozen in `pull.LOCKED_TERMINALS`;
`test-pull.sh` asserts `LOCKED_TERMINALS == {proceed, confirm→proceed,
hard-block, override-accepted}` and that the enum adds nothing.

`[C0]`'s determination order (`gates.c0_engine_support`) is monotonic:
trust-remote-code (fail-closed: `requires_trust_remote_code ∈ {true,
unverified}` **or** `config.json` `auto_map`) → no arch row → arch row
exists but runtime/hardware not loadable → else `engine-supported`.

---

## 5. `[C1]` — the §4.1 confidence × raw-verdict total function

`[B]` (`kv-calc.raw_verdict`) is pure measurement: `FAIL → wont-fit`,
`TIGHT → fits-constrained`, `PASS → fits-clean`. `[C1]`
(`pull.c1_terminal`, backed by the data table `_C1_TABLE`) is the **single**
authoritative mapping, reproduced verbatim from the locked design §4.1:

| Confidence | `fits-clean` | `fits-constrained` | `wont-fit` |
|---|---|---|---|
| `exact` | **proceed** (silent) | **confirm→proceed** (constraint changed the requested config — user must accept the applied ctx/KV constraint even though math is trusted) | **hard-block** (math trusted; suggest closest-fit) |
| `derived` | **confirm→proceed** (`--yes`; "best-effort, validate post-boot") | **confirm→proceed** (`--yes` + constraint notice) | advisory → `--force-download` → **override-accepted** |
| `estimated-lower-bound` | **confirm→proceed** (`--yes` + "VRAM is a floor; likely under-modeled") | **confirm→proceed** (`--yes` + floor + constraint notice) | advisory → `--force-download` → **override-accepted** |

The table is **total** over `{exact, derived, estimated-lower-bound} ×
{fits-clean, fits-constrained, wont-fit}` (nine cells; `test-pull.sh`
asserts totality and exactly nine entries). Per the locked design §4.1
footnote: **only `exact × fits-clean` is silent**; every other cell needs
`--yes` (a `confirm→proceed` cell) or `--force-download` (a low-confidence
`wont-fit` advisory) to be satisfied. `exact × wont-fit` is an
unconditional `hard-block` — **no flag clears it** (g3 asserts this even
with `--yes --force-download`).

Critically, a flag-bypassed low-confidence model is **not** a silent pass.
After `--trust-remote-code` clears stratum-3 for an
`estimated-lower-bound` model (g4), `[C1]` still lands on
`confirm→proceed` which itself requires `--yes`. Without `--yes` it is an
honest non-pass (`abort_reason` begins `confirm→proceed`, exit 3); the
caveat verdict is only printed once the cell is satisfied. `derived` is
RESERVED for the future override-registry (Loop) phase and is never
assigned in v0.8.0, but its §4.1 row is present so the function stays
total.

Every download-eligible terminal and every Path-B verdict carries the
locked design §7 caveat verbatim (`pull.CAVEAT_S7`):

> boot-fit satisfied; this does NOT guarantee stability under sustained /
> accumulated-context workloads — validate with soak-continuous before
> relying on it (recommend: scripts/soak.sh SOAK_MODE=continuous).

This is presentation-only and changes no decision.

---

## 6. Hardware-SM gating (why a 3090 cannot get a confidently-wrong "fits")

Stratum-3 enforces, as part of runtime loadability:

```
need_sm = max(engine.min_sm, registry.required_sm, arch-kernel SM rule)
```

(`gates._required_sm`). The arch-kernel rule (`gates._ARCH_KERNEL_SM`)
pins `fp8_e4m3` and `turboquant_3bit_nc` (Gemma-TQ3) at SM 9.0. If the
detected/`--hardware` SM is below `need_sm`, `[C0]` returns
`engine-support-unknown/runtime-incompatible` — **non-bypassable**.

Concretely (g14): a curated Gemma-4-31B `fp8_e4m3` / `required_sm:9.0`
profile on a detected RTX 3090 (`sm_86`) aborts at stratum-3
`runtime-incompatible`; `--experimental-arch` does **not** bypass it; the
same profile on `sm_90` clears the SM gate (proving it *is* the SM gate).
Without this check a 3090 would receive a false "fits" verdict — exactly
the §1 confidently-wrong outcome the design forbids.

---

## 7. How each path consumes `--profile-like`

`--profile-like` is REQUIRED on both paths but consumed differently:

| Aspect | Path A (curated pull-and-emit) | Path B (universal evaluate) |
|---|---|---|
| What the profile supplies | the **full** registry key (the validated key is handed to `[D]`) | runtime **shape only**: `engine`, `kv_format`, `tp`, `max_ctx`, `max_num_seqs`, `mem_util`, topology |
| Model/variant match | profile `model` must equal the curated resolved model **and** `weights_variant` must equal the matched variant, else stratum-2 `profile-mismatch` (g3b) | not checked — the pulled repo's own files determine weight format/quant |
| `[D]`-emittable required | yes — reuses `[D]`'s scope-gate (`engine.type==vllm` ∧ `profile_runtime` entry exists ∧ `genesis_equipped==false`); a Genesis/TQ3 profile (`vllm/dual-turbo`) → stratum-2 `profile-not-emittable` (g0) | no |
| `weights_variant` compat | Path-A only (`[C0]` checks the curated variant against arch constraints) | n/a — uses deriver-resolved `weight_format`/quant |
| `drafter` | from the curated profile | `none` for non-curated (drafter profiles expose `model_compat`, not arch-compat) |
| Non-vLLM `--profile-like` | refused stratum-2 `unsupported-runtime-engine` (g13: `llamacpp/default`, `engine=llama-cpp-local`, `mem_util=None`) | same — refused on both paths |

---

## 8. `[D]` handoff & the `--project-directory` requirement

On Path A, after a satisfied download-eligible terminal, `run_pull` runs
the stratum-6 `[D]` dry-run via the real `generate_compose.generate`
(pure — no container). If `[D]` refuses at one of its later points (pin
mismatch / TP·KV / trc / foundational-or-degraded patch drift), that is a
**stratum-6 Path-A abort** (`d-refused:<token>`) and the run is **not**
reported download-eligible — stratum-2's scope-gate is necessary but not
sufficient for `[D]` emit (g15: an injected refusing runner →
`d-refused:foundational-drift`, `ok=False`, no file written).

On a clean dry-run, the validated key's compose text is written to
`--out`. The emitted compose's relative overlay mounts resolve from the
**compose file's own directory**, so generated composes are **not
relocatable** — `run_pull` surfaces a notice that the consumer must run:

```
docker compose --project-directory <repo-root> -f <out> up
```

See [`docs/COMPOSE_GENERATOR.md`](COMPOSE_GENERATOR.md) for the full
`--project-directory` rationale and the governed-slot invariant (the
in-scope Path-A emitted body contains zero `--trust-remote-code`, asserted
by `test-pull.sh` via `patch_attribution.service_body()==0`). For a
`fits-constrained` Path-A run, `[D]` emits the chosen registry profile
**unchanged**; the run prints a "known effective-cap warning" (vLLM
internally caps effective KV on this hardware) — **no compose config is
rewritten** (g2 asserts the notice says "no compose config rewritten" and
not "applied constraint").

---

## 9. Golden cases (the test's truth table)

`scripts/tests/test-pull.sh` is the canonical spec. Golden cases as
asserted there:

| Case | Path | Asserted behavior |
|---|---|---|
| g0 | A | `vllm/dual-turbo` (genesis_equipped) → stratum-2 `profile-not-emittable` before `[C0]` |
| g1 | A | curated + emittable, gate-passing, clean `[D]` dry-run → compose emitted (integration analogue of the satisfied g2) |
| g2 | A | curated effective-capped → `exact × fits-constrained` → `confirm→proceed`; `--yes` → "known effective-cap warning" (no rewrite) → `[D]` emit; without `--yes` → honest non-pass, no file |
| g3 | A | curated too big → `exact × wont-fit` → `hard-block`; no `[D]` even with `--yes --force-download` |
| g3b | A | model/variant mismatch (`vllm/gemma-bf16-mtp` vs curated Qwen) → stratum-2 `profile-mismatch` |
| g4 | B | Llama, `trc:unverified` → `needs-trust-remote-code-ack`; `--trust-remote-code` → `[C1]` `confirm→proceed` (still needs `--yes`); `+ --yes` → Path-B caveat verdict, no `[D]` |
| g5 | B | `no-arch-row` → stratum-3; `--experimental-arch` (+ `--yes`, eligible) → Path-B verdict + bypass notice |
| g6a | B | known arch + `auto_map` → `needs-trc-ack`, `bypassable_by == ['--trust-remote-code']` only; `--experimental-arch` alone does not clear it |
| g6b | B | no-arch-row + `auto_map` → `bypassable_by == {--trust-remote-code, --experimental-arch}`; needs **both** (subset rule) |
| g7 | B | 200 GiB model, 2 GiB free, clean `[C0]` → stratum-4 `disk-short`; `[B]` never ran (no fit verdict) |
| g8 | B | curated + `--dry-run` (with `--out`) → Path B, no `[D]` emit, no file written |
| g9 | B | derived dense → `estimated-lower-bound` confidence, real verdict; `--calibration` stays 22/22 |
| g10 | B | `loads:false` pin → `runtime-incompatible`; `--experimental-arch` does **not** bypass |
| g11 | B | SWA-only / MoE-on-known-arch → `[C0]` stays `engine-supported` → stratum-5 `no-fit-model`; `--experimental-arch` does **not** bypass |
| g12 | — | no `*.safetensors` → `unsupported-format`; multiple sets → `ambiguous-weight-set`; HF 404 → `repo-not-found`; stratum-1 emits **no** fit verdict |
| g13 | both | `--profile-like llamacpp/default` → stratum-2 `unsupported-runtime-engine` before `[C0]`/`[B]` |
| g14 | A | Gemma `fp8_e4m3` / `required_sm:9.0` on `sm_86` → stratum-3 `runtime-incompatible`; non-bypassable; clears on `sm_90` |
| g15 | A | stratum-2 + `[C1]` download-eligible but `[D]` dry-run refuses → stratum-6 Path-A abort, **not** download-eligible |

Run the canonical spec from the repo root:

```
bash scripts/tests/test-pull.sh
```