Define the diagnostic-flag invariant by what cannot force a rebuild

Section 4 justified rejecting warn-pedantic from stanc_options partly on
the grounds that a supplied diagnostic evaporates the same way an
injected one does: build once, warn once, and never warn again once the
record matches. Read as a general rule that lands on --warn-uninitialized
and every other supplied diagnostic, and taken that way it asks for
stanc to be rerun on every construction of an up-to-date model.

The two cases are not the same. A compared option cannot evaporate in the
way that matters, because turning it on mismatches the record and
rebuilds; only an option that cannot force a rebuild needs a mechanism of
its own. So the invariant is narrower than "a diagnostic always
re-emits": asking for something you did not have before never yields
nothing. warn-pedantic satisfies it through section 8's rerun,
warn-uninitialized through being compared.

That leaves a real asymmetry on an identical repeat call, where pedantic
warns and a supplied diagnostic does not. Named rather than defended as
ideal. Buying it would mean cmdstanr knowing which stanc flags are
diagnostic-only per CmdStan version, which is the per-option semantics
canonicalization already declines, and a misclassification is silent in
the unsafe direction: treat a codegen flag as diagnostic and a needed
rebuild is skipped. It is also what a C compiler does with -W flags and
an up-to-date object file.

The warn-pedantic rejection now rests on the one-channel rule instead,
where pedantic is the case in which two channels differ in kind rather
than in spelling, one injected and uncompared and one supplied and
compared.

Author: jgabry

dev-notes/compilation-state.md

@@ -594,21 +594,38 @@ artifact while an old record's `_supplied` goes on matching, so nothing would
 rebuild. The bump is what forces it.
 
 **An injected option still applies; not comparing it only means it cannot force a
-rebuild.** Where the option's whole purpose is to produce output — `--warn-pedantic`
-is the only current case — the operation still has to happen on a model that is
-already up to date, or the user's request silently evaporates (§5).
-
-**Every `stanc_options` spelling of `--warn-pedantic` is therefore rejected**, with an
-error naming `pedantic = TRUE` — `list("warn-pedantic")`, `list("warn-pedantic" = TRUE)`
-and `list("warn-pedantic" = FALSE)` alike. The named `FALSE` is refused too because it
-emits nothing today (logical `FALSE` leaves a flag out, #1251) while `pedantic = TRUE`
-still injects, so it reads as a way to switch pedantic off and is not one.
-
-Supplied rather than injected, the flag would be *compared*: the first build warns, the
-second construction matches the record, nothing rebuilds, and the warnings never appear
-again — the same evaporation through the door the rule above does not cover. One
-spelling that is already handled is cheaper than a second rule. `name` and
-`filename-in-msg` stay supplyable: neither has a dedicated argument, and
+rebuild.** The invariant this obliges is narrower than "a diagnostic always re-emits":
+*asking for something you did not have before never yields nothing.* A compared option
+satisfies it for free, since turning it on mismatches the record and rebuilds. An
+uncompared one cannot, and needs a mechanism of its own — for `--warn-pedantic`, the
+only current case, §8 runs the check on a model that is already up to date.
+
+That leaves an asymmetry, accepted rather than defended as ideal. `pedantic = TRUE` warns
+on every construction, including an identical repeat, because an uncompared option has no
+build to attach to and "every time" is the only alternative to "never". A supplied
+diagnostic such as `--warn-uninitialized` warns whenever a build happens and is quiet on
+an identical repeat. Warning there too would be better; it is not worth what buying it
+costs (below), and it is the behaviour of every C compiler with `-W` flags and an
+up-to-date object file, so it is not a surprise we are introducing. Both routes deliver
+the flag's effect the moment the caller asks for it; only the nothing-changed case
+differs.
+
+**Extending warn-always to supplied options is refused.** It would need cmdstanr to know
+which stanc flags are diagnostic-only, per CmdStan version — the per-option semantics
+this section declines below for canonicalization, arrived at from the other direction. A
+misclassification is also silent and points the wrong way: treat a codegen flag as
+diagnostic and a needed rebuild is skipped.
+
+**`--warn-pedantic` is rejected from `stanc_options`**, with an error naming
+`pedantic = TRUE`, matched on occurrence rather than by value (§3). This is the
+one-channel rule of §3 and §6, and pedantic is the case where two channels would differ
+in *kind* rather than in spelling: `pedantic = TRUE` is injected and not compared, the
+same flag through `stanc_options` is supplied and compared, so one warns on every call
+and the other only on a build. The named `FALSE` has a second reason of its own: it emits
+nothing today (logical `FALSE` leaves a flag out, #1251) while `pedantic = TRUE` still
+injects, so it reads as a way to switch pedantic off and is not one.
+
+`name` and `filename-in-msg` stay supplyable: neither has a dedicated argument, and
 `filename-in-msg` is deliberately caller-overridable (§9). `allow-undefined` does not,
 being the flag `user_header` implies (§3).